REST test suite

You can define a suite of tests for your REST API using Emblazon. This is useful for testing your API as you develop it, or for testing an existing API.

Getting started

You can create a new test suite by typing /rest into a note and selecting the REST Test Suite option.

Adding a test

You can add a test to your suite by clicking the Add Test button on the top left of the widget.

Changing the name

To change a tests name, click on the name of the test and type in the new name.

Setting up the request

You setup the details of the request in the "Request Definition" section of the test. Here you can specify the HTTP method, URL, headers, url parameters and body of the request.

Validating the response

Rather than specifying assertions for the response, you can specify a template to validate the response.

At it's simplest this can be the expected text of the response.

To add more flexibility to your validation, you can use JSON Validation to validate the response. This is basically a template that maps back to a zod schema.

Running a test suite

You can run tests individually by clicking the Run Test button on the test. You can also run all the tests in a suite by clicking the Run All button on the top right of the widget.

Shared parameters

If there is a value you want to use in multiple tests, you can define a shared parameter. This is useful for things like the base URL of your API, or an API key.

Any shared parameter can be referenced in a test by using the syntax {{parameter_name}}. Under the hood this is resolved as a Handlebars template.

BASE_URL

As this is a common use case, there is a special handling for the BASE_URL shared parameter.

The BASE_URL shared parameter is automatically added to the start of any URL that doesn't contain "://". For example the full URL that will be used in the following test is https://api.emblazon.app/open/echo:

It can still be referenced using the {{BASE_URL}} syntax.