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/api/v1/examples/login
    body: {
      "username": "testuser",
      "password": "password"
    }
  response:
    status: 200
    extract:
      - name: auth
        field: auth.token
stages:
  - request:
      url: https://api.jikken.io/api/v1/examples/status
      headers:
        - header: Authorization
          value: Bearer ${auth}
    response:
      status: 200
  - request:
      url: https://api.jikken.io/api/v2/examples/status
      headers:
        - header: Authorization
          value: Bearer ${auth}
    compare:
      url: https://api.jikken.io/api/v1/examples/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.

Check out our Example Tests section for more test examples.

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.

Next steps

Want to learn more?

Check out our Tutorial series for a guided learning experience, or dive headfirst into our Test Format and CLI Commands references to explore all that Jikken has to offer.