Table of Contents

• Why a Testing DSL?
• Installation
• Comparison with Other Testing Libraries
• Test Definition Syntax
• What is JSONPath?
• Referencing Values and Dynamic Inputs for Subsequent API Requests
• Date Assertions
• Using Environment Variables
• Contributing and Help
• License

Why a Testing DSL?

• Teams should not be forced to write Javascript (Postman), Groovy (Katalon), or Java (Rest-Assured) just because they want to test an API for a web system.
• We should be able to create interactive builders that generate this underlying DSL (Domain Specific Language). So you shouldn't even need to write this DSL by hand in the future.
• We should be able to use the same script for both individual tests and load testing.
• We should still be able to persist these tests in our version control and collaborate on them with our peers.
• Inspired by Local-First software principles.

Installation

To install testkit, kindly follow one of the options below (click on the toggle):

[!NOTE]

Once testkit is installed succesfully, run the testkit --help command for all CLI commands and options.

Comparison with Other Testing Libraries

Before delving into the details of testkit and its functionality, let's compare it to other testing libraries to highlight it's elegance, cleanliness, and simplicity. By showcasing the differences, you will see how testkit provides a more streamlined and user-friendly approach to API testing. To illustrate this, we will rewrite a Cypress test as seen below:

Cypress ⤵️

describe('TODO API testing', () => {
  let todoItem;
  it('fetches Todo items - GET', () => {
    cy.request('/todos/').as('todoRequest');
    cy.get('@todoRequest').then((todos) => {
      todoItem = todos.body[0]['_id'];
      expect(todos.status).to.eq(200);
      assert.isArray(todos.body, 'Todos Response is an array');
    });
  });

  it('Deletes Todo items - DELETE', () => {
    cy.request('DELETE', `/todos/${todoItem}`).as('todoRequest');
    cy.get('@todoRequest').then((todos) => {
      expect(todos.status).to.eq(200);
      assert.isString(todos.body, 'todo deleted!');
    });
  });

  it('Adds Todo item - POST', () => {
    cy.request('POST', '/todos/', { task: 'run tests' }).as('todoRequest');
    // Adds new Todo item by defining Todo name
    cy.get('@todoRequest').then((todos) => {
      expect(todos.status).to.eq(200);
      cy.wrap(todos.body).should('deep.include', {
        task: 'run tests',
        completed: false,
      });
    });
  });
});

Testkit ⤵️

---
    - title: fetches TODO items - GET
      GET: /todos/
      asserts: # Asserts accepts a list of expressions, usually via JSONPaths to identify the items being referred to.
        - ok: $.resp.status == 200  # Rely on an expressions library for parsing expressions
        - array: $.resp.json
      exports: # Values which should be accessible to future steps.
        todoItem: $.resp.json[0]._id

    - title: deletes TODO items - DELETE
      DELETE: /todos/$.stages[0].todoItem # Relative syntax exists: $.stages[-1].todoItem, -1 means one stage before me
      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 == false

Testkit offers a clean and intuitive syntax that simplifies the process of defining and executing API test scenarios.

Test Definition Syntax

Testkit uses 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 <token>
    Content-Type: application/json
    Allowed-Methods:
      - GET
      - POST

- title: Create User - POST
  POST: /users/
  json:
    name: John Doe
    age: 25
    email: john.doe@example.com

- 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 powerful query language designed for navigating and extracting data from JSON documents. It provides a concise syntax that allows you to specify paths to specific elements within a JSON structure, facilitating data access and manipulation. In testkit, JSONPath expressions are extensively used to extract data for assertions and exports. To illustrate how JSONPath works, consider the following examples:

• $.user.name: This expression retrieves the name of a user from the top-level object in the JSON document.
• $.todos[0].task: This expression accesses the task property of the first element in an array of todos.
• $.todos[*].task.description: This expression retrieves the description property of all tasks within the todos array.

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 testkit facilitating the extraction of data for performing assertions and capturing exports during the testing process.

[!NOTE]

To learn more about JSONPaths, please take a look at the official docs.

Referencing Values and Dynamic Inputs for Subsequent API Requests

The exports field in testkit 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].<VAL> 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. testkit understands that it should substitute the reference 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. 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 in testkit 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.

Using Environment Variables

Testkit supports environment variables in two ways (.env file and CLI configuration). These approaches allow users to configure and customize their test scripts without exposing sensitive data and making it easier to switch between different environments and scenarios seamlessly.

Configuring the Environment Variables

Using a .env file involves creating a text file named .env in the test script's directory and defining KEY=VALUE pairs for each environment variable. testkit automatically loads these variables from the .env file during test execution, like so:

APIURL=https://api.example.com
EMAIL=user@example.com
PASSWORD=mysecretpassword
USERNAME=myusername
APIKEY=mysecretapikey

Setting environment variables directly is done via the command line or the test environment, like so:

APIKEY=SECRETAPIKEY testkit test --file test.tk.yaml

Utilizing the Environment Variables

To utilize environment variables in testkit, you can access them using the following syntax: $.env.<VAL>, where <VAL> represents the name of the specific environment variable you want to use. This allows you to easily reference and incorporate the values of these environment variables within your test scripts, enabling greater flexibility and adaptability without hardcoding sensitive information or configuration details. Here's an example:

- title: Register
  POST: '$.env.APIURL/users'
  headers:
    Content-Type: application/json
    X-Requested-With: XMLHttpRequest
  json: '{"user":{"email":"$.env.EMAIL", "password":"$.env.PASSWORD", "username":"$.env.USERNAME"}}'
  asserts:
    - exists: $.resp.json.user
    - exists: $.resp.json.user.email
    - exists: $.resp.json.user.username
    - exists: $.resp.json.user.bio
    - exists: $.resp.json.user.image
    - exists: $.resp.json.user.token

In this example, testkit performs a POST request to the API URL specified in the environment variable APIURL. The user information for registration is taken from the environment variables EMAIL, PASSWORD, and USERNAME, allowing for easy customization and reusability of the test script across different environments.

Contributing and Help

To contribute to the development of this project or request help from the community and our team, kindly do any of the following:

• Read our Contributors Guide.
• Join our community Discord Server.
• Create a new issue in this repository.

License

This repository is published under the MIT license.