Backend implementation

Run Hurl tests

Configure the Conduit Hurl runner, execute the behavioral suite serially, and diagnose failed assertions.

Run the Hurl collection against a local Conduit backend and use its assertions to find behavioral mismatches. Hurl is the source of truth for the API test workflow, and the runner gives each test run a host and a unique user-data value by default.

Before you begin

Start the backend you want to test and identify its API base URL. Install Hurl and run the command from the directory containing run-api-tests-hurl.sh. The default target is http://localhost:8000; use HOST when your backend listens elsewhere.

Run the suite

Set the backend URL

Set HOST to the complete API base URL. For a backend mounted at /api on port 3000, use:

bash

HOST=http://localhost:3000/api

The value is passed to Hurl as the host variable, so request paths resolve against this API origin and prefix.

Choose the test-data identifier

Leave UID_VAL unset for a normal run, or set it to a stable value when you need to reproduce a failure:

bash

UID_VAL=conformance-debug HOST=http://localhost:3000/api

When it is unset, the runner derives a unique value from the current time and process ID. The value is passed to Hurl as uid.

Run the Hurl files serially

Run the complete suite:

bash

HOST=http://localhost:3000/api UID_VAL=conformance-debug ./run-api-tests-hurl.sh

The script discovers the Hurl files, invokes hurl --test, and sets --jobs 1. The terminal output shows each test result and returns a failing status when an assertion does not pass.

Run a focused file when debugging

Pass one or more Hurl files after the script name:

bash

HOST=http://localhost:3000/api UID_VAL=conformance-debug ./run-api-tests-hurl.sh hurl/articles.hurl

The runner uses the file arguments instead of discovering the complete collection. Confirm the path in your checkout before using a focused command.

Diagnose a failed assertion

First confirm that HOST points to the running backend and includes the correct API prefix. Then read the first failed request and compare its status and response with the matching OpenAPI operation. If the failure depends on created data, rerun with the same UID_VAL to reproduce it; after correcting the behavior, run without an override to check a fresh identifier.

Hurl checks observable API behavior. It does not establish undocumented implementation details such as database design, token expiry, or deployment configuration. For a broader workflow that includes Bruno, see Run the backend conformance workflow.

✅A successful run completes all selected Hurl assertions without a failing exit status. Keep that result as the conformance signal because the Bruno collection is generated from Hurl.

Next steps

Use Run the generated Bruno collection when you need interactive request inspection, or return to Implement a conforming Conduit backend to organize the implementation around the contract.