@nifrajs/e2e 0.0.0-stage → 5.13.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.
- package/CHANGELOG.md +23 -0
- package/LICENSE +21 -0
- package/README.md +127 -2
- package/dist/agent.d.ts +119 -0
- package/dist/agent.d.ts.map +1 -0
- package/dist/agent.js +315 -0
- package/dist/agent.js.map +1 -0
- package/dist/cache.d.ts +84 -0
- package/dist/cache.d.ts.map +1 -0
- package/dist/cache.js +166 -0
- package/dist/cache.js.map +1 -0
- package/dist/decision.d.ts +54 -0
- package/dist/decision.d.ts.map +1 -0
- package/dist/decision.js +122 -0
- package/dist/decision.js.map +1 -0
- package/dist/engine.d.ts +75 -0
- package/dist/engine.d.ts.map +1 -0
- package/dist/engine.js +13 -0
- package/dist/engine.js.map +1 -0
- package/dist/evidence.d.ts +14 -0
- package/dist/evidence.d.ts.map +1 -0
- package/dist/evidence.js +52 -0
- package/dist/evidence.js.map +1 -0
- package/dist/expect.d.ts +28 -0
- package/dist/expect.d.ts.map +1 -0
- package/dist/expect.js +88 -0
- package/dist/expect.js.map +1 -0
- package/dist/fake.d.ts +35 -0
- package/dist/fake.d.ts.map +1 -0
- package/dist/fake.js +129 -0
- package/dist/fake.js.map +1 -0
- package/dist/index.d.ts +11 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +8 -0
- package/dist/index.js.map +1 -0
- package/dist/internal/record.d.ts +3 -0
- package/dist/internal/record.d.ts.map +1 -0
- package/dist/internal/record.js +6 -0
- package/dist/internal/record.js.map +1 -0
- package/dist/locator.d.ts +53 -0
- package/dist/locator.d.ts.map +1 -0
- package/dist/locator.js +103 -0
- package/dist/locator.js.map +1 -0
- package/dist/params.d.ts +44 -0
- package/dist/params.d.ts.map +1 -0
- package/dist/params.js +108 -0
- package/dist/params.js.map +1 -0
- package/dist/playwright.d.ts +72 -0
- package/dist/playwright.d.ts.map +1 -0
- package/dist/playwright.js +169 -0
- package/dist/playwright.js.map +1 -0
- package/dist/replay.d.ts +34 -0
- package/dist/replay.d.ts.map +1 -0
- package/dist/replay.js +111 -0
- package/dist/replay.js.map +1 -0
- package/dist/route.d.ts +7 -0
- package/dist/route.d.ts.map +1 -0
- package/dist/route.js +26 -0
- package/dist/route.js.map +1 -0
- package/dist/session.d.ts +62 -0
- package/dist/session.d.ts.map +1 -0
- package/dist/session.js +105 -0
- package/dist/session.js.map +1 -0
- package/dist/snapshot.d.ts +8 -0
- package/dist/snapshot.d.ts.map +1 -0
- package/dist/snapshot.js +49 -0
- package/dist/snapshot.js.map +1 -0
- package/package.json +73 -4
- package/src/agent.ts +525 -0
- package/src/cache.ts +229 -0
- package/src/decision.ts +152 -0
- package/src/engine.ts +92 -0
- package/src/evidence.ts +58 -0
- package/src/expect.ts +171 -0
- package/src/fake.ts +185 -0
- package/src/index.ts +64 -0
- package/src/internal/record.ts +5 -0
- package/src/locator.ts +157 -0
- package/src/params.ts +128 -0
- package/src/playwright.ts +236 -0
- package/src/replay.ts +153 -0
- package/src/route.ts +26 -0
- package/src/session.ts +178 -0
- 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
|
+
}
|