Tests are the cornerstone of Assertible and used to check and validate HTTP requests and responses. In a nutshell, a test is a single HTTP request which utilizes assertions and configuration data to prove an endpoint is working as expected.

Tests are designed to be small, reproducible, and deterministic so that there no false-positives and error messages can be reported accurately.


Fig 1.1 Tests for an API

Contents

Create a new test

In many areas of the dashboard, there is a Create Test button. For example, tests can be created from the web service overview:

Fig 1.1 Create test for a web service

Or by using the "+" plus button on an endpoint card:

Fig 1.2 Create test from API

When a new test is created, many configuration options are reasonably set to default values such as asserting a 200 OK endpoint.

Configuring a Test

Tests can be configured from the test settings view. From there, you can edit the name, request settings, variables, more.

Sections


Configure an API test in Assertible

Basic test info

Basic info is all the settings for a test that don't affect the request. All of these settings are available at the top of any test view. The following fields can be updated:

Test Name - Name for your test! (Uniqueness not enforced). In our experience, the test name should be as specific as possible. This helps identify error messages quickly.

Description / Notes - A short description of your test, so other people on your team will know what it's for. GitHub Flavored Markdown is supported. Sometimes it's useful to put a use-case or expected input/output in this field.

Tip! If you import an API from a Swagger / OpenAPI definition, many values are extracted like the description.

Request configuration

At it's core, a test is a single HTTP request. The reason Assertible only utilizes a single request for a test is:

  • Tests are hermetic
  • Reproducibility
  • Deterministic
  • Better failure messages.

Everything about your test's HTTP request can be configured from the test view. By default, a new test will have enough information to be runnable. You can additionally configure the following:

NOTE: You can chain multiple HTTP requests by using setup steps

HTTP Method

The HTTP method for the request. Can be GET, PUT, POST, PATCH, DELETE, HEAD, OPTIONS.

HTTP Scheme

The HTTP scheme. Can be http or https.

HTTP version

Use can use a specific HTTP version. The default is 1.1; other options are 1.0, 0.9.

Host (base URL)

The base URL is a static field from the web service default environment.

The base URL is visible but cannot be changed.

Endpoint

The path part of the URL. For example, in assertible.com/signup, /signup would be the endpoint.

Authentication & Authorization

Authentication used for the request, if necessary. This field is designed to override any authentication data specified for the web service

Supported auth types are Basic Authentication, Digest Authentication, oAuth v1.0a, oAuth v2.0, and API Token Auth.

If you have an auth type that is not supported, you can probably set any auth headers manually.

Use cookies

If checked, all HTTP requests invoked by a test including setup steps.

For example, if you have a setup step that calls a /login endpoint, and requires Cookie headers to be persisted for all subsequent requests.

Max redirects

The maximum number of HTTP redirects allowed before aborting the request. The default is 2, maximum is 100.

Variables

Variables provide a way for you to insert dynamic data into certain parts of a request, like the endpoint. For

example, let's say you're are testing an endpoint, /tests/{{testid}}. You can populate the {{testid}} part before the test is run. In the image below, {{testid}} will be subtituded with 12345:

Fig 1.6 Route Parameters

In the above example, every time the test is run the final URL will be: https://assertible.com/tests/12345.

Variables can be used in the following parts of a test:

You can splice a variable into the endpoint by using mustache-like template syntax: {{...}}. You can then define that variable in the 'Variables' section of your test's configuration.

Note: If a variable is used, but not defined, the test will fail. The test result will show you the reason for the failure.

Dynamic variables

In many cases, you may wish to fetch or dynamically create variables using pre-requisite data from an HTTP request or at random. In these cases, you can use setup steps to describe how to fetch and populate variables before your test is run

Query parameters

Add query parameters to the request.

Note: No url or percent encoding is done by Assertible.

Request headers

Add custom headers to the request. This is useful for manually setting auth other service specific information.

Request body

Set a request body.

Note: No url or percent encoding is done by Assertible.

Setup steps

Setup steps allow you to create test variables before your test is run by capturing them from an HTTP request or generating random data. There are two types of setup steps:

There are many use-cases for setup steps, like fetching an auth token to use in your test, or logging into a website to create a session cookie. In all of these cases, you can use setup steps to describe how to fetch and populate variables before your test is run.

Setup steps can be configured on the Setup step tab of the test configuration page.

Fig 1.6 Configure Setup Step

HTTP request generator

The HTTP Request setup allows you to make an additional HTTP request before the main test is run. You can capture data from the HTTP request, save it in a test variable, and use it throughout your tests.

Examples

For example, if you want to test a POST request to create an entity and a subsequent GET request to fetch the entity, you would have a test comprised of two steps:

  • POST /item in your setup step, and save the id from the response.
  • GET /item/{{id}} in your test by using the id variable.

Setup steps can also be used without populating any variables. For example, if you want to perform a test as a logged in user, you would have a login request in your setup step:

  • POST login form to /login in your setup step
  • GET /account or POST a form to /form in your test step

NOTE: Ensure the use cookies setting is enabled if you want sessions to persist between your setup step and test.

Random generator

A Random setup step allows you to generate random data, save it to a test variable, and use it throughout your tests. This is useful in cases where you don't need to fetch any specific data, but you need to, for example, populate a userName query parameter.

There are three different types of random data you can generate with this setup step:

  • Random Text
  • Random Number
  • Random UUID

Tests and assertions

Fig 1.4 Tests and Assertions

You can add and manage your test's assertions on the Assertions tab of a test's configuration view. For more information on how to configure assertions, check our assertions documentation.

Test Badges

Each test has an embeddable badge for displaying the current status of only that test's assertions. You can use this to communicate current test states with team members or within documentation pages. The badge will display the current test result state at any given time.

Fig 1.5 Embeddable test badges

You can also create a test badge for a specific environment like staging or production by using the environment query parameter on the trigger url.

Badges can also be created for an entire web service.

Embedding badges

You can find and copy the badge image URL on any test's page, and use it outside of the dashboard. More specifically, there is a copy button next to the badges in the dashboard which will copy the markdown for the badge directly to your clipboard. Here are a few examples of using badges:

Badge monitoring test on production

https://assertible.com/tests/{{test-id}}/status?api_token={{token}}

Badge monitoring test on staging

https://assertible.com/tests/{{test-id}}/status?api_token={{token}}&environment=staging

Markdown:

[![Assertions Status](https://assertible.com/tests/{{test-id}}/status?api_token={{token}})]

HTML:

<img src="https://assertible.com/tests/{{test-id}}/status?api_token={{token}}" alt="Assertions Status" />

Automate your QA pipeline

Define and test your web service with Assertible Track and test API deployments across environments Schedule API monitoring and failure alerts

Reduce bugs in web applications by using Assertible to create an automated QA pipeline that helps you catch failures & ship code faster.

Sign up for free