testflowkit.yml

TestFlowKit reads testflowkit.yml from the project root (legacy config.yml also supported). Override with --config path/to/file.yml.

tkit run --config staging.yml
tkit run --env-file .env.staging.yml

Minimal example

settings:
  gherkin_location: "features"
  report_format: "html"
  think_time: 100          # ms delay between actions (debugging)
  concurrency: 1
  env_file: ".env.local.yml" # optional default env file

env:
  base_url: "http://localhost:3000"
  api_base_url: "http://localhost:3001"

frontend:
  driver: "rod"              # required: "rod" or "playwright"
  base_url: "{{ env.base_url }}"
  default_timeout: 10000
  headless: false
  screenshot_on_failure: true
  pages:
    login: "/login"
  elements:
    login:
      email_field: "#email"
      submit_button: "#submit"

apis:
  default_timeout: 10000
  definitions:
    my_api:
      type: rest
      base_url: "{{ env.api_base_url }}"
      default_headers:
        Content-Type: "application/json"
      endpoints:
        get_users:
          method: GET
          path: "/users"
        create_user:
          method: POST
          path: "/users"
    my_graphql:
      type: graphql
      endpoint: "{{ env.api_base_url }}/graphql"
      operations:
        get_user:
          type: query
          operation: "graphql/get_user.graphql"

Use {{ env.variable }} anywhere in config. Nested env vars use dot notation: {{ env.database.host }}.

Sections

Section	Purpose
`settings`	Gherkin path, reports, concurrency, default env file, tag filter
`env`	Variables available as `{{ env.* }}` in config and Gherkin
`frontend`	Browser driver, pages, element selectors
`apis`	REST and GraphQL API definitions
`security_schemes`	Reusable auth (bearer, basic, apikey, oauth2)
`default_security`	Auth scheme applied by default
`files`	Named file paths for uploads and request bodies
`agent`	MCP server settings (ignored by `tkit run`)

Environment files

Keep secrets and per-environment URLs in separate files:

# .env.staging.yml
base_url: "https://staging.example.com"
api_base_url: "https://api-staging.example.com"

tkit run --env-file .env.staging.yml

Priority: CLI --env-file → settings.env_file → inline env: block.

Frontend

Field	Description
`driver`	Required. `rod` (default, bundled) or `playwright` (run `tkit install`)
`base_url`	App root URL
`pages`	Named paths — used in `the user goes to the "login" page`
`elements`	Selectors grouped by page — see Selectors

APIs

Reference in Gherkin as "api_name.endpoint_name" or "api_name.operation_name".

REST — requires type: rest, base_url, endpoints with method and path. Path params use {id} syntax.

GraphQL — requires type: graphql, endpoint, operations with type (query/mutation) and operation (file path or inline query).

Timeout precedence: endpoint/operation → API → apis.default_timeout → 30s.

Authentication

Define schemes once, reference with security_ref:

security_schemes:
  my_oauth2:
    type: oauth2
    token_url: "{{ env.auth_url }}"
    client_id: "{{ env.client_id }}"
    client_secret: "{{ env.client_secret }}"
    token_endpoint_auth_method: client_secret_post
    scopes: ["read"]

default_security: "my_oauth2"

apis:
  definitions:
    my_api:
      type: rest
      base_url: "{{ env.api_base_url }}"
      security_ref:
        name: my_oauth2
      endpoints:
        get_data:
          method: GET
          path: "/data"

Supported: bearer, basic, apikey, oauth2. Use security_ref.name: none to disable auth. oidc and certificate are not yet implemented.

Files

files:
  base_directory: "./test-files"
  definitions:
    avatar: "images/avatar.png"
    sample_json: "data/post.json"

Reference in steps: I set the request body from file "sample_json".

Next Steps

Selectors — Element selector strategies
Frontend Testing — UI testing guide
API Testing — REST and GraphQL guide
IDE Agent — MCP server setup