# GraphQL calls

> Test a GraphQL API in Arcus with a GraphQL call that builds a query from the endpoint's schema, sends it with variables, and checks the data and errors in the response.

A **GraphQL call** is a step that sends a GraphQL query or mutation and checks the response. It works like a REST API call: you build the request in the editor, try it with **Send**, then add what to verify and store. The editor also reads the endpoint's schema, so you can pick an operation and its fields instead of writing the query manually.

For REST APIs, see [API tests](https://testsigma.com/docs/arcus/v2/apps/api/api-tests/).

## Add a GraphQL call

1. Open the test case and select **Automated steps**.
2. In an empty step row, type `/` and select **GraphQL**. The request editor opens beside the steps, with the **Query** tab selected.

   ![The blocks list, with GraphQL outlined.](https://s3.amazonaws.com/static-docs.testsigma.com/arcus/application_types/api_blocks_menu.webp)

3. Click **New API call** at the top of the editor and enter a name for the call.
4. Enter the endpoint URL. A GraphQL call is always sent as **POST**, so the method list can't be changed.
5. In the **Schema** panel, click **Fetch schema**. The panel lists the API's **QUERIES**, each with its arguments and return type. To see mutations instead, click **Mutation**.
6. Select an operation. Arcus writes the query in the **Query** editor with the operation's fields ticked, and names it in **Operation to run**. Tick or untick fields in the panel to change what the query asks for, or edit the query directly.
7. If the query has variables, click **Variables** in the header and give each one a value. See [Give the query's variables a value](#give-the-querys-variables-a-value).
8. **(Optional)** Add headers and authorization, as for a REST call. See [Authorization types](https://testsigma.com/docs/arcus/v2/apps/api/api-call-reference/#authorization-types).
9. Click **Send**. The **Response** pane shows the status, the time, the size, and the body.
10. Check the **Verify** and **Store** tabs, then click **Create**.

![The GraphQL editor after Send, with the Schema panel, Operation to run, the schema check, and the data, errors, and extensions views outlined.](https://s3.amazonaws.com/static-docs.testsigma.com/arcus/application_types/api_graphql_editor.webp)

Below the query, Arcus checks it against the schema. "Query matches the schema" means every field, argument, alias, and fragment exists. Fix anything it reports before you send.

If the endpoint doesn't allow introspection, click **Paste schema (SDL)** and paste the schema instead. To fetch the schema again after the API changes, click the refresh icon beside the schema source.

## Give the query's variables a value

**Variables** in the header lists the query's variables, such as `$code`. GraphQL sends them in the request's `variables` object, alongside `query` and `operationName`.

1. Click **Variables**.
2. On the **Variables** tab, enter each variable's **VALUE**. **TYPE** defaults to **Auto**, which reads the type from the value. To enter the variables as JSON instead, click **JSON**.
3. Close the panel.

![The Variables panel, with the code variable and its value IN outlined.](https://s3.amazonaws.com/static-docs.testsigma.com/arcus/application_types/api_graphql_variables.webp)

A value can be a stored value or an environment value, such as `{user_id}` or `{env.country_code}`. Use `{env.base_url}` for the endpoint and `{env.api_token}` for a token, as in REST calls. See [Use a stored value in a later call](https://testsigma.com/docs/arcus/v2/apps/api/api-tests/#use-a-stored-value-in-a-later-call). The **Request values** tab lists the `{placeholders}` the URL and headers use.

## Verify the response

A new GraphQL call starts with two checks on the **Verify** tab:

- **Status code** **Equals** `200`.
- **errors** **Is empty**, so a query that fails inside a `200` response still fails the step.

![The Verify tab of a GraphQL call, with the default errors Is empty check and the data, errors, and extensions scopes outlined.](https://s3.amazonaws.com/static-docs.testsigma.com/arcus/application_types/api_graphql_default_checks.webp)

To check a field, open **Response (JSON Path)**, pick the part of the body it's in, **data**, **errors**, or **extensions**, and click **Add Verification**. The path starts inside that part. For example, `$.country.capital` under **data**. The comparisons are the same as for REST calls. See [Verification types](https://testsigma.com/docs/arcus/v2/apps/api/api-call-reference/#verification-types).

The response pane splits the body the same way. **errors** shows how many errors came back, such as **errors · 0**.

Storing works as it does for REST calls. See [Store a value](https://testsigma.com/docs/arcus/v2/apps/api/api-tests/#store-a-value).

## If the schema doesn't load

Arcus fetches the schema by sending an introspection query with the call's URL, headers, and authorization. It keeps a fetched schema for 10 minutes. When the fetch fails, the **Schema** panel says why:

| Reason | What to do |
|---|---|
| The address is private or local | Like **Send**, introspection doesn't reach private or local addresses, such as `localhost`. Use an address Arcus can reach from the internet, or paste the schema. |
| The host name didn't resolve | Check the URL. |
| The request timed out | The endpoint took longer than 15 seconds. Try again. |
| Introspection is turned off on the server | Click **Paste schema (SDL)**, or ask the API's owner to allow introspection for your environment. You can still send queries. |
| The endpoint didn't answer as GraphQL | Check that the URL is the GraphQL endpoint, not a page or REST endpoint. |
| The schema is too large | The endpoint's answer is larger than 10 MB. Paste the schema instead. |

## Run a GraphQL test

Run it like any API test, in a Copilot session or a test run. See [Run an API test](https://testsigma.com/docs/arcus/v2/apps/api/api-tests/#run-an-api-test).

**Send** and fetching the schema can't reach private network addresses, but a run can. To test an API on your own network, run the test on the Arcus Agent.
