A test is the cornerstone of Assertible and where you'll spend most of your time. Creating a basic test is trivial, and there are options to configure nearly every piece of an HTTP request.

Contents

Create a new test

Across the Assertible Dashboard you'll see several places to create a test. They all work similarly - eg, if you click Create test from the web service Manage drop-down, the new test will be created for the corresponding web service.

In general, tests are created with a set of default values such as asserting a 200 OK endpoint.

Creating tests for a web service

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

Fig 1.1 Create test for a web service

From a web service page you can also quickly create a test for any endpoint:

Fig 1.2 Create test from API

Configuring a Test

Tests can be configured from their settings view. From there, you can edit the name, request settings, and much, much more.

Sections

Fig 1.3 Configuring a test

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)

Description - A short description of your test, so other people on your team will know what it's for. GitHub Flavored Markdown is supported. Tip! If you import an API from a spec, these may be pre-populated for you.

Request configuration

Everything about your test's 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:

Method

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

Scheme

The HTTP scheme. Can be http or https.

Host (base URL)

The base URL is a static field from the Web Service default Environment. The base URL 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. Supported auth types are Basic Authentication, Digest Authentication, oAuth v1.0a, oAuth v2.0, and API Token Auth. You can also set any auth headers manually, if you need an auth that is not supported. Tip! If you import an API from a spec, these may be pre-populated for you.

Use cookies

If checked, the request will store the cookie.

NOTE: cookies are persisted between all HTTP requests invoked by a test including setup steps.

HTTP version

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

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, /users/{{userId}}. You can populate the {{userId}} part before the test is run. In the image below, {{userId}} 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/users/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 for the request. This is useful for manually setting auth other service specific information.

Request body

Set a body for the request.

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. Learn more about the two types of setup steps below:

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.

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

Fig 1.6 Configure Setup Step


Heads up! You can currently only enable one setup step per test. If you have a use-case for multiple setup steps on a single test, let us know.

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 POSTing an entity to an API and then GETing that 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 allows you to generate random data, save it to a test variable, and use 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 any test page. More information on how to configure assertions can be found here.

Assertions are 'snapshotted' with test results. If you delete or update an assertion it won't retroactively effect or change the test result.

Analyzing test results

Test results will be the core of your interaction with Assertible. They'll give you insight into the details about your web service HTTP requests, the reason specific assertions failed or passed, and much more. Test results can be viewed on the "Results" tab of a web service page.

Fig 1.5 Analyzing test results

Test Badges

Each test has an embeddable badge for displaying the current status of your 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

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:

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" />