Skip to content

[Scout] Improve Scout Deployment tags article #260229

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
csr merged 2 commits into from
Mar 30, 2026
Merged

[Scout] Improve Scout Deployment tags article #260229

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
91e4167
improve Scout Deployment tags doc
csr Mar 30, 2026
c839568
add icon for "classic" solution view
csr Mar 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 56 additions & 29 deletions docs/extend/scout/deployment-tags.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,47 +18,68 @@ Where:

## Use the `tags` helper [scout-deployment-tags-using]

Prefer the `tags` helper exported by Scout instead of writing raw strings. It returns arrays of Playwright tags you can use directly or combine.
Use the `tags` helper (see the full list below) to declare where your tests should run. By default, each helper expands to **both** `@local-*` and `@cloud-*` targets:

```ts
import { test, tags } from '@kbn/scout';

test.describe('My suite', { tag: tags.deploymentAgnostic }, () => {
test('works', async () => {
test.describe(
'My suite',
{ tag: [...tags.stateful.classic, ...tags.serverless.security.complete] },
() => {
// ...
});
});
}
);
Comment on lines +24 to +30
Copy link
Copy Markdown
Member Author

@csr csr Mar 30, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated: we show an example using a set of combination of tags teams are very likely to use (tags.deploymentAgnostic is mostly reserved for Platform tests that need to run on all stateful + serverless complete project types). We update our guidance on deployment tags to stop mentioning "we recommend it in most cases".

```

Combine multiple targets by spreading:
This is equivalent to assigning all of these tags:

- `@local-stateful-*` (local stateful)
- `@cloud-stateful-*` (Elastic Cloud)
- `@local-serverless-security_complete` (local serverless)
- `@cloud-serverless-security_complete` (Elastic Cloud)

To restrict a test to **local environments** only, write the tag strings explicitly:

```ts
test.describe('My suite', { tag: [...tags.stateful.classic, ...tags.serverless.search] }, () => {
// ...
});
test.describe(
'My suite',
{ tag: ['@local-stateful-classic', '@local-serverless-security_complete'] },
() => {
// ...
}
);
```

This test will only run locally (stateful classic and serverless Security complete tier), and will be skipped by Elastic Cloud pipelines.
Copy link
Copy Markdown
Member Author

@csr csr Mar 30, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

New: we now show developers how they can exclude their tests from running on Elastic Cloud.


## Common shortcuts [scout-deployment-tags-shortcuts]

Unless stated otherwise, these helpers include **both** `@local-*` and `@cloud-*` targets.
### `tags.deploymentAgnostic` [scout-deployment-tags-deployment-agnostic]

### Cross-cutting helpers [scout-deployment-tags-cross-cutting]
Use this tag for **platform** specs that need to run across every standard deployment type. It expands to:

| Helper | What it targets |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tags.deploymentAgnostic` | **Recommended if your test can run (almost) everywhere**: includes stateful + serverless `*.complete`. Excludes serverless Workplace AI projects (as they don't have a stateful counterpart). |
| `tags.performance` | Performance tests (`@perf`) |
- `tags.stateful.all`
- `tags.serverless.search`
- `tags.serverless.observability.complete`
- `tags.serverless.security.complete`

### Stateful (by domain) [scout-deployment-tags-stateful]
Workplace AI is excluded because it has no stateful counterpart.

| Helper | Domain |
::::{warning}
`tags.deploymentAgnostic` runs your test across all solutions, which is expensive. If your test lives in a solution module, use explicit targets instead (e.g. `[...tags.stateful.classic, ...tags.serverless.observability.complete]`).
::::

### Stateful [scout-deployment-tags-stateful]

| Helper | Compatible with solution view |
| ----------------------------- | ---------------------------------------- |
| `tags.stateful.all` | All stateful targets |
| `tags.stateful.classic` | Classic |
| `tags.stateful.search` | {icon}`logo_elasticsearch` Search |
| `tags.stateful.all` | All space solution views |
| `tags.stateful.classic` | {icon}`logo_elastic_stack` Classic |
| `tags.stateful.search` | {icon}`logo_elasticsearch` Elasticsearch |
| `tags.stateful.observability` | {icon}`logo_observability` Observability |
| `tags.stateful.security` | {icon}`logo_security` Security |

The target solution view indicates the **solution view** the test is intended for, but is not enforced at test execution time. To set the solution view in a test, use `scoutSpace.setSolutionView()`.
Copy link
Copy Markdown
Member Author

@csr csr Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

New: we explain what the solution portion of stateful tags refers to the Kibana Space-specific "target solution view" the tests are compatible with.


### Serverless (by solution) [scout-deployment-tags-serverless]

#### All serverless targets [scout-deployment-tags-serverless-all]
Expand All @@ -77,23 +98,29 @@ Unless stated otherwise, these helpers include **both** `@local-*` and `@cloud-*

| Helper | Project type |
| ----------------------------------------------- | ---------------------------------------------------------- |
| `tags.serverless.observability.complete` | {icon}`logo_observability` Observability (complete) |
| `tags.serverless.observability.logs_essentials` | {icon}`logo_observability` Observability (logs_essentials) |
| `tags.serverless.observability.all` | {icon}`logo_observability` All Observability project tiers |
Copy link
Copy Markdown
Member Author

@csr csr Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add missing: tags.serverless.observability.all

| `tags.serverless.observability.complete` | {icon}`logo_observability` Observability (Complete) |
| `tags.serverless.observability.logs_essentials` | {icon}`logo_observability` Observability (Logs Essentials) |

#### Security [scout-deployment-tags-serverless-security]

| Helper | Project type |
| ------------------------------------- | ------------------------------------------- |
| `tags.serverless.security.complete` | {icon}`logo_security` Security (complete) |
| `tags.serverless.security.essentials` | {icon}`logo_security` Security (essentials) |
| `tags.serverless.security.ease` | {icon}`logo_security` Security (ease) |
| Helper | Project type |
| ------------------------------------- | ------------------------------------------------ |
| `tags.serverless.security.all` | {icon}`logo_security` All Security project tiers |
Copy link
Copy Markdown
Member Author

@csr csr Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add missing: tags.serverless.security.all

| `tags.serverless.security.complete` | {icon}`logo_security` Security (Complete) |
| `tags.serverless.security.essentials` | {icon}`logo_security` Security (Essentials) |
| `tags.serverless.security.ease` | {icon}`logo_security` Security (EASE) |

#### Workplace AI [scout-deployment-tags-serverless-workplaceai]

| Helper | Project type |
| ----------------------------- | ------------------------------------------ |
| `tags.serverless.workplaceai` | {icon}`logo_workplace_search` Workplace AI |

### `tags.performance` [scout-deployment-tags-performance]
Copy link
Copy Markdown
Member Author

@csr csr Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Move to the bottom as performance tags aren't as popular as the other tags listed above.


Use `tags.performance` for performance tests. It assigns the `@perf` tag.

For the authoritative list (and the exact tag strings), see `src/platform/packages/shared/kbn-scout/src/playwright/tags.ts` or just rely on editor autocomplete.

::::::{note}
Expand Down
Loading