# API tests

> Test REST APIs in Arcus with API call steps that send requests, verify responses, store values, and pass them to later calls.

An **API call** is a step that sends an HTTP request and checks the response. You build it in a request editor inside the test case: the method, URL, parameters, body, headers, and authorization, then what to verify and what to store. A test case can hold several API calls, each passing values to the next, and can mix them with web steps.

Use API calls to test an API directly, to set up data before a UI test, or to check a backend result after one. For every field and option in the editor, see [API call reference](https://testsigma.com/docs/arcus/v2/apps/api/api-call-reference/). To test a GraphQL API, see [GraphQL calls](https://testsigma.com/docs/arcus/v2/apps/api/graphql-calls/).

![A test case with three API calls, with Create user, List users, and Get user by ID outlined.](https://s3.amazonaws.com/static-docs.testsigma.com/arcus/application_types/api_tests_calls.webp)

## Add an API call

1. Open the test case and select **Automated steps**.
2. In an empty step row, type `/REST` and press `Enter` to insert **REST API**. The request editor opens beside the steps.

   ![The blocks list filtered by /REST, with REST API outlined.](https://s3.amazonaws.com/static-docs.testsigma.com/arcus/application_types/api_rest_block_menu.webp)

3. Click **New API call** at the top of the editor and enter a name for the call.
4. Select the method, such as **GET** or **POST**, and enter the URL. Until the URL is filled in, the field reads "Enter a URL" and **Create** stays unavailable.

   ![A new API call, with the empty URL field and its Enter a URL message outlined.](https://s3.amazonaws.com/static-docs.testsigma.com/arcus/application_types/api_new_call.webp)
5. **(Optional)** Fill in the tabs the request needs:
   - **Parameters**: query parameters, written into the URL after `?`.
   - **Body**: **form-data**, **x-www-form-urlencoded**, **Raw** as JSON, XML, or Text, or **Binary**, a file from Uploads sent as the whole body.
   - **Headers**: request headers.
   - **Authorization**: Basic, Bearer, API key, OAuth 2.0, and other schemes.
   - **Settings**: SSL verification, redirects, timeout, and other request options.
6. Click **Send** to try the request. The **Response** pane shows the status, the time, the size, and the body.

   ![The request editor after Send, with the request line, the request tabs, the Verify and Store tabs, and the 201 Created response line outlined.](https://s3.amazonaws.com/static-docs.testsigma.com/arcus/application_types/api_call_editor.webp)
7. Add what to check on the **Verify** tab and what to keep on the **Store** tab. See [Verify a response](#verify-a-response) and [Store a value](#store-a-value).

   ![The Verify tab, with the verification sources, Add Verification, and a JSON path check outlined.](https://s3.amazonaws.com/static-docs.testsigma.com/arcus/application_types/api_call_verify.webp)

8. Click **Create**.

The call appears in the test as plain sentences under **REST API** and its name, for example "Make POST call to https://…/api/users", "Verify response status is 201", and "Store response field "id" as user_id". To change it later, click the call. Changes save when you close the editor. To add a check or a stored value without opening the editor first, click **Verify** or **Store** in **Add step to the API call** under the call.

**Send** runs the request from the editor and saves nothing. Use it to see the response before you add checks.

## Verify a response

On the **Verify** tab, click **Add Verification**. If you sent the request first, Arcus fills in a check from the response, such as **Status code** **Equals** `201`.

Choose what to check:

- **Status**: the status code.
- **Headers** and **Cookies**: a response header or cookie.
- **Response (JSON Path)**: a field in the body, by its JSON path, such as `$.name` or `$.data[0].id`.
- **Response (Object)**: the body as an object.

Then choose the comparison and the expected value. A JSON path check can compare values, match a regular expression, check that a field is present or absent, compare sizes with **Count equals** and the other count options, or check the type. For the full list, see [Verification types](https://testsigma.com/docs/arcus/v2/apps/api/api-call-reference/#verification-types).

Each check appears under the call, for example "Verify response field "data" count is 6".

## Send and compare files

API calls take their files from the project's [Uploads](https://testsigma.com/docs/arcus/v2/test-assets/uploads/). Until the project has an upload, the file options are unavailable and read "needs Uploads".

### Send a file

1. On the **Body** tab, select the body type:
   - **Binary**: the file is sent as the whole request body. The tab reads "The picked file is sent as the whole request body."
   - **form-data**: the file is sent as one part of the form.
2. Click **Select or search files in uploads** and pick the upload, or click **Upload a new file** to add one to Uploads first. Until a file is picked, the field reads "Pick the file to send".

A body on a **GET** request shows the warning "A body on a GET request is unusual; many servers ignore or reject it."

Form-data file parts are sent as `application/octet-stream`, whatever the file's type.

### Compare the response with a file

1. On the **Verify** tab, click **Add Verification** and select **Response (Object)**.
2. In **Comparison Type**, select **Upload File**. Until a file is picked, the field reads "Pick a file to compare the response with".
3. Click **Select or search JSON or XML files** and pick the upload.
4. In **Verification Type**, select how strictly to compare: **Strict**, **Strict Order**, **Lenient**, **Non Extensible**, or **Schema**.

File compares are checked when the test runs, not when you click **Send** in the editor. See [Limitations](#limitations).

## Store a value

To use part of a response later in the test, store it.

1. On the **Store** tab, select where the value comes from: **Status**, **Headers**, **Cookies**, or **Response (JSON Path)**.
2. Click **Store Variable**.

   ![The Store tab, with the store sources, Store Variable, and a stored value outlined.](https://s3.amazonaws.com/static-docs.testsigma.com/arcus/application_types/api_call_store.webp)

3. Enter a **Variable Name** and the **JSON Path** of the value, such as `$.id`.

The call then shows "Store response field "id" as user_id".

## Use a stored value in a later call

Type the variable name in braces anywhere in a later call: the URL, a parameter, a header, or the body. For example:

```text
https://api.example.com/api/users/{user_id}
```

Arcus highlights the variable. Click the call in the step list: the **Step settings** panel lists it under **FILLED ELSEWHERE**, marked "stored above".

![The Step settings panel of the Get user by ID call, with {first_user_id} stored above under FILLED ELSEWHERE outlined.](https://s3.amazonaws.com/static-docs.testsigma.com/arcus/application_types/api_step_settings_filled.webp)

When the test runs, Arcus fills in the value from the earlier call. **Send** in the editor doesn't, because nothing has run yet. To try the request, click **Variables**, enter a value under **SENT AS**, and click **Use these values**. Values you give there are kept for that editing session only.

## Keep secrets and base URLs in an environment

Don't type passwords, tokens, or keys into a test. Store them as variables in [Environments](https://testsigma.com/docs/arcus/v2/test-assets/environments/), and reference them as `{env.variable_name}`.

1. Go to **Test Assets** > **Environments** > **Default variables**, add each secret and turn on **Encrypt**. Click **Update**.
2. Create at least one environment, for example **Staging**. It starts with the default variables.
3. In the API call, enter the reference in the field, for example `{env.api_token}` in **Authorization** > **Bearer Token** > **Token**.

Do the same for the base URL, for example `{env.base_url}/api/users`, so the same test runs against each environment.

To try a call with an environment's values in the editor, select the environment in the list beside **Variables** before you click **Send**. **Project defaults** uses the project's default variables.

![The environment list beside Send, with Project defaults and the Playground environment.](https://s3.amazonaws.com/static-docs.testsigma.com/arcus/application_types/api_call_environment.webp)

A test reads `{env.…}` values only from an environment. When you run it, check that **Variables from** names the environment. If the project has only default variables and no environment, the references aren't filled in, and calls that need them fail, for example with 401 Unauthorized. **Send** in the editor does fill them in, so a call can work in the editor and fail in a run.

A test plan has its own environment, which every run it starts uses. A plan without one uses the project's default variables. When you start a cycle, you can pick a different environment for that cycle.

## Run an API test

1. On the test case, click **Debug with Copilot**.
2. Under **Where to run**, select **My local machine** or **Cloud**.
3. Under **Variables from**, select the environment.

   ![The Environment section of the Copilot configuration, with Variables from set to Playground (default) outlined.](https://s3.amazonaws.com/static-docs.testsigma.com/arcus/application_types/api_copilot_environment.webp)

4. Click **Start Copilot**.

Each call shows how long it took, and each check shows whether it passed. Click a call to see the request and the response it got.

![A Copilot session with the Create user call and its passed lines outlined, and the request editor showing the 201 response beside it.](https://s3.amazonaws.com/static-docs.testsigma.com/arcus/application_types/api_copilot_session.webp)

A Copilot session opens a browser even for a test with only API calls, and waits for it to start before running the calls. The browser stays on a blank page. The **Run log** below lists each call with its result and duration.

On your own machine, a session can need a newer Arcus Agent than the one installed. It then shows "This test needs a newer Arcus Agent" with **Update Arcus Agent** and **Try again**.

If a check fails, fix the call, then click the ellipsis icon (⋯) on it and click **Run from here**.

## Read the results

After a run, open the test case's **Run history** and click the run. The run page shows each step with its result, read-only, as it ran (**Executed**). To see and edit the test case's steps as they are now, click **Current**. Click an API call to see:

- The request it sent, read-only.
- Each check with the value it found, for example "Verify response status is 201 · was 201".
- The response: status, time, size, headers, and body, viewed as **Outline**, **JSON**, **HTML**, **XML**, or **Text**.

![A run page with the Create user call selected, with the Executed view, a check with its actual value, and the 201 response line outlined.](https://s3.amazonaws.com/static-docs.testsigma.com/arcus/application_types/api_tests_run_result.webp)

## Limitations

- You add API calls one at a time. Arcus doesn't import OpenAPI, Swagger, or Postman collections.
- **Raw** bodies support JSON, XML, and Text.
- **Send** in the editor doesn't evaluate file compares. They're checked only when the test runs.
- A failed file compare doesn't say which field differed.
- When a run fails on a call, the error can say "JSON path validation failed" even when the status check also failed. Open the call to see which checks failed.

## FAQs

### A call works with Send but fails when the test runs

The run isn't reading from an environment, so `{env.…}` references aren't filled in. Create an environment and select it under **Variables from**.

### A GET after a POST returns 404

Some APIs, especially demo and mock APIs, don't keep what you create. Check that the API stores the record. To chain calls against such an API, store a value from data it already has, such as the first item in a list.

### See what a call sent

Click the call in the session or on the run page. The editor shows the request, and **Variables** lists every variable it used.
