Getting Started

Jikken is a CLI tool designed to make it easy for automated API testing to integrate with source control. It accomplishes this by providing a simple yet powerful test definition file format. These test files can be stored in your source repository alongside the application and services you’re testing, or be kept in their own separate repos as your project requires. Jikken provides the ability to execute API calls based on these definitions, along with features to help create and validate your test files. It also has capabilities to simplify some common testing needs for modern CI/CD deployment practices.

Command-line interface

Jikken’s CLI is accessed via the jk command. Typing jk with no arguments will provide a description of all available commands.

Simple test definition

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

Requests can also be compared against each other. This is convenient for testing new versions of services against older ones, as in regression testing.

request:
  url: https://google.com
compare:
  url: https://google.com

You can also compare them against both each other and a known good state.

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

This validates that the response status is 301 for both the request and the compare APIs.

request:
  url: https://google.com
compare:
  url: https://google.com
response:
  status: 200

If we change the status to 200, the test will fail because while both calls return the same status code and response body (as they both call the same endpoint), the actual status response of 301 does not match the expected 200. This is commonly used for detecting auth issues. Often if you fail to authenticate to one version of a service, you’ll fail to authenticate with both endpoints.

Test definitions support basic HTTP functionality such as defining headers and query parameters.

request:
  url: https://api.jikken.io/api/v1/examples/status
  headers:
    - header: Authorization
      value: Bearer ${token}
  params:
    - param: q
      value: test
response:
  status: 200

They also support stages (multiple steps), variables (generating data), tags for selective execution grouping, setup methods, cleanup methods, and more! Check out our Test Format documentation for additional details.

Checking tests

Jikken also provides some mechanisms to help verify your tests prior to actually calling the real services. The most basic form of this is through the jk dryrun command. This command prints a detailed list of the steps and checks the tool will make given the currently defined tests, without actually making any of the API calls.

We also have plans for adding test validation (“compiling” to find errors in the definitions) and linting (auto formating and pruning uneeded fields).

Running tests

To run tests in Jikken, use the jk run command. By default, this will execute all test definitions in the current directory. You can also specify a single test file or path to run, and enable recursive searching via options.

You can also execute specific groups of tests by using tag definitions. You can provide a list of tags which are all required when selecting tests to run, or you can leverage the tags_or argument to execute tests that match any of the provided tags.

We also have plans in the near future to allow piping test definitions via Unix pipes.