Quick Start

Before you can use Jikken, you’ll need to download and install the CLI tool. We provide several easy ways to get it: you can use Cargo, Homebrew/Linuxbrew, or Chocolatey. We also provide installation instructions for Linux, MacOS, and Windows, along with prebuilt binaries for download (Linux, MacOS, Windows) from our Github releases.

Creating Tests

Jikken test definitions use the .jkt file extension. In its simplest form, a test definition requires two things: a request to make, and some form of validation to perform on the response.

request:
  url: https://google.com
response:
  status: 301

The above test will call https://google.com and only pass if the response status code from the server is 301. Any other status code will cause the test to fail.

Tests can also be much more complex:

name: Multistage Test
tags: multi
setup:
  request:
    method: Post
    url: https://api.jikken.io/v1/test_login
    body: {
      "username": "testuser",
      "password": "password"
    }
  response:
    status: 200
    extract:
      - name: auth
        field: auth.token
stages:
  - request:
      url: https://api.jikken.io/v1/test_status
      headers:
        - header: Authorization
          value: Bearer ${auth}
    response:
      status: 200
  - request:
      url: https://api.jikken.io/v2/test_status
      headers:
        - header: Authorization
          value: Bearer ${auth}
    compare:
      url: https://api.jikken.io/v1/test_status
    response:
      status: 200
      ignore:
        - user.lastActivity

The above test provides a test name, which will be displayed in the CLI and dashboard. It has a setup stage where it attempts to login. If the login succeeds, an auth bearer token is extracted from the response JSON.

Then it has two normal stages. The first stage calls a status API, leveraging the API token extracted in the setup step. It validates that the response code is a 200.

The second stage calls v2 of the status API, passing in the same auth token. It then compares the results of v2 and v1 of the APIs, checking the response body and status codes. Since we expect a field to be present in the v2 response that doesn’t exist in the v1 API, we list that field in the ignore definition. Jikken then prunes the specified nested JSON field before comparing the response bodies. It also verifies that both APIs returned a 200 status code.

For more examples of tests, see our Test Format documentation or the example_tests folder in our git repo.

Checking Tests

Before executing your tests, you can use the jk dryrun command to do a dry run. This allows you to see what steps will take place without performing any API calls, and can be useful for finding mistakes in your test definition. The example below shows a dry run of the more complex test definition in the previous section.

Running Tests

When you’re ready to actually run your defined tests, use the jk run command. The default behavior runs all tests in the current directory, but you can also specify a path or single file, filter tests by tags, and search recursively for tests to run.