Using thymian test

thymian test validates a running API by sending real HTTP requests and checking the responses with the same rule system you use during linting. It helps you catch implementation drift: places where the live behavior no longer matches HTTP expectations or your intended design.

When to Use thymian test

Use thymian test when your API is running and you want to validate real behavior.

Typical situations include:

• local development against a running server
• CI checks against a test environment
• integration testing before deployment
• verifying that implementation changes still respect HTTP semantics

If thymian lint asks, “Does the specification look correct?”, then thymian test asks, “Does the running API actually behave correctly?”

Prerequisites

• An OpenAPI specification file
• A running API server

Step by Step Instructions

Step 1: Run live tests against your API

There is no setup step. Start your API server, then run:

npx thymian test --spec openapi:openapi.yaml --target-url http://localhost:3000

This command tells Thymian to:

1. Load the specification
2. Generate a request for every Transaction it describes, in memory
3. Send those requests to the target URL
4. Evaluate the responses against the loaded rules
5. Report any violations

Nothing is written to disk: request samples are a projection of your API description, rebuilt on every run. See Virtual Request Samples.

Step 2: Shape the requests with hooks

A generated request satisfies your schemas; it does not know your credentials or your database. That is what hooks are for — TypeScript functions anchored to the Transaction they apply to:

.thymian/sampler/hooks/auth.ts

import { authorize } from '@thymian/hooks';

export const credentials = authorize((request) => {
  request.headers['authorization'] = `Bearer ${process.env.API_TOKEN}`;
});

For a hands-on walkthrough, see Testing an API with the Sampler.

If you already have a Thymian config file, you can also run the command with -c and point to that config explicitly:

npx thymian test -c ./thymian.config.yaml

Step 3: Interpret the results

thymian test reports findings in the context of real HTTP traffic.

That means the output reflects what your running server actually returned, not just what the OpenAPI file describes. This is useful for catching problems caused by:

• framework defaults
• missing middleware
• authentication flows
• proxies or environment-specific behavior
• implementation changes that were never reflected in the spec

If a test run reports violations, fix the implementation, the test setup, or the specification, then rerun the command.

Step 4: Write better live tests with samples and hooks

Many APIs need more than a basic generated request. For example, you may need to:

• add authentication
• create data before a request runs
• inject IDs or tokens into requests
• skip or shape requests for specific scenarios

That is where samples and hooks help. A common progression looks like this:

1. Run thymian test
2. See which requests fail because they need setup or authentication
3. Add or refine hooks
4. Run thymian test again
5. Optionally run thymian sampler init so your editor completes Selectors and the compiler checks your hooks

For a hands-on walkthrough, see Testing an API with the Sampler.

How thymian test fits into the workflow

thymian test sits between design-time validation and traffic analysis:

• lint checks the API description
• test checks a live implementation
• analyze checks recorded traffic after requests have already happened

This makes test the best place to catch implementation issues before they appear in staging or production traffic.

Next Steps

• If you have not done it yet, start with Use thymian lint to review your API design
• Continue with Use thymian analyze to inspect recorded traffic
• See the CLI reference