AGENTS.md

1# Alerting e2e tests — agent guide
2 
3This guide documents conventions for Playwright e2e tests under
4`e2e-playwright/alerting-suite/`. Follow it when adding or modifying specs in this
5directory.
6 
7## Test isolation and parallelism
8 
9Playwright's global config sets `fullyParallel: true`, which distributes individual
10tests (not just files) across workers. The implications:
11 
12- `beforeAll` / `afterAll` run **once per worker**, not once per file. With shared
13  module-scoped state, every worker that picks up a test runs its own setup, creating
14  duplicate resources (and resulting in strict-mode locator violations or 409s).
15- Prefer `beforeEach` / `afterEach`. Each test owns its own resources, no shared
16  module-scoped state to reason about, and parallel workers can't collide.
17- Reach for `test.describe.configure({ mode: 'serial' })` only when shared state is
18  unavoidable. It pins all tests in the file to a single worker, sacrificing
19  parallelism for setup-cost reuse.
20 
21## Unique resource names
22 
23When the test creates server-side resources (folders, groups, rules), the name needs
24to be unique **per invocation** — not per test definition.
25 
26- Use `crypto.randomUUID().slice(0, 8)` (or similar) generated inside `beforeEach`.
27  Each run produces a fresh name; parallel workers can't collide; orphans from a
28  crashed previous run don't accumulate under the same title.
29- Do **not** use `testInfo.testId` — it's stable across runs, so the same orphaned
30  name keeps reappearing. Same applies to fixed names or `Date.now()` at module
31  scope.
32- Do **not** add pre-create cleanup loops to compensate for stable names. That's a
33  workaround for using the wrong identifier.
34 
35## Cleanup via cascade
36 
37Each test owns one folder, created in `beforeEach`. Everything the test seeds lives
38inside that folder. The `afterEach` deletes the folder with
39`?forceDeleteRules=true`, which cascade-deletes all rule groups, rules, and seeded
40data within.
41 
42- Don't add per-resource cleanup hooks when the parent folder cascade covers it.
43- The k8s `alertrule` API stores the folder reference under
44  `metadata.annotations['grafana.app/folder']` — those rules are also caught by
45  the folder cascade.
46- One DELETE call per test is faster and partial-failure-safe vs. per-group
47  cleanup.
48 
49## Realistic test data
50 
51Use names that look like real alerting entities. Examples in this suite:
52 
53- Folders: `Infrastructure alerts <suffix>`
54- Groups: `disk-alerts`, `infra-monitoring`, `platform-alerts`
55- Rules: `High CPU usage`, `Disk space low`, `Memory pressure`, `Node load average`
56- Seeded placeholders: `Node disk read latency`, `Pod restart rate`, `HTTP error rate`
57 
58Avoid `E2E ...`, `e2e-seed-...`, or other test-betraying prefixes — they bleed into
59the UI, the API, and any screenshots/traces, making the test data look fake even
60when it covers real flows.
61 
62## Page Object Models (POMs)
63 
64Encapsulate UI interactions in class-based POMs under `pages/`. The existing
65`AlertRuleEditPage` and `AlertRuleViewPage` demonstrate the pattern. Add new POMs
66for new pages or for substantial subviews; do not inline complex locator logic in
67specs.
68 
69### Structure
70 
71- One class per page or distinct view (`AlertRuleEditPage`, `AlertRuleViewPage`,
72  `ContactPointsPage`, `SilencesListPage`, …).
73- Constructor takes the Playwright `Page` and stashes it as a private field.
74- High-level actions are public async methods that describe user intent
75  (`setEvaluationInterval`, `useExistingGroup`, `setManualRouting`) — not raw
76  click/fill operations.
77- Locators that tests assert against (e.g. `nameHeading`, `evaluationIntervalText`)
78  are public getters returning `Locator`. Locators that are only used internally
79  are `protected` or `private`.
80 
81### Locator strategy
82 
83- Prefer accessibility queries: `getByRole`, `getByLabel`, `getByText`.
84- Reach for `getByTestId` only when the component has no stable accessible name.
85  If you find yourself adding a testid, consider whether the underlying component
86  should expose an accessible name instead.
87- When a label double-matches because of `<Field>` description-bleed, target the
88  input by id or use a more specific role query rather than papering over it with
89  `.first()`.
90- For tree/list items that can appear in multiple sections (breadcrumbs vs.
91  sidebar vs. metadata strip), scope the query (`getByRole('group', { name })`
92  then drill in).
93 
94### Documentation
95 
96- Comment non-obvious locator choices inline — particularly when you've worked
97  around a UI quirk (e.g. label double-match, dropdown race, hidden-when-flag-off
98  inputs). Skip JSDoc for self-explanatory methods/getters; the comments should
99  earn their place by explaining _why_ a selector looks the way it does.
100 
101## Authentication
102 
103All tests use the `request` and `page` fixtures from `@grafana/plugin-e2e`. Auth
104is wired up at the project level in `playwright.config.ts` via `withAuth(...)`,
105which adds the `authenticate` setup project as a dependency and points the test at
106a saved storage state file.
107 
108**Gotcha:** Playwright applies CLI file filters to dependency projects too. So
109`yarn e2e:pw --project=alerting e2e-playwright/alerting-suite/foo.spec.ts` will
110also filter the `authenticate` project's `auth.setup.js`, find no matches, and
111skip generating the storage state — every API call then 403s.
112 
113Workarounds:
114 
1151. Run the setup project explicitly first:
116```sh
117   yarn e2e:pw --project=authenticate
118   yarn e2e:pw --project=alerting --reporter=line e2e-playwright/alerting-suite/foo.spec.ts
119```
1202. Use `--grep` instead of a file path — title filters don't break dependency
121   projects:
122```sh
123   yarn e2e:pw --project=alerting --reporter=line --grep &quot;your test title&quot;
124```
125 
126## SQLite / dev-env caveats
127 
128The e2e Grafana instance uses SQLite with a small `max_open_conn` cap
129(`scripts/grafana-server/custom.ini`). Under sustained parallel writes you'll
130see flakes like `SQLITE_BUSY`, `sqlstore.max-retries-reached`, or 403s from
131request handlers giving up. If the test logic looks correct, suspect the
132connection pool before suspecting the test.
133 
134## File organization
135 
136Top-down: imports, config, shared state, hooks, `test.describe` blocks, then
137helpers at the bottom. TypeScript hoists function declarations, so helpers can
138be referenced from earlier test bodies.
139 
140## Spec authoring
141 
142Title tests by behavior, not mechanics. Push complex locator/action logic into
143POM methods. Assert visible outcomes (rendered values, breadcrumbs, errors),
144not internal state.
145