---
title: Write Scout UI tests
description: Scout UI tests are Playwright tests that use Scout fixtures and page objects for readable, maintainable flows. Tags: every suite needs one or more deployment...
url: https://www.elastic.co/elastic/docs-builder/docs/3028/extend/kibana/scout/write-ui-tests
products:
  - Kibana
---

# Write Scout UI tests
Scout UI tests are Playwright tests that use Scout fixtures and page objects for readable, maintainable flows.
<important>
  [Set up your plugin or package](https://www.elastic.co/elastic/docs-builder/docs/3028/extend/kibana/scout/setup-plugin) first.
</important>


## The building blocks

- **Tags**: every suite needs one or more [deployment tags](https://www.elastic.co/elastic/docs-builder/docs/3028/extend/kibana/scout/deployment-tags) (use `tags.*`). Scout validates tags at runtime.
- **[Authentication](https://www.elastic.co/elastic/docs-builder/docs/3028/extend/kibana/scout/browser-auth)**: use `browserAuth` in `beforeEach` for a clean, readable flow.
- **Navigation + actions**: use `pageObjects` (preferred) or `page.gotoApp(...)`.
- **Selectors**: use `page.testSubj` for `data-test-subj`-based locators/actions.
- **Assertions**: import `expect` from your Scout package’s UI entrypoint (for example `@kbn/scout/ui` or `@kbn/scout-<solution>/ui`).


## Starter template (sequential UI test)

This pattern is a good default:
```ts
import { tags } from '@kbn/scout';
import { expect } from '@kbn/scout/ui';
import { test } from '../fixtures';

test.describe('My feature', { tag: tags.deploymentAgnostic }, () => {
  test.beforeEach(async ({ browserAuth, pageObjects }) => {
    await browserAuth.loginAsViewer();
    await pageObjects.discover.goto();
  });

  test('shows the main table', async ({ page }) => {
    await expect(page.testSubj.locator('discoverDocTable')).toBeVisible();
  });
});
```

<tip>
  Prefer APIs for setup/cleanup (for example `apiServices`, `kbnClient`) in `beforeAll`/`afterAll` instead of doing expensive setup through the UI. If the same one-time setup is shared across many suites (archives, ingest, settings), move it to a [global setup hook](https://www.elastic.co/elastic/docs-builder/docs/3028/extend/kibana/scout/global-setup-hook).
</tip>


## Parallel UI tests (recommended)

If your suite can be isolated, put it under `parallel_tests/` and use `spaceTest` to get one Space per worker via `scoutSpace`. See [Parallelism](https://www.elastic.co/elastic/docs-builder/docs/3028/extend/kibana/scout/parallelism) and the [global setup hook](https://www.elastic.co/elastic/docs-builder/docs/3028/extend/kibana/scout/global-setup-hook).

## Save the test file

- Sequential UI tests: `<plugin-root>/test/scout/ui/tests`
- Parallel UI tests: `<plugin-root>/test/scout/ui/parallel_tests`

Spec files must end with `.spec.ts`.

## Next steps

- [Browser authentication](https://www.elastic.co/elastic/docs-builder/docs/3028/extend/kibana/scout/browser-auth)
- [Deployment tags](https://www.elastic.co/elastic/docs-builder/docs/3028/extend/kibana/scout/deployment-tags)
- [Best practices](https://www.elastic.co/elastic/docs-builder/docs/3028/extend/kibana/scout/best-practices)
- [Page objects](https://www.elastic.co/elastic/docs-builder/docs/3028/extend/kibana/scout/page-objects)
- [Fixtures](https://www.elastic.co/elastic/docs-builder/docs/3028/extend/kibana/scout/fixtures)
- [Accessibility (a11y) checks](https://www.elastic.co/elastic/docs-builder/docs/3028/extend/kibana/scout/a11y-checks)
- [Run tests](https://www.elastic.co/elastic/docs-builder/docs/3028/extend/kibana/scout/run-tests) and [Debugging](https://www.elastic.co/elastic/docs-builder/docs/3028/extend/kibana/scout/debugging)