API Tests Page

In this guide, you will learn how to effectively navigate through the API Tests page on the APItoolkit dashboard and maximize all the powerful features accessible in it.

On this page, you can define and run different API tests (synthetic monitors) with multiple steps to monitor endpoints from your API at scheduled intervals.

Get Started

To get started, kindly follow the steps below:

• Click on the + new tests button to create a new test.

• Enter your preferred title and description.

• If you want to run the test at intervals, click the Schedule toggle, and select your preferred interval.

• Click the Create Test button and you will now be redirected to a new page.

• Next, click on the Code toggle to select the UI editor mode (use the input fields) or manual code mode (manually write the tests with a YAML DSL).

• Add as many steps as you want for this test and click the Run all button to preview the results at the right section of the page.

• Once done, click the Save button to save the test.

Test Definition Syntax

We use a YAML-based syntax for defining test scenarios. Each scenario consists of multiple stages, where each stage represents a specific API request and its associated assertions. Below is an example of the YAML syntax for defining API tests:

---
- title: fetches TODO items - GET
  GET: /todos/
  asserts:
    - ok: $.resp.status == 200
    - array: $.resp.json
  exports:
    todoItem: $.resp.json[0]._id

- title: deletes TODO items - DELETE
  DELETE: /todos/$.stages[0].todoItem
  asserts:
    - empty: $.resp.json.todos
    - string: $.resp.json

- title: Adds Todo item - POST
  POST: /todos/
  json:
    task: "run tests"
  asserts:
    - ok: $.resp.status == 200
    - ok: $.resp.json.task == "run tests"
    - ok: $.resp.json.completed

In the example above, the YAML test file defines three test items fetching TODO items using a GET request, deleting a specific TODO item using a DELETE request, and adding a new TODO item using a POST request. The YAML file consists of a list of test scenarios. Each scenario represents an API request and contains the following fields:

Kindly click each toggle below to learn more about each field.

  # POST request
  - title: Adds Todo item - POST
    POST: /todos/

  # GET request
  - title: Fetches Todo items - GET
    GET: /todos/
  

  - title: Fetches Todo items - GET with headers
    GET: /todos/
    headers:
      Authorization: Bearer 
      Content-Type: application/json
      Allowed-Methods:
        - GET
        - POST
  

  - title: Create User - POST
    POST: /users/
    json:
      name: John Doe
      age: 25
      email: [email protected]
  

- title: Fetches Todo items - GET
  GET: /todos/
  asserts:
    - ok: $.resp.status == 200
    - array: $.resp.json
    - ok: $.resp.json[0].task == "run tests"

- title: Fetches Todo items - GET
  GET: /todos/
  exports:
    todoItem: $.resp.json[0]._id

What is JSONPath?

JSONPath is a query language used to select and extract data from JSON files. It provides a concise syntax that allows you to specify paths to specific elements within a JSON structure, facilitating data access and manipulation. JSONPath expressions are extensively used to extract data for assertions and exports. To illustrate how JSONPath works, consider the following examples:

The syntax of JSONPath expressions includes several key components:

By employing JSONPath expressions, you can precisely pinpoint the desired data within a JSON structure. These expressions play a vital role in facilitating the extraction of data for performing assertions and capturing exports during the testing process.

Referencing Values and Dynamic Inputs for Subsequent API Requests

The exports field not only allows you to capture values from the API response but also provides a powerful mechanism for referencing those values and dynamically generating inputs for subsequent API requests.

By capturing relevant data using the exports field, you can store it as an export and easily refer to it in the later stages of your test scenario. This capability becomes particularly useful when you need to access specific values extracted from the response and utilize them in subsequent API requests.

For example, let's say you retrieve an ID from an API response in one stage using the exports field:

- title: Fetch User - GET
  GET: /users/1
  exports:
    userId: $.resp.body.id

To reference this userId export in a subsequent API request, you can use the $.stages[n]. syntax:

- title: Update User - PUT
  PUT: /users/$.stages[0].userId
  json:
    name: 'John Doe'

In the above example, the userId captured in the first stage is accessed using the syntax $.stages[0].userId. The reference will substituted with the corresponding value during execution. You can also use relative references like $.stages[-n] which refers to the exports of the nth stage before the current stage. Here's an example:

- title: deletes TODO items - DELETE
  DELETE: /todos/$.stages[-1].todoItem #-1 means one stage before me
  asserts:
    - string: $.resp.json.task
    - ok: $.resp.json.id == $.stages[-1].todoItem

By referencing specific values captured in previous stages, you can establish dependencies between different API requests and ensure seamless data flow throughout your test scenario. This flexibility allows you to build more comprehensive and realistic tests, simulating complex user interactions or workflows.

Date Assertions

To make date assertions, you'll need to provide the date string and the date format, like so:

- title: Get User Profile - GET
  GET: /user/jon_doe
  asserts:
    - date: $.resp.json.createdAt %Y-%m-%d %H:%M:%S %Z

In the example above, we first provide a JSONPath to the date followed by the date's format. We use chrono crate's formatting tokens to represent different components of a date. Here are some commonly used formatting tokens:

Here are some example dates and their correct formats:

In the table above, the "Date String" column represents the example date string, and the "Format" column contains the corresponding format string to parse the given date string.