---
title: Write Scout API tests
description: Scout API tests validate HTTP endpoints with realistic scoped credentials. Prepare the test environment with higher-privilege helpers (apiServices, kbnClient,...
url: https://www.elastic.co/elastic/docs-builder/docs/3016/extend/kibana/scout/write-api-tests
products:
  - Kibana
---

# Write Scout API tests
Scout API tests validate HTTP endpoints with realistic scoped credentials.
<important>
  [Set up your plugin or package](https://www.elastic.co/elastic/docs-builder/docs/3016/extend/kibana/scout/setup-plugin) first.
</important>


## Recommended structure

1. **Prepare the test environment** with higher-privilege helpers (`apiServices`, `kbnClient`, `esArchiver`, …)
2. **[Authenticate](https://www.elastic.co/elastic/docs-builder/docs/3016/extend/kibana/scout/api-auth)** with `requestAuth` (or `samlAuth` for `internal/*` endpoints)
3. **Call the endpoint under test** with `apiClient` + the scoped headers
4. **Assert** status + response body, and verify side effects when needed

See [best practices for API tests](/elastic/docs-builder/docs/3016/extend/kibana/scout/best-practices#api-tests).
Example test ([Console](https://github.com/elastic/kibana/blob/main/src/platform/plugins/shared/console/test/scout/api/tests/spec_definitions.spec.ts)).

## API matchers

For API tests, import `expect` from `@kbn/scout/api` or `@kbn/scout-<solution>/api` (more on [solution-specific Scout packages](/elastic/docs-builder/docs/3016/extend/kibana/scout#scout-packages)).
Scout provides response matchers for `apiClient` responses and `kbnClient.request(...)` (Axios) responses:
- `toHaveStatusCode(200)` (or `toHaveStatusCode({ oneOf: [200, 201] })`)
- `toHaveStatusText('OK')`
- `toHaveHeaders({ 'content-type': 'application/json; charset=utf-8' })` (partial match; header keys are case-insensitive)

These matchers do not apply to higher-level `kbnClient.*` helpers that return only `data`.
```ts
import type { RoleApiCredentials } from '@kbn/scout';
import { tags } from '@kbn/scout';
import { expect } from '@kbn/scout/api';
import { apiTest } from '../fixtures';

apiTest.describe('My endpoint', { tag: tags.deploymentAgnostic }, () => {
  let viewerRoleCredentials: RoleApiCredentials;

  apiTest.beforeAll(async ({ requestAuth }) => {
    viewerRoleCredentials = await requestAuth.getApiKeyForViewer();
  });

  apiTest('returns JSON', async ({ apiClient }) => {
    const res = await apiClient.get('api/my-plugin/endpoint', {
      headers: { ...viewerRoleCredentials.apiKeyHeader, 'kbn-xsrf': 'scout' },
      responseType: 'json',
    });

    expect(res).toHaveStatusCode(200);
    expect(res).toHaveHeaders({ 'content-type': 'application/json; charset=utf-8' });
    expect(res.body).toMatchObject({ ok: true });
  });
});
```


## Save the test file

API tests live under `<plugin-root>/test/scout/api/tests` and must end with `.spec.ts`.

## Next steps

- [API authentication](https://www.elastic.co/elastic/docs-builder/docs/3016/extend/kibana/scout/api-auth)
- [Best practices](https://www.elastic.co/elastic/docs-builder/docs/3016/extend/kibana/scout/best-practices)
- [Fixtures](https://www.elastic.co/elastic/docs-builder/docs/3016/extend/kibana/scout/fixtures)
- [Run tests](https://www.elastic.co/elastic/docs-builder/docs/3016/extend/kibana/scout/run-tests) and [Debugging](https://www.elastic.co/elastic/docs-builder/docs/3016/extend/kibana/scout/debugging)
- [Parallelism notes](/elastic/docs-builder/docs/3016/extend/kibana/scout/parallelism#api-tests-and-parallelism)