# The API test suite you leave a client can be a few text files

> Hurl runs on your laptop and in the client's CI pipeline, and their team can read every line of it.

Original: https://fdetimes.net/en/tools/hurl-api-tests-for-client-handover/

In your first week on a client site you will call their API a hundred times: fetching a token, creating a record, checking a status. Those calls usually end up scattered across your terminal history or someone's collection. By handover, nothing is left that the client's team can run again.

Hurl fills exactly this gap. According to its official site, it is a command-line tool that runs HTTP requests defined in a plain-text format. It is a lightweight binary written in Rust and uses libcurl as its HTTP engine.

The project sits in the Orange-OpenSource organisation on GitHub under the Apache-2.0 licence. If the client has an approval process for open-source software, ask early whether that licence is on the allowed list.

For an FDE, the value is not speed. It is that a text file can be committed to the client's repo, reviewed in a pull request and run in their CI with a single command.

## One file, a whole business flow

Imagine you are integrating with a client's job orchestration API. The flow to check is: create a job, take its id, then confirm the job is running. Written in Hurl, the file `integration/create_job.hurl` might look like this:

```hurl
# Create a new job
POST https://{{host}}/api/jobs
Content-Type: application/json
{
  "name": "nightly-sync"
}
HTTP 201
[Captures]
job_id: jsonpath "$.id"

# Check the job just created
GET https://{{host}}/api/jobs/{{job_id}}
HTTP 200
[Asserts]
jsonpath "$.state" == "running"
```

Each block is a request with its expected status line. The `[Captures]` section takes a value from the response for a later request to reuse. Hurl's README illustrates this with XPath, pulling a CSRF token from the meta tag of an HTML page. The `[Asserts]` section checks what comes back, for example comparing a JSON field via JSONPath, as in the official sample docs.

The detail worth noticing is `{{host}}`. You do not hard-code a staging or production address into the file, so the same suite runs against every one of the client's environments.

## From laptop to CI takes only a flag

When debugging, you run the file normally to see the last response. When you want to test, add the `--test` flag. Hurl's documentation says this mode adds a run summary and suppresses the printing of the last response, while asserts still run. Multiple `.hurl` files are also run in parallel to cut the time.

The official CI/CD integration guide gives a command that is almost ready to use:

```bash
hurl --variable host="$1" --test integration/*.hurl
```

Add `--report-junit report.xml` and most CI systems can read the results and show which tests failed. Hurl also exports text, TAP and HTML reports; the HTML one is generated with `--report-html DIR` so that people who do not read logs can follow it too.

Installation is not hard either. Hurl is available through Homebrew and Cargo, and there is an official Docker image at `ghcr.io/orange-opensource/hurl`. At companies that lock down their build machines, running through the Docker image is usually the route that needs the fewest permissions.

## Two traps before it goes into the client's pipeline

The first trap comes from the parallel execution itself. If file A creates data that file B needs, the two may run at the same time and the tests will fail intermittently. The safe rule is to keep each file self-contained: any flow that chains requests stays in one file and passes data through captures.

The second trap is the HTML report. The documentation states clearly that new results are appended to the existing report. On a CI runner that reuses its working directory, delete the report directory before each run, or readers will mix today's results with yesterday's.

It also helps to be clear about the tool's scope. Hurl checks HTTP behaviour from the outside. It tells you the API returned the wrong thing, but to find out why you still have to read the client's logs and code.

**Key point:** The best test suite to leave a client is one their team can understand without you.

## What to learn first

Master three things in order: the structure of a request block and its status line, how to capture values to chain requests, and JSONPath syntax for asserts. With those three you can write smoke tests for most REST APIs. Only then move on to `--variable`, `--test` and the report flags.

On a client site, the first thing to do is write a file that checks the most important endpoint of the integration, commit it to their repo and run it in CI before the first demo. From then on, every bug you find should come with a `.hurl` file that reproduces it.

## Break a test on purpose before trusting it

A small exercise worth doing before you hand a suite to a client: in the example file above, change `"running"` to a value that is certainly wrong, such as `"no-such-state"`. Then run `hurl --variable host=... --test --report-junit report.xml integration/*.hurl`.

Your job is to check three places. The summary at the end of the run should show `create_job.hurl` failing while the other files still pass. The `report.xml` file should record that same failure, and when pushed to a trial CI job, the pipeline should turn red.

If any of the three fails to reflect the error, your suite is not yet trustworthy, even if everything is green today. Put the assert back to the correct value, run it again, and hand over only once you have seen it go both red and green.

Professionally, a directory of `.hurl` files in a portfolio repo shows recruiters that you can test an API you did not write. When an FDE job posting mentions "API integration" or "CI/CD", put a concrete result on your CV, such as having built a smoke test suite that runs in a client's pipeline, rather than just listing tool names.

When you leave a project, the integration code may well be rewritten. The text files that spell out what the API must return tend to outlast it.

**Try this week:**

- Install Hurl with Homebrew, Cargo or the official Docker image, then write a .hurl file that calls the health endpoint of an API you are integrating with
- Write a second file that chains two requests: capture an id from the first request, then assert the status in the second
- Run the whole directory with --test and --report-junit, then put that command into a trial CI job

## Sources

- [Hurl - Run and Test HTTP Requests](https://hurl.dev/)

- [Orange-OpenSource/hurl: Hurl, run and test HTTP requests with plain text](https://github.com/Orange-OpenSource/hurl)

- [Running Tests - Hurl Documentation](https://hurl.dev/docs/running-tests.html)

- [CI/CD Integration - Hurl Tutorial](https://hurl.dev/docs/tutorial/ci-cd-integration.html)

- [hurl 6.0.0 README (docs.rs)](https://docs.rs/crate/hurl/6.0.0/source/README.md)

- [Samples - Hurl Documentation](https://hurl.dev/docs/samples.html)

- [Installation - Hurl Documentation](https://hurl.dev/docs/installation.html)
