Getting Started

Install

Testing ships in the kis CLI — check it is present with:

kis version

That gives you the v2 functional runner. The load, API, agent and orchestrator modes live on the standalone test.svc binary — see CLI Reference for which surface has what.

Your first API test (v2 runner)

Create a test directory with a test file and an env file:

tests/users.yaml

tests:
  - name: list-users
    tags: [smoke]
    steps:
      - name: get-users
        http:
          url: "{{baseurl}}/users"
          method: GET
          response:
            variables:
              first_id: "jq: .response[0].id"   # extract for the next step
        assertions:
          - status_code == 200
          - response.length > 0
          - duration_ms < 2000

      - name: fetch-first-user
        http:
          url: "{{baseurl}}/users/{{first_id}}"
          method: GET
        assertions:
          - status_code == 200
          - response.id == first_id             # RHS references the scope variable

  - name: create-user
    steps:
      - name: create
        http:
          url: "{{baseurl}}/users"
          method: POST
          headers:
            Content-Type: application/json
          body:
            type: raw
            payload: '{"name": "Testing Test", "username": "testing", "email": "[email protected]"}'
        assertions:
          - status_code == 201
          - response.id != null
          - response.name == "Testing Test"

tests/env.yaml

baseurl: https://jsonplaceholder.typicode.com

Run it:

kis test -t tests/

auto-discovered env file: tests/env.yaml
• kis test run started  (run-id: 57ab053badb098487fd390b2)

▾ tests
    ✓ get-users  88ms GET https://jsonplaceholder.typicode.com/users → 200
    ✓ fetch-first-user  100ms GET https://jsonplaceholder.typicode.com/users/1 → 200
    ✓ create  312ms POST https://jsonplaceholder.typicode.com/users → 201

────────────────────────────────────────────────────────────
  2 tests  │  2 passed  │  501ms
────────────────────────────────────────────────────────────

The env file is auto-discovered (env.local.yaml → env.yaml → env.<name>.yaml); results stream to the console; exit code is 0 if everything passed, 1 otherwise. No files are written unless you ask:

kis test -t tests/ --junit .test/junit.xml --db .test/results.db

Useful variations:

kis test -t tests/ --tags smoke                     # filter by tag
kis test -t tests/ -v baseurl=http://localhost:8080 # override a variable
kis test -t tests/ -e tests/env.yaml -n staging     # multi-env file, pick one
kis test -t tests/ --dry-run                        # validate without calling anything

Next steps:

• Full YAML schema (HTTP, gRPC, SQL, script steps; hooks; suites): test-definitions
• Assertion syntax and variable chaining: assertions-and-variables
• Table-driven tests: data-driven

Your first load test

Load testing runs through tests mode (test.svc tests), which uses the legacy step format — the repo ships runnable examples:

# workload: examples/06-load-test/steps.yaml (plain REST steps)
# profile:  examples/06-load-test/profile.yaml (warmup/sustained/cooldown)
test.svc tests -p examples/06-load-test -d examples/env.json \
    --load examples/06-load-test/profile.yaml --profile default -s

A profile is named phases with durations and concurrency targets:

loadprofiles:
  default:
    warmup:    { duration: 10s, targetusers: 5 }
    sustained: { duration: 30s, targetusers: 10 }
    cooldown:  { duration: 10s, targetusers: 2 }

While running you get a live status line; afterwards, per-phase tables with latency percentiles (execution time and TTFB), pass/fail counts, and bytes in/out.

Read load-testing before sizing real runs — especially the execution model (targetusers is a concurrency cap, not an arrival rate) and the pass/fail semantics (failed requests don’t change the exit code).

Trying the shipped examples

All examples/ use the tests-mode format:

test.svc tests -p examples/01-rest-basics -d examples/env.json -s     # REST basics
test.svc tests -p examples/02-rest-validations -d examples/env.json -s # validations & extraction
test.svc tests -p examples/03-plugin-engine -d examples/env.json -s   # JS plugin engine
test.svc tests -p examples/04-data-driven -d examples/env.json -s     # CSV-driven
test.svc tests -p examples/05-test-hierarchy -d examples/env.json -t testplan -e api-smoke -s

Which runner should I use?

You want to…	Use
Write new functional API tests (HTTP/gRPC/SQL/script)	kis test — test-definitions
Run load tests	test.svc tests --load — load-testing
Run existing plan/scenario/case collections, plugins, GraphQL bodies	test.svc tests — legacy tests mode
Distribute execution across machines	test.svc orchestrator + test.svc agent — server-modes