@nifrajs/e2e 0.0.0-stage → 5.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/CHANGELOG.md +37 -0
  2. package/LICENSE +21 -0
  3. package/README.md +127 -2
  4. package/dist/agent.d.ts +119 -0
  5. package/dist/agent.d.ts.map +1 -0
  6. package/dist/agent.js +312 -0
  7. package/dist/agent.js.map +1 -0
  8. package/dist/cache.d.ts +84 -0
  9. package/dist/cache.d.ts.map +1 -0
  10. package/dist/cache.js +162 -0
  11. package/dist/cache.js.map +1 -0
  12. package/dist/decision.d.ts +54 -0
  13. package/dist/decision.d.ts.map +1 -0
  14. package/dist/decision.js +122 -0
  15. package/dist/decision.js.map +1 -0
  16. package/dist/engine.d.ts +75 -0
  17. package/dist/engine.d.ts.map +1 -0
  18. package/dist/engine.js +13 -0
  19. package/dist/engine.js.map +1 -0
  20. package/dist/evidence.d.ts +14 -0
  21. package/dist/evidence.d.ts.map +1 -0
  22. package/dist/evidence.js +49 -0
  23. package/dist/evidence.js.map +1 -0
  24. package/dist/expect.d.ts +28 -0
  25. package/dist/expect.d.ts.map +1 -0
  26. package/dist/expect.js +88 -0
  27. package/dist/expect.js.map +1 -0
  28. package/dist/fake.d.ts +35 -0
  29. package/dist/fake.d.ts.map +1 -0
  30. package/dist/fake.js +124 -0
  31. package/dist/fake.js.map +1 -0
  32. package/dist/index.d.ts +11 -0
  33. package/dist/index.d.ts.map +1 -0
  34. package/dist/index.js +8 -0
  35. package/dist/index.js.map +1 -0
  36. package/dist/internal/record.d.ts +3 -0
  37. package/dist/internal/record.d.ts.map +1 -0
  38. package/dist/internal/record.js +4 -0
  39. package/dist/internal/record.js.map +1 -0
  40. package/dist/locator.d.ts +53 -0
  41. package/dist/locator.d.ts.map +1 -0
  42. package/dist/locator.js +102 -0
  43. package/dist/locator.js.map +1 -0
  44. package/dist/params.d.ts +44 -0
  45. package/dist/params.d.ts.map +1 -0
  46. package/dist/params.js +93 -0
  47. package/dist/params.js.map +1 -0
  48. package/dist/playwright.d.ts +72 -0
  49. package/dist/playwright.d.ts.map +1 -0
  50. package/dist/playwright.js +165 -0
  51. package/dist/playwright.js.map +1 -0
  52. package/dist/replay.d.ts +34 -0
  53. package/dist/replay.d.ts.map +1 -0
  54. package/dist/replay.js +105 -0
  55. package/dist/replay.js.map +1 -0
  56. package/dist/route.d.ts +7 -0
  57. package/dist/route.d.ts.map +1 -0
  58. package/dist/route.js +20 -0
  59. package/dist/route.js.map +1 -0
  60. package/dist/session.d.ts +62 -0
  61. package/dist/session.d.ts.map +1 -0
  62. package/dist/session.js +98 -0
  63. package/dist/session.js.map +1 -0
  64. package/dist/snapshot.d.ts +8 -0
  65. package/dist/snapshot.d.ts.map +1 -0
  66. package/dist/snapshot.js +44 -0
  67. package/dist/snapshot.js.map +1 -0
  68. package/package.json +73 -4
  69. package/src/agent.ts +525 -0
  70. package/src/cache.ts +229 -0
  71. package/src/decision.ts +152 -0
  72. package/src/engine.ts +92 -0
  73. package/src/evidence.ts +58 -0
  74. package/src/expect.ts +171 -0
  75. package/src/fake.ts +185 -0
  76. package/src/index.ts +64 -0
  77. package/src/internal/record.ts +5 -0
  78. package/src/locator.ts +157 -0
  79. package/src/params.ts +128 -0
  80. package/src/playwright.ts +237 -0
  81. package/src/replay.ts +153 -0
  82. package/src/route.ts +26 -0
  83. package/src/session.ts +178 -0
  84. package/src/snapshot.ts +46 -0
package/src/expect.ts ADDED
@@ -0,0 +1,171 @@
1
+ import { E2EError, type ElementState } from "./engine.ts"
2
+ import { Locator, type LocatorContext } from "./locator.ts"
3
+
4
+ export interface MatcherOptions {
5
+ /** Overrides the session's `assertionTimeout` for this assertion, in ms. */
6
+ readonly timeout?: number
7
+ }
8
+
9
+ /** Anything with a current URL; `E2ESession` is one. */
10
+ export interface UrlSource {
11
+ readonly context: LocatorContext
12
+ url(): Promise<string>
13
+ /** Path plus query of the current URL. */
14
+ path(): Promise<string>
15
+ }
16
+
17
+ export interface LocatorMatchers {
18
+ toBeVisible(options?: MatcherOptions): Promise<void>
19
+ toBeHidden(options?: MatcherOptions): Promise<void>
20
+ toHaveText(expected: string | RegExp, options?: MatcherOptions): Promise<void>
21
+ toContainText(expected: string | RegExp, options?: MatcherOptions): Promise<void>
22
+ toHaveCount(expected: number, options?: MatcherOptions): Promise<void>
23
+ toHaveValue(expected: string | RegExp, options?: MatcherOptions): Promise<void>
24
+ readonly not: LocatorMatchers
25
+ }
26
+
27
+ export interface UrlMatchers {
28
+ toHaveURL(expected: string | RegExp, options?: MatcherOptions): Promise<void>
29
+ readonly not: UrlMatchers
30
+ }
31
+
32
+ interface Outcome {
33
+ readonly pass: boolean
34
+ readonly received: string
35
+ /** The page cannot answer yet (for example, several elements for a one-element matcher): neither the assertion nor its negation holds. */
36
+ readonly indeterminate?: true
37
+ }
38
+
39
+ const normalize = (text: string): string => text.replace(/\s+/g, " ").trim()
40
+
41
+ function matches(received: string, expected: string | RegExp, substring: boolean): boolean {
42
+ if (typeof expected !== "string") return expected.test(received)
43
+ return substring
44
+ ? normalize(received).includes(normalize(expected))
45
+ : normalize(received) === normalize(expected)
46
+ }
47
+
48
+ function single(states: readonly ElementState[], check: (state: ElementState) => Outcome): Outcome {
49
+ const [only] = states
50
+ if (only === undefined) return { pass: false, received: "no element" }
51
+ if (states.length > 1) {
52
+ return { pass: false, received: `${states.length} elements, expected one`, indeterminate: true }
53
+ }
54
+ return check(only)
55
+ }
56
+
57
+ async function retry(
58
+ context: LocatorContext,
59
+ timeout: number,
60
+ negate: boolean,
61
+ describe: string,
62
+ evaluate: () => Promise<Outcome>,
63
+ ): Promise<void> {
64
+ const deadline = context.clock.now() + timeout
65
+ for (;;) {
66
+ const outcome = await evaluate()
67
+ if (outcome.indeterminate !== true && outcome.pass !== negate) {
68
+ await context.onCheck?.(true)
69
+ return
70
+ }
71
+ const remaining = deadline - context.clock.now()
72
+ if (remaining <= 0) {
73
+ await context.onCheck?.(false)
74
+ throw new E2EError(
75
+ "EXPECT_FAILED",
76
+ `expected ${negate ? "not " : ""}${describe}, received ${outcome.received} (after ${timeout} ms)`,
77
+ )
78
+ }
79
+ await context.clock.sleep(Math.min(context.pollInterval, remaining))
80
+ }
81
+ }
82
+
83
+ function locatorMatchers(locator: Locator, negate: boolean): LocatorMatchers {
84
+ const { context } = locator
85
+ const run = (
86
+ describe: string,
87
+ options: MatcherOptions | undefined,
88
+ evaluate: (states: readonly ElementState[]) => Outcome,
89
+ ): Promise<void> =>
90
+ retry(
91
+ context,
92
+ options?.timeout ?? context.assertionTimeout,
93
+ negate,
94
+ `${locator.describe()} ${describe}`,
95
+ async () => evaluate(await locator.states()),
96
+ )
97
+ return {
98
+ toBeVisible: (options) =>
99
+ run("to be visible", options, (states) =>
100
+ single(states, (s) => ({ pass: s.visible, received: s.visible ? "visible" : "hidden" })),
101
+ ),
102
+ toBeHidden: (options) =>
103
+ run("to be hidden", options, (states) => {
104
+ const shown = states.filter((s) => s.visible).length
105
+ return { pass: shown === 0, received: `${shown} visible` }
106
+ }),
107
+ toHaveText: (expected, options) =>
108
+ run(`to have text ${String(expected)}`, options, (states) =>
109
+ single(states, (s) => ({
110
+ pass: matches(s.text, expected, false),
111
+ received: JSON.stringify(normalize(s.text)),
112
+ })),
113
+ ),
114
+ toContainText: (expected, options) =>
115
+ run(`to contain text ${String(expected)}`, options, (states) =>
116
+ single(states, (s) => ({
117
+ pass: matches(s.text, expected, true),
118
+ received: JSON.stringify(normalize(s.text)),
119
+ })),
120
+ ),
121
+ toHaveCount: (expected, options) =>
122
+ run(`to have count ${expected}`, options, (states) => ({
123
+ pass: states.length === expected,
124
+ received: String(states.length),
125
+ })),
126
+ toHaveValue: (expected, options) =>
127
+ run(`to have value ${String(expected)}`, options, (states) =>
128
+ single(states, (s) => {
129
+ const value = s.value ?? ""
130
+ return {
131
+ pass: typeof expected === "string" ? value === expected : expected.test(value),
132
+ received: JSON.stringify(value),
133
+ }
134
+ }),
135
+ ),
136
+ get not() {
137
+ return locatorMatchers(locator, !negate)
138
+ },
139
+ }
140
+ }
141
+
142
+ function urlMatchers(source: UrlSource, negate: boolean): UrlMatchers {
143
+ return {
144
+ toHaveURL: (expected, options) =>
145
+ retry(
146
+ source.context,
147
+ options?.timeout ?? source.context.assertionTimeout,
148
+ negate,
149
+ `URL to be ${String(expected)}`,
150
+ async () => {
151
+ const received =
152
+ typeof expected === "string" && expected.startsWith("/")
153
+ ? await source.path()
154
+ : await source.url()
155
+ return {
156
+ pass: typeof expected === "string" ? received === expected : expected.test(received),
157
+ received,
158
+ }
159
+ },
160
+ ),
161
+ get not() {
162
+ return urlMatchers(source, !negate)
163
+ },
164
+ }
165
+ }
166
+
167
+ export function expect(subject: Locator): LocatorMatchers
168
+ export function expect(subject: UrlSource): UrlMatchers
169
+ export function expect(subject: Locator | UrlSource): LocatorMatchers | UrlMatchers {
170
+ return subject instanceof Locator ? locatorMatchers(subject, false) : urlMatchers(subject, false)
171
+ }
package/src/fake.ts ADDED
@@ -0,0 +1,185 @@
1
+ import {
2
+ E2EError,
3
+ type ElementAction,
4
+ type ElementState,
5
+ type Engine,
6
+ type EngineFactory,
7
+ type Selector,
8
+ type Step,
9
+ } from "./engine.ts"
10
+
11
+ /** A node of the in-memory page tree the fake engine matches locators against. */
12
+ export interface FakeNode {
13
+ role?: string
14
+ /** Accessible name, matched by `getByRole(role, name)`. */
15
+ name?: string
16
+ /** Own text, matched by `getByText`. */
17
+ text?: string
18
+ testId?: string
19
+ /** Label text, matched by `getByLabel`. */
20
+ label?: string
21
+ value?: string
22
+ hidden?: boolean
23
+ children?: FakeNode[]
24
+ }
25
+
26
+ export interface FakeLogEntry {
27
+ readonly kind: "goto" | ElementAction["kind"]
28
+ readonly detail: string
29
+ }
30
+
31
+ export interface FakeEngineOptions {
32
+ /** Pages by `pathname + search`, falling back to bare `pathname`. */
33
+ readonly pages: Readonly<Record<string, readonly FakeNode[]>>
34
+ /** Runs after a tap or press on the matched node; return a path to navigate to it. */
35
+ readonly onAct?: (node: FakeNode, action: ElementAction) => string | undefined
36
+ }
37
+
38
+ interface Found {
39
+ readonly node: FakeNode
40
+ readonly visible: boolean
41
+ }
42
+
43
+ const normalize = (text: string): string => text.replace(/\s+/g, " ").trim()
44
+
45
+ function textMatches(value: string, wanted: string, exact: boolean | undefined): boolean {
46
+ return exact === true
47
+ ? normalize(value) === normalize(wanted)
48
+ : normalize(value).toLowerCase().includes(normalize(wanted).toLowerCase())
49
+ }
50
+
51
+ function textOf(node: FakeNode): string {
52
+ return [node.text, ...(node.children ?? []).map(textOf)]
53
+ .filter((part) => part !== undefined && part !== "")
54
+ .join(" ")
55
+ }
56
+
57
+ function descend(nodes: readonly FakeNode[], hidden: boolean): Found[] {
58
+ return nodes.flatMap((node) => {
59
+ const isHidden = hidden || node.hidden === true
60
+ return [{ node, visible: !isHidden }, ...descend(node.children ?? [], isHidden)]
61
+ })
62
+ }
63
+
64
+ function accepts(step: Step, found: Found): boolean {
65
+ const { node } = found
66
+ switch (step.kind) {
67
+ case "role":
68
+ return (
69
+ node.role === step.role &&
70
+ (step.name === undefined || textMatches(node.name ?? "", step.name, step.exact))
71
+ )
72
+ case "label":
73
+ return node.label !== undefined && textMatches(node.label, step.text, step.exact)
74
+ case "text":
75
+ return node.text !== undefined && textMatches(node.text, step.text, step.exact)
76
+ case "testId":
77
+ return node.testId === step.id
78
+ case "hasText":
79
+ return textMatches(textOf(node), step.text, false)
80
+ case "nth":
81
+ return true
82
+ }
83
+ }
84
+
85
+ function run(roots: readonly FakeNode[], selector: Selector): Found[] {
86
+ let scope: Found[] = [{ node: { children: [...roots] }, visible: true }]
87
+ for (const step of selector) {
88
+ if (step.kind === "hasText") {
89
+ scope = scope.filter((found) => accepts(step, found))
90
+ continue
91
+ }
92
+ if (step.kind === "nth") {
93
+ scope = scope.slice(step.index, step.index + 1)
94
+ continue
95
+ }
96
+ const seen = new Set<FakeNode>()
97
+ scope = scope
98
+ .flatMap((found) => descend(found.node.children ?? [], !found.visible))
99
+ .filter((found) => accepts(step, found) && !seen.has(found.node) && seen.add(found.node))
100
+ }
101
+ return scope
102
+ }
103
+
104
+ function outline(nodes: readonly FakeNode[], depth: number): string[] {
105
+ return nodes.flatMap((node) => {
106
+ if (node.hidden === true) return []
107
+ const indent = " ".repeat(depth)
108
+ const head = node.role ?? (node.text === undefined ? undefined : "text")
109
+ const name = node.role !== undefined && node.name !== undefined ? ` "${node.name}"` : ""
110
+ const own = node.text === undefined ? "" : `: ${node.text}`
111
+ const children = outline(node.children ?? [], head === undefined ? depth : depth + 1)
112
+ return head === undefined ? children : [`${indent}- ${head}${name}${own}`, ...children]
113
+ })
114
+ }
115
+
116
+ function stateOf(found: Found): ElementState {
117
+ const text = textOf(found.node)
118
+ return found.node.value === undefined
119
+ ? { visible: found.visible, text }
120
+ : { visible: found.visible, text, value: found.node.value }
121
+ }
122
+
123
+ /**
124
+ * An in-memory engine for tests of code built on `@nifrajs/e2e`: no browser, same locator
125
+ * semantics (case-insensitive substring unless `exact`). It does not wait; an `act` on a missing
126
+ * element throws at once.
127
+ */
128
+ export function fakeEngine(options: FakeEngineOptions): {
129
+ factory: EngineFactory
130
+ log: FakeLogEntry[]
131
+ } {
132
+ const log: FakeLogEntry[] = []
133
+ const factory: EngineFactory = async () => {
134
+ let current = ""
135
+ let tree: FakeNode[] = []
136
+ const engine: Engine = {
137
+ async goto(url) {
138
+ const target = new URL(url)
139
+ const key = `${target.pathname}${target.search}`
140
+ const page = options.pages[key] ?? options.pages[target.pathname]
141
+ if (page === undefined) throw new E2EError("NAVIGATION_FAILED", `no fake page for ${key}`)
142
+ log.push({ kind: "goto", detail: key })
143
+ current = url
144
+ tree = structuredClone([...page])
145
+ },
146
+ async url() {
147
+ return current
148
+ },
149
+ async resolve(selector) {
150
+ return run(tree, selector).map(stateOf)
151
+ },
152
+ async snapshot() {
153
+ return outline(tree, 0).join("\n")
154
+ },
155
+ async act(selector, action) {
156
+ const found = run(tree, selector).filter((candidate) => candidate.visible)
157
+ const [match] = found
158
+ if (match === undefined)
159
+ throw new E2EError(
160
+ "LOCATOR_NOT_FOUND",
161
+ `no visible element for ${JSON.stringify(selector)}`,
162
+ )
163
+ if (found.length > 1)
164
+ throw new E2EError(
165
+ "LOCATOR_AMBIGUOUS",
166
+ `${found.length} elements for ${JSON.stringify(selector)}`,
167
+ )
168
+ const { node } = match
169
+ log.push({
170
+ kind: action.kind,
171
+ detail: action.kind === "fill" ? action.value : action.kind === "press" ? action.key : "",
172
+ })
173
+ if (action.kind === "fill") {
174
+ node.value = action.value
175
+ return
176
+ }
177
+ const next = options.onAct?.(node, action)
178
+ if (next !== undefined) await engine.goto(new URL(next, current).href)
179
+ },
180
+ async close() {},
181
+ }
182
+ return engine
183
+ }
184
+ return { factory, log }
185
+ }
package/src/index.ts ADDED
@@ -0,0 +1,64 @@
1
+ export type {
2
+ ActionRecord,
3
+ ActOptions,
4
+ ActRequest,
5
+ ActResult,
6
+ Agent,
7
+ AgentReport,
8
+ E2EModel,
9
+ ExtractOptions,
10
+ ExtractRequest,
11
+ HandOff,
12
+ JudgeRequest,
13
+ ModelRequest,
14
+ StepOptions,
15
+ WaitForOptions,
16
+ } from "./agent.ts"
17
+ export { formatReport } from "./agent.ts"
18
+ export {
19
+ type CacheEntry,
20
+ type CacheMode,
21
+ type CacheOptions,
22
+ type CacheStore,
23
+ fileCacheStore,
24
+ memoryCacheStore,
25
+ type RecordedAction,
26
+ } from "./cache.ts"
27
+ export type { ActDecision, PerformedDecision, Target, Verdict } from "./decision.ts"
28
+ export {
29
+ type Clock,
30
+ E2EError,
31
+ type E2EErrorCode,
32
+ type ElementAction,
33
+ type ElementState,
34
+ type Engine,
35
+ type EngineFactory,
36
+ type EngineInit,
37
+ type HydrationMode,
38
+ type Selector,
39
+ type Step,
40
+ } from "./engine.ts"
41
+ export {
42
+ expect,
43
+ type LocatorMatchers,
44
+ type MatcherOptions,
45
+ type UrlMatchers,
46
+ type UrlSource,
47
+ } from "./expect.ts"
48
+ export {
49
+ Locator,
50
+ type LocatorContext,
51
+ type RoleOptions,
52
+ Screen,
53
+ type TextOptions,
54
+ } from "./locator.ts"
55
+ export { type Param, type Params, Secret, Unique, unique } from "./params.ts"
56
+ export type { StopReason } from "./replay.ts"
57
+ export {
58
+ type E2EOptions,
59
+ type E2ESession,
60
+ e2e,
61
+ type OpenArgs,
62
+ type OpenOptions,
63
+ type PathParams,
64
+ } from "./session.ts"
@@ -0,0 +1,5 @@
1
+ /** A non-null, non-array object. The prototype is not checked: a `Date` or a `Map` passes. */
2
+ // biome-ignore lint/plugin/noHelperCopy: this is the e2e package's one owning module for isRecord.
3
+ export function isRecord(value: unknown): value is Record<string, unknown> {
4
+ return typeof value === "object" && value !== null && !Array.isArray(value)
5
+ }
package/src/locator.ts ADDED
@@ -0,0 +1,157 @@
1
+ import type { Clock, ElementState, Engine, Selector, Step } from "./engine.ts"
2
+
3
+ export interface LocatorContext {
4
+ readonly engine: Engine
5
+ readonly clock: Clock
6
+ readonly actionTimeout: number
7
+ readonly assertionTimeout: number
8
+ readonly pollInterval: number
9
+ /** Told when an assertion passes or fails, so the replay cache learns whether the steps before it held. */
10
+ readonly onCheck?: ((passed: boolean) => Promise<void>) | undefined
11
+ }
12
+
13
+ export interface TextOptions {
14
+ readonly exact?: boolean
15
+ }
16
+
17
+ export interface RoleOptions extends TextOptions {
18
+ readonly name?: string
19
+ }
20
+
21
+ interface Finders {
22
+ getByRole(role: string, nameOrOptions?: string | RoleOptions): Locator
23
+ getByLabel(text: string, options?: TextOptions): Locator
24
+ getByText(text: string, options?: TextOptions): Locator
25
+ getByTestId(id: string): Locator
26
+ }
27
+
28
+ function roleStep(role: string, nameOrOptions: string | RoleOptions | undefined): Step {
29
+ const options = typeof nameOrOptions === "string" ? { name: nameOrOptions } : nameOrOptions
30
+ const step: { kind: "role"; role: string; name?: string; exact?: boolean } = {
31
+ kind: "role",
32
+ role,
33
+ }
34
+ if (options?.name !== undefined) step.name = options.name
35
+ if (options?.exact !== undefined) step.exact = options.exact
36
+ return step
37
+ }
38
+
39
+ function textStep(kind: "label" | "text", text: string, options: TextOptions | undefined): Step {
40
+ const step: { kind: "label" | "text"; text: string; exact?: boolean } = { kind, text }
41
+ if (options?.exact !== undefined) step.exact = options.exact
42
+ return step
43
+ }
44
+
45
+ export class Locator implements Finders {
46
+ readonly context: LocatorContext
47
+ readonly selector: Selector
48
+
49
+ constructor(context: LocatorContext, selector: Selector) {
50
+ this.context = context
51
+ this.selector = selector
52
+ }
53
+
54
+ #then(step: Step): Locator {
55
+ return new Locator(this.context, [...this.selector, step])
56
+ }
57
+
58
+ getByRole(role: string, nameOrOptions?: string | RoleOptions): Locator {
59
+ return this.#then(roleStep(role, nameOrOptions))
60
+ }
61
+
62
+ getByLabel(text: string, options?: TextOptions): Locator {
63
+ return this.#then(textStep("label", text, options))
64
+ }
65
+
66
+ getByText(text: string, options?: TextOptions): Locator {
67
+ return this.#then(textStep("text", text, options))
68
+ }
69
+
70
+ getByTestId(id: string): Locator {
71
+ return this.#then({ kind: "testId", id })
72
+ }
73
+
74
+ nth(index: number): Locator {
75
+ return this.#then({ kind: "nth", index })
76
+ }
77
+
78
+ filter(options: { readonly hasText: string }): Locator {
79
+ return this.#then({ kind: "hasText", text: options.hasText })
80
+ }
81
+
82
+ states(): Promise<readonly ElementState[]> {
83
+ return this.context.engine.resolve(this.selector)
84
+ }
85
+
86
+ async count(): Promise<number> {
87
+ return (await this.states()).length
88
+ }
89
+
90
+ tap(): Promise<void> {
91
+ return this.context.engine.act(this.selector, { kind: "tap" }, this.context.actionTimeout)
92
+ }
93
+
94
+ fill(value: string): Promise<void> {
95
+ return this.context.engine.act(
96
+ this.selector,
97
+ { kind: "fill", value },
98
+ this.context.actionTimeout,
99
+ )
100
+ }
101
+
102
+ press(key: string): Promise<void> {
103
+ return this.context.engine.act(
104
+ this.selector,
105
+ { kind: "press", key },
106
+ this.context.actionTimeout,
107
+ )
108
+ }
109
+
110
+ describe(): string {
111
+ return this.selector.map(describeStep).join(" >> ")
112
+ }
113
+ }
114
+
115
+ function describeStep(step: Step): string {
116
+ switch (step.kind) {
117
+ case "role":
118
+ return step.name === undefined
119
+ ? `role=${step.role}`
120
+ : `role=${step.role}[name="${step.name}"]`
121
+ case "label":
122
+ return `label="${step.text}"`
123
+ case "text":
124
+ return `text="${step.text}"`
125
+ case "testId":
126
+ return `testId="${step.id}"`
127
+ case "hasText":
128
+ return `hasText="${step.text}"`
129
+ case "nth":
130
+ return `nth=${step.index}`
131
+ }
132
+ }
133
+
134
+ /** The page root: every chain starts here. */
135
+ export class Screen implements Finders {
136
+ readonly #root: Locator
137
+
138
+ constructor(context: LocatorContext) {
139
+ this.#root = new Locator(context, [])
140
+ }
141
+
142
+ getByRole(role: string, nameOrOptions?: string | RoleOptions): Locator {
143
+ return this.#root.getByRole(role, nameOrOptions)
144
+ }
145
+
146
+ getByLabel(text: string, options?: TextOptions): Locator {
147
+ return this.#root.getByLabel(text, options)
148
+ }
149
+
150
+ getByText(text: string, options?: TextOptions): Locator {
151
+ return this.#root.getByText(text, options)
152
+ }
153
+
154
+ getByTestId(id: string): Locator {
155
+ return this.#root.getByTestId(id)
156
+ }
157
+ }