Jikken

https://jikken.io/docs
Admin
Jikken is a CLI tool for automated API testing that uses JKT test definition files to execute and...
Tokens:22,672
Snippets:347
Trust Score:6.3
Update:5 months ago
Show doc for...
Tokens:
Raw
### Build and Install Jikken from Local Clone

Source: https://jikken.io/docs/setup/install-from-source

Installs Jikken after cloning the repository locally. This method allows for modifications before building and installing.

```bash
git clone https://github.com/jikkenio/jikken.git
cd jikken
cargo install --path .
```

--------------------------------

### Install Jikken using Installation Script

Source: https://jikken.io/docs/setup/install-on-linux

This method provides a public installation script, suitable for CI/CD pipelines. It uses curl to download and execute the script.

```bash
curl https://jikken.io/install.sh | bash
```

--------------------------------

### Test Setup Configuration

Source: https://jikken.io/docs/test-format/full-format

The `setup` block defines an initial API request that must succeed before other stages of the test are executed. The `response` sub-field within setup is optional.

```yaml
setup:
  request:
  response:
```

--------------------------------

### Install Jikken with Chocolatey

Source: https://jikken.io/docs/setup/install-on-windows

Use this command if you have Chocolatey installed on your Windows system to install the Jikken CLI.

```bash
choco install jikken
```

--------------------------------

### Install Jikken from Git Repository with Cargo

Source: https://jikken.io/docs/setup/install-from-source

Installs Jikken directly from its Git repository. This is useful for installing development versions or specific branches.

```bash
cargo install --git http://www.github.com/jikkenio/jikken
```

--------------------------------

### Display Jikken CLI Help

Source: https://jikken.io/docs/cli-commands/jk

Prints all available commands and options for the Jikken CLI. Use the -V option to check the installed version.

```bash
jk -h
```

--------------------------------

### Install Jikken with Linuxbrew

Source: https://jikken.io/docs/setup/install-on-linux

Use this method if you are a Linuxbrew user. It involves adding the Jikken tap and then performing the brew installation.

```bash
brew tap jikkenio/jikken
brew install jikken
```

--------------------------------

### Setup Stage for Authentication

Source: https://jikken.io/docs/tutorial/multistage

Defines the initial request to authenticate and extract a token, typically used in subsequent stages.

```yaml
setup:
  request:
    method: Post
    url: https://api.jikken.io/api/v1/examples/login
    body: {
      "username": "testuser",
      "password": "password"
    }
  response:
    status: 200
    extract:
      - name: token
        field: auth.token

```

--------------------------------

### Setup Stage

Source: https://jikken.io/docs/test-format/full-format

Defines an API request to be made before any other stages, typically for setting up test preconditions.

```APIDOC
## Setup Stage

### Description
Defines an API request to be made before any other stages, typically for setting up test preconditions.

### Fields
- **request** - The API request to be made prior to all other stages.
- **response** - Optional - The expected response values to validate. If the setup stage fails, no other stages will be executed.
```

--------------------------------

### Full Jikken Test Structure Example

Source: https://jikken.io/docs/test-format/full-format

This YAML/JSON structure represents a complete Jikken test case, including request, comparison, response, setup, stages, cleanup, and variable definitions. It serves as a template for defining complex test scenarios.

```yaml
name:
id:
platformId:
description:
project:
env:
tags:
requires:
disabled:
iterate:
request:
  method:
  url:
  params:
  - param:
    value:
  headers:
  - header:
    value:
  body:
compare:
  method:
  url:
  params:
  - param:
    value:
  addParams:
  - param:
    value:
  ignoreParams:
  -
  headers:
  - header:
    value:
  addHeaders:
  - header:
    value:
  ignoreHeaders:
  -
  body:
  strict:
response:
  status:
  time:
  headers:
  - header:
    value:
  body:
  bodySchema:
  strict:
  ignore:
  -
  extract:
  - name:
    field:
setup:
  request:
    method:
    url:
    params:
    - param:
      value:
    headers:
    - header:
      value:
    body:
  response:
    status:
    time:
    headers:
    - header:
      value:
    body:
    bodySchema:
    strict:
    ignore:
    -
    extract:
    - name:
      field:
stages:
- name:
  request:
    method:
    url:
    params:
    - param:
      value:
    headers:
    - header:
      value:
    body:
  compare:
    method:
    url:
    params:
    - param:
      value:
    addParams:
    - param:
      value:
    ignoreParams:
    -
    headers:
    - header:
      value:
    addHeaders:
    - header:
      value:
    ignoreHeaders:
    -
    body:
    strict:
  response:
    status:
    time:
    headers:
    - header:
      value:
    body:
    bodySchema:
    strict:
    ignore:
    -
    extract:
    - name:
      field:
  delay:
cleanup:
  onsuccess:
    method:
    url:
    params:
    - param:
      value:
    headers:
    - header:
      value:
    body:
  onfailure:
    method:
    url:
    params:
    - param:
      value:
    headers:
    - header:
      value:
    body:
  always:
    method:
    url:
    params:
    - param:
      value:
    headers:
    - header:
      value:
    body:
variables:
- name:
  type:
  value:
  valueSet:
  file:
  min:
  max:
  pattern:
  oneOf:
  noneOf:
  anyOf:
  length:
  minLength:
  maxLength:
  schema:
  modifier:
    operation:
    value:
    unit:
  format:

```

--------------------------------

### Example List Value

Source: https://jikken.io/docs/user-guide/data-generation

An example of a generated List value.

```json
[98,38,3,31]
```

--------------------------------

### Install Latest Jikken Package with Cargo

Source: https://jikken.io/docs/setup/install-from-source

Installs the latest stable version of Jikken published to Cargo. Ensure you have the latest stable Rust installed.

```bash
cargo install jikken
```

--------------------------------

### Example DateTime Value

Source: https://jikken.io/docs/user-guide/data-generation

An example of a generated DateTime value adhering to a specific format.

```text
"2023-01-30 23:13:42"
```

--------------------------------

### Define Multi-staged Test Structure

Source: https://jikken.io/docs/test-format/basic-format

Use this structure to define tests with setup, stages, and cleanup phases. The setup runs before all stages, and cleanup can be configured to run on success, failure, or always.

```yaml
setup:
  request:
  response:
stages:
  - name:
    request:
    compare:
    response:
    variables:
cleanup:
  onsuccess:
  onfailure:
  always:

```

--------------------------------

### Metadata Section Example

Source: https://jikken.io/docs/test-format/basic-format

The metadata section is optional but recommended for ease of use. It includes fields like name, id, project, env, tags, and requires for organizing and referencing tests.

```yaml
# metadata
name:
id:
project:
env:
tags:
requires:

```

--------------------------------

### Define HTTP Request with Headers and Query Parameters

Source: https://jikken.io/docs/user-guide/getting-started

This example demonstrates how to include custom headers, such as authorization tokens, and query parameters in your HTTP requests. It also specifies an expected response status.

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

--------------------------------

### Jenkinsfile for Jikken CI/CD

Source: https://jikken.io/docs/setup/ci-cd-integration

This Jenkinsfile defines a CI/CD pipeline with stages for building, deploying, and testing. It demonstrates how to inject environment variables, install Jikken, run tests, and report JUnit results.

```groovy
pipeline {
    agent {
        docker {
            image 'ubuntu:latest'
        }
    }


    stages {
        stage('Build') {
            ...
        }
        stage('Deploy') {
            ...
        }
        stage('Test') {
            environment {
                JIKKEN_API_KEY = credentials('jikken-api-key')
                JIKKEN_ENVIRONMENT = ${JIKKEN_ENVIRONMENT}
                JIKKEN_GLOBAL_API_BASE = ${JIKKEN_API_BASE}
                JIKKEN_GLOBAL_TEST_USERNAME = ${JIKKEN_TEST_USERNAME}
                JIKKEN_SECRET_TEST_PASSWORD = credentials('jikken-test-user-password')
            }
            steps {
                echo 'Installing Jikken'
                sh 'curl https://jikken.io/install.sh | bash'


                echo 'Executing Jikken tests'
                sh './jk run --junit jikken-test-results.xml tests/'
            }
        }
    }


    post {
        always {
            echo 'Reporting test data'
            junit 'jikken-test-results.xml'
        }
    }
}

```

--------------------------------

### GitHub Actions Workflow for Jikken Tests

Source: https://jikken.io/docs/setup/ci-cd-integration

This workflow runs Jikken tests after deployment. It installs Jikken using a curl script, executes tests, and uploads JUnit XML results. Environment variables and secrets are configured for API keys and credentials.

```yaml
jobs:
  build:
    ...
  deploy:
    ...
  test:
    needs: deploy
    runs-on: ubuntu-latest
    environment: dev
    steps:
    - uses: actions/checkout@v4


    - name: Install Jikken
      run: |
        curl https://jikken.io/install.sh | bash


    - name: Run Jikken tests
      run: ./jk run --junit jikken-test-results.xml tests/
      env:
        JIKKEN_API_KEY: ${{ secrets.JIKKEN_API_KEY }}
        JIKKEN_ENVIRONMENT: ${{ vars.JIKKEN_ENVIRONMENT }}
        JIKKEN_GLOBAL_API_BASE: ${{ vars.JIKKEN_API_BASE }}
        JIKKEN_GLOBAL_TEST_USERNAME: ${{ vars.JIKKEN_TEST_USERNAME }}
        JIKKEN_SECRET_TEST_PASSWORD: ${{ secrets.JIKKEN_TEST_PASSWORD }}


    - name: Upload test results
      uses: actions/upload-artifact@v4
      with:
        name: jikken-test-results
        path: jikken-test-results.xml
      if: always()

```

--------------------------------

### CircleCI Configuration for Jikken Tests

Source: https://jikken.io/docs/setup/ci-cd-integration

This CircleCI configuration sets up a test job that runs after deployment. It installs Jikken via a script, executes tests, and stores the JUnit XML results. Environment variables and secrets are used for authentication and configuration.

```yaml
version: 2.1


jobs:
  build:
    ...
  deploy:
    ...
  test:
    docker:
      - image: ubuntu:latest
    steps:
      - checkout


      - run:
          name: Install Jikken
          command: curl https://jikken.io/install.sh | bash


      - run:
          name: Run Jikken Tests
          command: ./jk run --junit jikken-test-results.xml tests/
            environment:
              JIKKEN_API_KEY: $JIKKEN_API_KEY
              JIKKEN_ENVIRONMENT: $JIKKEN_ENVIRONMENT
              JIKKEN_GLOBAL_API_BASE: $JIKKEN_API_BASE
              JIKKEN_GLOBAL_TEST_USERNAME: $JIKKEN_TEST_USERNAME
              JIKKEN_SECRET_TEST_PASSWORD: $JIKKEN_SECRET_TEST_PASSWORD


      - store_test_results:
          path: jikken-test-results.xml

workflows:
  my-workflow:
    jobs:
      - build
      - deploy:
          requires: build
      - test:
          requires: deploy
          context: dev

```

--------------------------------

### Generate List of Strings

Source: https://jikken.io/docs/user-guide/data-generation

Use the 'schema' block to define the type of items within a list. This example generates a list of 5 random string values.

```yaml
variables:
  - name: listOfStrings
    type: List
    length: 5
    schema:
      type: String
```

--------------------------------

### Create a Multistage Jikken Test

Source: https://jikken.io/docs

Define a multistage Jikken test with a name and tags. Includes a setup stage for login and token extraction, followed by multiple stages that make API calls and compare responses.

```yaml
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
```

--------------------------------

### Define an HTTP Request

Source: https://jikken.io/docs/test-format/full-format

Use this structure to define the details of an HTTP request, including method, URL, parameters, headers, and body. Defaults to GET if method is not specified.

```yaml
request:
  method:
  url:
  params:
  - param:
    value:
  headers:
  - header:
    value:
  body:

```

--------------------------------

### Basic Object Validation with Constraints

Source: https://jikken.io/docs/user-guide/advanced-validation

Use `response.bodySchema` to validate the structure and types of a response object. This example checks for a specific string value and a 5-character string.

```yaml
response:
  status: 200
  bodySchema:
    type: Object
    schema:
      "field1": "value"
      "field2":
        type: String
        length: 5
```

--------------------------------

### Create a Basic Test File

Source: https://jikken.io/docs/cli-commands/new

Create a new test file with a specified name in the current directory.

```bash
jk new <test_file_name>
```

--------------------------------

### Jikken CLI Help

Source: https://jikken.io/docs/user-guide/getting-started

Run `jk` with no arguments to display a description of all available commands.

```bash
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 

```

--------------------------------

### Display Help for jk new

Source: https://jikken.io/docs/cli-commands/new

Use the -h or --help flag to display detailed information about the 'jk new' command, including its usage, arguments, and options.

```bash
jk new -h
```

--------------------------------

### Generate an email address

Source: https://jikken.io/docs/user-guide/data-generation

Generates an email address with a domain from example.com, example.net, or example.org.

```yaml
variables:
  - name: email
    type: Email
```

--------------------------------

### Display Help for jk format

Source: https://jikken.io/docs/cli-commands/format

Use the -h or --help option to display detailed information about the jk format command, including its usage, arguments, and available options.

```bash
jk format -h
```

--------------------------------

### Display Help for jk list

Source: https://jikken.io/docs/cli-commands/list

Use the -h or --help flag to display detailed information about the jk list command, including its usage, arguments, and options.

```bash
jk list -h
```

--------------------------------

### Validating Nested Object Structures

Source: https://jikken.io/docs/user-guide/advanced-validation

Define nested schemas within `bodySchema` to validate complex, multi-level object structures. This example validates an object containing a nested 'metrics' object.

```yaml
response:
  bodySchema:
    type: Object
    schema:
      "id":
        type: Integer
      "metrics":
        type: Object
        schema:
          "average":
            type: Float
            min: 0
            max: 100
          "median":
            type: Integer
            min: 0
            max: 100
```

--------------------------------

### Generate a Full Test Template

Source: https://jikken.io/docs/cli-commands/new

Generate a test template that includes all available fields by using the -f or --full flag.

```bash
jk new --full <test_file_name>
```

--------------------------------

### Generate List with Schema and Constraints

Source: https://jikken.io/docs/user-guide/data-generation

Configure List generation with length, minLength, maxLength, and a nested schema for item types. If no schema or constraints are provided, it defaults to a list of 1-10 integers between 0 and 100.

```yaml
variables:
  - name: list
    type: List
    length: 5
    minLength: 5
    maxLength: 10
    schema:
      type: String
      length: 10
```

--------------------------------

### Configure Jikken Settings and Globals in TOML

Source: https://jikken.io/docs/setup/configuration

Define runtime settings and global variables for Jikken tests using a TOML configuration file. This file allows for centralized management of API keys, environment settings, and shared variables across tests.

```toml
[settings]
continueOnFailure=true
environment="qa"
apiKey="52adb38c-a0e4-438d-bff3-aa83a1a9a8ba"
bypassCertVerification=false


[globals]
newUrl="https://localhost:5001"
oldUrl="https://localhost:5002"
```

--------------------------------

### Test Stages Configuration

Source: https://jikken.io/docs/test-format/full-format

Define sequential `stages` for your test, each with its own optional `name`, `request`, `compare` request, `response` validation, and `delay`.

```yaml
stages:
- name:
  request:
  compare:
  response:
  delay:
```

--------------------------------

### Display Dryrun Command Help

Source: https://jikken.io/docs/cli-commands/dryrun

Use the -h or --help flag to display detailed information about the dryrun command, including its arguments and options.

```bash
jk dryrun -h
```

--------------------------------

### Format Test Files Matching Any Tag

Source: https://jikken.io/docs/cli-commands/format

Toggle the tag matching logic using the --tags-or option to format tests that match any of the provided tags, instead of requiring all tags to match.

```bash
jk format --tags-or -t tag1 -t tag2
```

--------------------------------

### Validate Command Help

Source: https://jikken.io/docs/cli-commands/validate

Displays help information for the `jk validate` command, including usage, arguments, and options.

```bash
jk validate -h
```

--------------------------------

### Generate a Multi-stage Test Template

Source: https://jikken.io/docs/cli-commands/new

Generate a test template structured for multi-stage tests using the -m or --multistage flag.

```bash
jk new --multistage <test_file_name>
```

--------------------------------

### Generate a list of objects

Source: https://jikken.io/docs/user-guide/data-generation

Create a list where each element is a generated object. This generates a list of 5 objects, each with 'field1' and a 10-character 'field2'.

```yaml
variables:
  - name: listOfObjects
    type: List
    length: 5
    schema:
      type: Object
      schema:
        "field1": "value"
        "field2":
          type: String
          length: 10
```

--------------------------------

### Authentication Endpoint

Source: https://jikken.io/docs/example-tests/basic

This snippet demonstrates how to authenticate with the API using a username and password.

```APIDOC
## POST https://api.jikken.io/api/v1/examples/login

### Description
Authenticates a user and returns a token.

### Method
POST

### Endpoint
https://api.jikken.io/api/v1/examples/login

### Request Body
- **username** (string) - Required - The username for authentication.
- **password** (string) - Required - The password for authentication.

### Request Example
{
  "username": "testuser",
  "password": "password"
}

### Response
#### Success Response (200)
- **token** (string) - The authentication token.
```

--------------------------------

### Create a Simple Jikken Test

Source: https://jikken.io/docs

Define a basic Jikken test by specifying a request and the expected response status code. This test passes only if the response status is 301.

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

--------------------------------

### Generate an integer with constraints

Source: https://jikken.io/docs/user-guide/data-generation

Generates a 64-bit integer. Constraints like min, max, anyOf, and noneOf can be applied. If no constraints are provided, the value is between 0 and 100.

```yaml
variables:
  - name: integer
    type: Integer
    min: 0
    max: 100
    anyOf: [1, 2]
    noneOf: [3]
```

--------------------------------

### Output Template to Console

Source: https://jikken.io/docs/cli-commands/new

Output the generated test template directly to the console instead of saving it to a file, using the -o option. This option has no effect when --from_openapi is also used.

```bash
jk new -o <test_file_name>
```

--------------------------------

### Define Global Variable via Environment

Source: https://jikken.io/docs/user-guide/variables

Expose environment variables directly to Jikken tests by prefixing them with JIKKEN_GLOBAL_.

```bash
export JIKKEN_GLOBAL_url=https://api.jikken.io
```

--------------------------------

### Generate String from a Pre-defined Set

Source: https://jikken.io/docs/user-guide/data-generation

Use the 'anyOf' constraint to specify a list of allowed values, from which a random string will be chosen.

```yaml
variables:
  - name: enum
    type: String
    anyOf: ["value1", "value2"]
```

--------------------------------

### Format Specific Test Files or Directories

Source: https://jikken.io/docs/cli-commands/format

Specify one or more file paths or directory paths as arguments to the jk format command to format only the test files within those locations.

```bash
jk format path/to/test_file.yml another/path/
```

--------------------------------

### Full Variable Definition Format

Source: https://jikken.io/docs/user-guide/variables

This snippet shows the complete structure for defining variables in a Jikken test, including all possible fields.

```yaml
variables:
- name: 
  type: 
  value: 
  valueSet: 
  file: 
  min: 
  max: 
  oneOf: 
  noneOf: 
  anyOf: 
  length: 
  minLength: 
  maxLength: 
  schema: 
  modifier:
    operation: 
    value: 
    unit: 
  format: 
```

--------------------------------

### Generate a basic object

Source: https://jikken.io/docs/user-guide/data-generation

Define an object with literal and generated fields. 'field1' is a literal string, and 'field2' is a 10-character random string.

```yaml
variables:
  - name: object
    type: Object
    schema:
      "field1": "value"
      "field2":
        type: String
        length: 10
```

--------------------------------

### Test Cleanup Actions

Source: https://jikken.io/docs/test-format/full-format

Configure `cleanup` actions to run after test execution. Specify requests to run `onsuccess`, `onfailure`, or `always`, with `always` executing last.

```yaml
cleanup:
  onsuccess:
  onfailure:
  always:
```

--------------------------------

### Generate String with Length Constraints

Source: https://jikken.io/docs/user-guide/data-generation

Use 'minLength' and 'maxLength' to generate a random string within a specified character length range. 'length' can be used for an exact length.

```yaml
variables:
  - name: text
    type: String
    minLength: 5
    maxLength: 10
```

--------------------------------

### Validate String Type with Constraints

Source: https://jikken.io/docs/user-guide/advanced-validation

Illustrates string validation with exact length, minimum/maximum length, allowed values (anyOf), disallowed values (noneOf), and a regular expression pattern.

```json
bodySchema:
  type: Object
  schema:
    "string":
      type: String
      length: 5
      minLength: 5
      maxLength: 10
      anyOf: ["this", "that"]
      noneOf: ["notthis"]
      pattern: "^[0-9a-z]*$"
```

--------------------------------

### Generate a string with constraints

Source: https://jikken.io/docs/user-guide/data-generation

Generates a string value. Constraints like length, minLength, maxLength, anyOf, and noneOf can be applied. If no constraints are provided, the value is an alphabetic string between 5 and 20 characters.

```yaml
variables:
  - name: string
    type: String
    length: 5
    minLength: 5
    maxLength: 10
    anyOf: ["this", "that"]
    noneOf: ["notthis"]
```

--------------------------------

### Basic Test Structure Skeleton

Source: https://jikken.io/docs/test-format/basic-format

This skeleton outlines the main sections of a Jikken test definition file, including metadata, basic request fields, multi-staged request fields, and variables.

```yaml
# metadata
name:
id:
project:
env:
tags:
requires:


# basic request fields
request:
compare:
response:


# multi-staged request fields
setup:
stages:
cleanup:


# variables
variables:

```

--------------------------------

### Multistage Test with Authentication and Comparison

Source: https://jikken.io/docs/example-tests/multistage

Define a multistage test that first logs in to obtain a token, then uses that token to test an API endpoint across different versions, and finally compares responses while ignoring specific fields. This is useful for testing sequential API interactions and version compatibility.

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

```

--------------------------------

### Generate a float with constraints

Source: https://jikken.io/docs/user-guide/data-generation

Generates a 64-bit floating-point number. Constraints like min, max, anyOf, and noneOf can be applied. If no constraints are provided, the value is between 0 and 100 with up to 3 decimal places.

```yaml
variables:
  - name: float
    type: Float
    min: 0.0
    max: 100.0
    anyOf: [1.2, 3.4]
    noneOf: [5.6]
```

--------------------------------

### Generate List of Strings with Specific Length

Source: https://jikken.io/docs/user-guide/data-generation

Define constraints within the 'schema' block to apply them to each item in the list. This generates a list of 5 strings, each 10 characters long.

```yaml
variables:
  - name: listOfStrings
    type: List
    length: 5
    schema:
      type: String
      length: 10
```

--------------------------------

### Generate Tests from OpenAPI Specification

Source: https://jikken.io/docs/cli-commands/new

Derive test definitions from an OpenAPI specification file. This option generates test templates for all specified paths and HTTP methods, organizing them hierarchically based on the specification's paths.

```bash
jk new --from_openapi <path_to_openapi_spec>
```

--------------------------------

### Executing Multiple Stages

Source: https://jikken.io/docs/tutorial/multistage

Defines sequential stages for executing requests, comparing responses, and validating status codes.

```yaml
stages:
  - request:
      url: https://api.jikken.io/api/v1/examples/status
      headers:
        - header: Authorization
          value: Bearer ${token}
    response:
      status: 200
  - request:
      url: https://api.jikken.io/api/v2/examples/status
      headers:
        - header: Authorization
          value: Bearer ${token}
    compare:
      url: https://api.jikken.io/api/v1/examples/status
    response:
      status: 200
      ignore:
        - user.lastActivity

```

--------------------------------

### Generate DateTime with Constraints

Source: https://jikken.io/docs/user-guide/data-generation

Configure DateTime generation with min, max, anyOf, noneOf, and format constraints. If no constraints are provided, the default range is 1970-01-01 to the current date/time with 'YYYY-MM-DD hh:mm:ss' format.

```yaml
variables:
  - name: datetime
    type: DateTime
    min: "2024-01-01 00:00:00"
    max: "2024-12-31 23:59:59"
    anyOf: ["2024-01-01 00:00:00", "2024-02-01 00:00:00"]
    noneOf: ["2024-02-29 00:00:00"]
    format: "%Y-%m-%d %H:%M:%S"
```

--------------------------------

### Generate a date with constraints

Source: https://jikken.io/docs/user-guide/data-generation

Generates a date value. Constraints like min, max, anyOf, noneOf, and format can be applied. If no constraints are provided, the date is between 1970-01-01 and the current date with the default format YYYY-MM-DD.

```yaml
variables:
  - name: date
    type: Date
    min: "2024-01-01"
    max: "2024-12-31"
    anyOf: ["2024-01-01", "2024-02-01"]
    noneOf: ["2024-02-29"]
    format: "%Y-%m-%d"
```

--------------------------------

### Compare Two HTTP Requests

Source: https://jikken.io/docs/user-guide/getting-started

Compare the responses of two different HTTP requests. This is ideal for regression testing, where you want to ensure a new service version behaves identically to an older one.

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

--------------------------------

### Export Global Variables as Environment Variables

Source: https://jikken.io/docs/setup/configuration

Define global variables for Jikken tests by exporting them as environment variables with the JIKKEN_GLOBAL_ prefix. This method allows overriding configuration file settings or defining new variables dynamically.

```bash
export JIKKEN_GLOBAL_newUrl=https://localhost:5001
export JIKKEN_GLOBAL_oldUrl=https://localhost:5002
```

--------------------------------

### Generate Object with Schema

Source: https://jikken.io/docs/user-guide/data-generation

Configure Object generation using a schema to define fields and their types or constraints. The 'schema' is required as there is no default value for Objects.

```yaml
variables:
  - name: object
    type: Object
    schema:
      "field1": "value"
      "field2":
        type: Integer
        min: 0
        max: 100
```

--------------------------------

### Validate Date Type with Constraints

Source: https://jikken.io/docs/user-guide/advanced-validation

Demonstrates date validation with minimum/maximum dates, allowed/disallowed values, and a specific date format.

```json
bodySchema:
  type: Object
  schema:
    "date":
      type: Date
      min: "2024-01-01"
      max: "2024-12-31"
      anyOf: ["2024-01-01", "2024-02-01"]
      noneOf: ["2024-02-29"]
      format: "%Y-%m-%d"
```

--------------------------------

### Compare API Endpoint

Source: https://jikken.io/docs/tutorial/compare

Use the 'compare' keyword to specify an alternative API endpoint for response comparison. By default, both HTTP status and body are compared.

```yaml
compare:
  url: https://api.jikken.io/api/v1/examples/status

```

--------------------------------

### Define a Comparison Request

Source: https://jikken.io/docs/test-format/full-format

Use this structure to define a request for comparison purposes, allowing for overriding or extending base request parameters and headers. Supports ignoring specific parameters and headers.

```yaml
compare:
  method:
  url:
  params:
  - param:
    value:
  addParams:
  - param:
    value:
  ignoreParams:
  - 
  headers:
  - header:
    value:
  addHeaders:
  - header:
    value:
  ignoreHeaders:
  - 
  body:
  bodySchema:
  strict:

```

--------------------------------

### Format Test Files Recursively

Source: https://jikken.io/docs/cli-commands/format

The -r option enables recursive searching for test files within the current directory and its subdirectories. This is useful for formatting all test definitions in a project.

```bash
jk format -r
```

--------------------------------

### Generate List of Integers

Source: https://jikken.io/docs/user-guide/data-generation

Specify 'type: List' with a 'length' to generate a list of a fixed size. By default, this generates a list of integers.

```yaml
variables:
  - name: list
    type: List
    length: 5
```

--------------------------------

### Validate List of Objects

Source: https://jikken.io/docs/user-guide/advanced-validation

Expect a list of 5 objects, each with an 'id' (integer >= 0) and 'createdAt' (DateTime >= NOW).

```json
response:
  bodySchema:
    type: List
    length: 5
    schema:
      type: Object
      schema:
        "id":
          type: Integer
          min: 0
        "createdAt":
          type: DateTime
          min: ${NOW}
```

--------------------------------

### Perform a Dry Run of a Jikken Test

Source: https://jikken.io/docs

Use the `jk dryrun` command to preview test execution steps without making actual API calls. This is useful for identifying errors in test definitions.

```bash

```

--------------------------------

### Generate an object with a list field

Source: https://jikken.io/docs/user-guide/data-generation

Create an object where one field is a list of generated values. 'field2' is a list of 5 random 10-character strings.

```yaml
variables:
  - name: objectWithList
    type: Object
    schema:
      "field1": "value"
      "field2":
        type: List
        length: 5
        schema:
          type: String
          length: 10
```

--------------------------------

### Run Dryrun Command with JUnit Output

Source: https://jikken.io/docs/cli-commands/dryrun

Execute tests in dryrun mode and save the results in JUnit format to a specified file.

```bash
jk dryrun --junit results.xml
```

--------------------------------

### Define Variable Loading Data from File

Source: https://jikken.io/docs/user-guide/variables

Create a variable by loading its content from a specified file using the `file` field. This is useful for complex JSON payloads.

```yaml
variables:
  - name: requestBody
    file: postbody.json

```

--------------------------------

### Format Test Files with Specific Tags

Source: https://jikken.io/docs/cli-commands/format

Use the -t or --tag option to filter tests based on their associated tags. By default, only tests matching all specified tags are formatted. Each tag should be provided with a separate -t option.

```bash
jk format -t tag1 -t tag2
```

--------------------------------

### Define Global Variable in .jikken config

Source: https://jikken.io/docs/user-guide/variables

Alternatively, define global variables within the .jikken configuration file under the [globals] section.

```ini
[globals]
url="https://api.jikken.io"
```

--------------------------------

### Compare StatusV2 and StatusV1 Responses

Source: https://jikken.io/docs/example-tests/compare

This snippet sets up a test to compare the response from a v2 API endpoint with the response from a v1 endpoint. It specifies the request URL, headers, the comparison URL, and expected response status, while ignoring certain fields in the comparison.

```yaml
name: Compare StatusV2 and StatusV1
tags: regression
requires: auth
request:
  url: https://api.jikken.io/api/v2/examples/status
  headers:
    - header: Authorization
      value: Bearer ${token}
compare:
  url: https://api.jikken.io/api/v1/examples/status
response:
  status: 200
  ignore:
    - user.lastActivity

```

--------------------------------

### Configure HTTP Headers

Source: https://jikken.io/docs/test-format/full-format

Set HTTP headers for requests. The 'header' field specifies the header key, and 'value' provides the header's value. This is commonly used for authentication tokens or content types.

```yaml
headers:
- header:
  value:
```

--------------------------------

### Validate Float Type with Constraints

Source: https://jikken.io/docs/user-guide/advanced-validation

Demonstrates validation for a float value, including minimum, maximum, allowed values (anyOf), and disallowed values (noneOf).

```json
bodySchema:
  type: Object
  schema:
    "float":
      type: Float
      min: 0.0
      max: 100.0
      anyOf: [1.2, 3.4]
      noneOf: [5.6]
```

--------------------------------

### Cleanup Actions

Source: https://jikken.io/docs/test-format/full-format

Defines API requests to be made after a test has executed, based on the test's success or failure.

```APIDOC
## Cleanup Actions

### Description
Defines API requests to be made after a test has executed, based on the test's success or failure.

### Fields
- **onsuccess** - Optional - An API request to be made only when the test has succeeded.
- **onfailure** - Optional - An API request to be made only when the test has failed.
- **always** - Optional - An API request to be made every time this test executes, regardless of success or failure. This runs after `onsuccess`/`onfailure` requests.
```

--------------------------------

### Run Dryrun Command with Tag Filtering

Source: https://jikken.io/docs/cli-commands/dryrun

Execute tests in dryrun mode, selecting only those that match the specified tags. Use --tags-or to match any tag instead of all.

```bash
jk dryrun -t tag1 -t tag2
```

```bash
jk dryrun --tag tag1 --tags-or
```

--------------------------------

### Configure Query Parameters

Source: https://jikken.io/docs/test-format/full-format

Define query parameters for requests. The 'param' field is the parameter name and 'value' is its corresponding value. This structure appends parameters to the request URL.

```yaml
params:
- param:
  value:
```

--------------------------------

### Generate a full name

Source: https://jikken.io/docs/user-guide/data-generation

Generates a full name, consisting of a given name and surname separated by a single space.

```yaml
variables:
  - name: name
    type: Name
```

--------------------------------

### Define Compare API Request Structure

Source: https://jikken.io/docs/test-format/basic-format

The `compare` block specifies an additional API request for response comparison. It supports all fields from `request` plus additional flexibility options.

```yaml
compare:
  method:
  url:
  params:
  - param:
    value:
  headers:
  - header:
    value:
  body:
```

--------------------------------

### Define Variables for Dynamic Tests

Source: https://jikken.io/docs/test-format/basic-format

Configure variables to make tests dynamic. Supports various types, static values, value sets for cycling through inputs, and file-based content.

```yaml
variables:
- name:
  type:
  value:
  valueSet:
  file:

```

--------------------------------

### Define Variables in Jikken

Source: https://jikken.io/docs/test-format/full-format

Use this structure to define variables with various constraints and types. Ensure unique names for variables to avoid overwrites. Supported types include Int, String, Date, Float, Object, List, Boolean, Email, Name, and Datetime.

```yaml
variables:
- name:
  type:
  value:
  valueSet:
  file:
  min:
  max:
  oneOf:
  noneOf:
  anyOf:
  length:
  minLength:
  maxLength:
  schema:
  modifier:
    operation:
    value:
    unit:
  format:
```

--------------------------------

### Test Stages

Source: https://jikken.io/docs/test-format/full-format

Defines the main sequence of operations for a test, including requests, comparisons, and expected responses.

```APIDOC
## Test Stages

### Description
Defines the main sequence of operations for a test, including requests, comparisons, and expected responses.

### Fields
- **name** - Optional - The name for the stage, used in console output and dashboard messaging.
- **request** - The API request to be made.
- **compare** - Optional - The comparison request to be made.
- **response** - Optional - The expected response values to validate.
- **delay** - Optional - The millisecond duration to pause after executing the stage.
```

--------------------------------

### Request Structure

Source: https://jikken.io/docs/test-format/full-format

Defines the structure for making an API request, including method, URL, parameters, headers, and body.

```APIDOC
## Request Structure

### Description
Defines the structure for making an API request.

### Fields
- **method** (string, Optional): The HTTP method for the request. Supported values are: `Get`, `Post`, `Put`, `Patch`, and `Delete`. Defaults to `Get` if not present.
- **url** (string): The URL to be called. Supports global and local variable injection.
- **params** (array, Optional): A list of query parameters to add to the URL request.
- **headers** (array, Optional): A list of HTTP headers to send in the request.
- **body** (object, Optional): The JSON body to send in the request. Supports literal JSON and variable embedding.

### Example
```yaml
request:
  method: Post
  url: http://api.myurl.com
  params:
    - param:
        name: queryParam1
        value: value1
  headers:
    - header:
        name: Content-Type
        value: application/json
  body: |
    { "key": "value" }
```
```

--------------------------------

### Define API Request Structure

Source: https://jikken.io/docs/test-format/basic-format

The `request` block defines an API request. It supports HTTP method, URL, query parameters, headers, and a JSON body. Use variables for URLs to support different environments.

```yaml
request:
  method:
  url:
  params:
  - param:
    value:
  headers:
  - header:
    value:
  body:
```

--------------------------------

### Compare Requests Against Each Other and a Known State

Source: https://jikken.io/docs/user-guide/getting-started

This snippet defines a test that compares two requests and also validates the response against a specific known state. It ensures both requests match each other and a predefined expected outcome.

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

--------------------------------

### Request Definition

Source: https://jikken.io/docs/test-format/basic-format

Defines an API request to be made, including method, URL, parameters, headers, and body.

```APIDOC
## Request Definition

### Description
Defines an API request to be made. This structure is used in various parts of Jikken, including stage definitions, setup, cleanup, and compare calls.

### Fields

- **method** (string, optional): The HTTP method (e.g., `Get`, `Post`, `Put`, `Patch`, `Delete`). Defaults to `Get` if not specified.
- **url** (string): The URL of the API to call. Supports variable embeddings.
- **params** (array of objects, optional): URL Query Parameters to attach to the URL. Each object has a `param` key and a `value` key. Values support variable embeddings.
- **headers** (array of objects, optional): HTTP headers to send with the request. Each object has a `header` key (name) and a `value` key. Values support variable embeddings.
- **body** (object, optional): The JSON body to include in the request. Can be literal JSON or a variable referencing JSON or a file.
```

--------------------------------

### Load Request Body from File Variable

Source: https://jikken.io/docs/user-guide/variables

Use a variable to load request body content from an external file. The file path can be absolute or relative to the test definition file.

```yaml
request:
  method: Post
  url: https://api.jikken.io/api/v1/examples/login
  body: ${credentials}
response:
  status: 200
variables:
  - name: credentials
    file: creds.json

```

--------------------------------

### Compare Structure

Source: https://jikken.io/docs/test-format/full-format

Defines the structure for comparing API responses, allowing for detailed configuration of request parameters, headers, and body.

```APIDOC
## Compare Structure

### Description
Defines the structure for comparing API responses with detailed configuration options.

### Fields
- **method** (string, Optional): The HTTP method for the request. Supported values are: `Get`, `Post`, `Put`, `Patch`, and `Delete`. Defaults to `Get` if not present.
- **url** (string): The URL to be called. Supports global and local variable injection.
- **params** (array, Optional): A list of query parameters. If not provided, defaults to `request.params`. If provided, `request.params` are ignored.
- **addParams** (array, Optional): A list of additional query parameters to add to the URL request.
- **ignoreParams** (array, Optional): A list of query parameters to exclude from the comparison.
- **headers** (array, Optional): A list of HTTP headers. If not provided, defaults to `request.headers`. If provided, `request.headers` are ignored.
- **addHeaders** (array, Optional): A list of additional HTTP headers to send.
- **ignoreHeaders** (array, Optional): A list of HTTP headers to exclude from the comparison.
- **body** (object, Optional): The JSON body to send in the request.
- **bodySchema** (object, Optional): The schema to validate the response body against.
- **strict** (boolean, Optional): When true, missing body fields in the response result in an error. Defaults to true.

### Example
```yaml
compare:
  method: Get
  url: http://api.myurl.com/v2
  params:
    - param:
        name: version
        value: 2
  addParams:
    - param:
        name: newParam
        value: newValue
  ignoreParams:
    - oldParam
  headers:
    - header:
        name: Accept
        value: application/json
  addHeaders:
    - header:
        name: X-Custom-Header
        value: customValue
  ignoreHeaders:
    - Authorization
  body:
    key: value
  strict: false
```
```
Tokens:
Raw