@testra-studio/kit 0.0.0-stage → 0.2.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.
@@ -0,0 +1,171 @@
1
+ /**
2
+ * Plain-English tests: a test as data, `<name>.steps.json` (its schema is
3
+ * `schemas/steps.schema.json`), beside a two-line `<name>.e2e.ts` that runs
4
+ * it through the app's own `support/plain.ts`. People write them in e2e
5
+ * Studio or by hand, and review them like code.
6
+ *
7
+ * ```json
8
+ * {
9
+ * "title": "a transferred task shows in My Work",
10
+ * "requires": ["someFeature"],
11
+ * "steps": [
12
+ * { "block": "work-order-with-task", "as": "work1", "with": { "description": "Pump leaking" } },
13
+ * { "block": "send-to-mobile", "with": { "work": "{work1}" } },
14
+ * { "do": "Search for {work1.description}" },
15
+ * { "waitUntil": "The list has finished loading" },
16
+ * { "check": "Assignment {work1.reference} is listed at {basic.site.name}", "when": "!someFeature" },
17
+ * { "verify": "work-assignment-state", "with": { "work": "{work1}", "state": "Assigned" } }
18
+ * ]
19
+ * }
20
+ * ```
21
+ *
22
+ * - `do`, `check` and `waitUntil` are sentences the agent carries out or
23
+ * judges (`agent.act`, `agent.assert`, `agent.waitFor`).
24
+ * - `block` calls one of the app's building blocks (`e2e-studio.blocks.json`): code that
25
+ * sets something up the screen does not, such as data made through an
26
+ * API. `as` names its result for later steps; `with` fills its fields.
27
+ * - `verify` calls one of the app's checks (`checks` in the same file): code
28
+ * that waits until the system holds what the test expects, and fails with
29
+ * what it holds instead. `with` fills its fields.
30
+ * - `{basic.<item>.<field>}` is the instance's basic data, such as
31
+ * `{basic.site.code}`; `{<name>.<value>}` is a value an earlier block
32
+ * returned; `{<name>}` alone, in a block field, is its whole result.
33
+ * - `requires` lists features the whole test needs: without them it is
34
+ * skipped, with the reason. `when` runs one step only with a feature, or
35
+ * only without it (`"!feature"`). The features, and whether a run has each,
36
+ * are the project's to say (`PlainOptions.features`).
37
+ *
38
+ * A file is checked when the tests are listed, so a mistake in one fails
39
+ * `npm run list` (and CI) by file and step, before anything runs.
40
+ *
41
+ * The app's `support/plain.ts` declares the test with its engine's `test`,
42
+ * after whatever starts it (signing in, opening the app):
43
+ *
44
+ * ```ts
45
+ * export function plainTest(testFile: string): void {
46
+ * const plain = loadPlainTest(testFile, options);
47
+ * test(plain.title, async ({ app, agent }) => {
48
+ * await app.open();
49
+ * await runSteps(agent, plain, options);
50
+ * });
51
+ * }
52
+ * ```
53
+ */
54
+ import { type BrowserLike, type ScreenLike, type StepAction } from './actions.ts';
55
+ /** The agent the steps run on: the e2e framework's, as a test gets it. */
56
+ export interface Agent {
57
+ act(instruction: string, options?: {
58
+ readonly params?: Record<string, unknown>;
59
+ }): Promise<unknown>;
60
+ assert(statement: string, options?: {
61
+ readonly screenshot?: boolean;
62
+ }): Promise<unknown>;
63
+ waitFor(condition: string): Promise<unknown>;
64
+ }
65
+ /**
66
+ * What a test gets to run steps on: the agent, and for a web test the
67
+ * engine's `screen` and `browser`, which a Do step's recorded actions need.
68
+ * Without them, every Do step is the agent's, from its sentence.
69
+ */
70
+ export interface PlainFixtures {
71
+ readonly agent: Agent;
72
+ readonly screen?: ScreenLike;
73
+ readonly browser?: BrowserLike;
74
+ }
75
+ /** What a project tells the runner about itself. */
76
+ export interface PlainOptions {
77
+ /**
78
+ * The features a test may require, or a step be conditioned on, and
79
+ * whether this run has each (a release track's, say). Without them, a
80
+ * steps file may use neither `requires` nor `when`.
81
+ */
82
+ readonly features?: {
83
+ readonly names: readonly string[];
84
+ readonly has: (feature: string) => boolean;
85
+ };
86
+ /** The instance's basic data, by item and field, for `{basic.<item>.<field>}`; see `readBasicData`. */
87
+ readonly basicData?: () => Readonly<Record<string, object>>;
88
+ }
89
+ /** A step's own condition: run it only with `feature`, or only without it. */
90
+ export interface Condition {
91
+ readonly feature: string;
92
+ readonly present: boolean;
93
+ }
94
+ export type PlainStep = {
95
+ readonly kind: 'do' | 'check' | 'waitUntil';
96
+ readonly text: string;
97
+ /** For a Do step recorded in e2e Studio: what it did, on the exact elements; the sentence is the fallback. */
98
+ readonly actions?: readonly StepAction[];
99
+ readonly when?: Condition;
100
+ } | {
101
+ /** A building block, or a check. */
102
+ readonly kind: 'block' | 'verify';
103
+ readonly call: BlockDefinition;
104
+ /** A block's name for its result. */
105
+ readonly as?: string;
106
+ readonly with: Readonly<Record<string, string>>;
107
+ readonly when?: Condition;
108
+ };
109
+ /** A plain-English test, checked and ready to run. */
110
+ export interface PlainTest {
111
+ readonly title: string;
112
+ readonly requires: readonly string[];
113
+ readonly steps: readonly PlainStep[];
114
+ /** The steps file, for messages. */
115
+ readonly file: string;
116
+ /** The app's directory, the one holding `e2e.config.ts`: where a block's `./path` starts. */
117
+ readonly appRoot: string;
118
+ }
119
+ /** A building block or a check as `e2e-studio.blocks.json` lists it; the runner needs only these parts. */
120
+ export interface BlockDefinition {
121
+ readonly id: string;
122
+ readonly label: string;
123
+ /** The function to call, with one options object. */
124
+ readonly function: string;
125
+ /** Where it comes from: a package, or `./a/path` from the app's directory. */
126
+ readonly from: string;
127
+ readonly fields: readonly {
128
+ readonly name: string;
129
+ readonly label: string;
130
+ readonly default?: string;
131
+ readonly optional?: boolean;
132
+ /** Takes an earlier step's result of this block. */
133
+ readonly block?: string;
134
+ /** The values it takes, when it takes one of a few. */
135
+ readonly options?: readonly string[];
136
+ }[];
137
+ readonly returns?: readonly {
138
+ readonly name: string;
139
+ readonly label: string;
140
+ }[];
141
+ }
142
+ /** An app's building blocks and checks. */
143
+ export interface Catalog {
144
+ readonly blocks: readonly BlockDefinition[];
145
+ readonly checks: readonly BlockDefinition[];
146
+ }
147
+ export declare const STEPS_FILE_SUFFIX = ".steps.json";
148
+ /** The app's building blocks, the catalog e2e Studio offers too. */
149
+ export declare const BLOCKS_FILE = "e2e-studio.blocks.json";
150
+ /**
151
+ * The plain-English test of the `.e2e.ts` file at `testFile` (its
152
+ * `import.meta.url`): the `.steps.json` beside it, checked against the app's
153
+ * building blocks. Throws, naming the file and step, at the first mistake.
154
+ */
155
+ export declare function loadPlainTest(testFile: string, options?: PlainOptions): PlainTest;
156
+ /** The app's building blocks and checks from its `e2e-studio.blocks.json`; none without one. */
157
+ export declare function readCatalog(appRoot: string): Catalog;
158
+ /** Checks a steps file's content; `file` names it in errors. */
159
+ export declare function parsePlainTest(json: unknown, context: Catalog & {
160
+ readonly file: string;
161
+ readonly appRoot: string;
162
+ }, options?: PlainOptions): PlainTest;
163
+ /** The features a test needs that this run lacks. */
164
+ export declare function missingFeatures(test: PlainTest, options?: PlainOptions): string[];
165
+ /**
166
+ * Runs a plain-English test's steps on `agent`. A `do` gets its values as
167
+ * params: basic data as is, a block's results as `unique()`, so the replay
168
+ * cache replays the steps on the next run with that run's values. A `check`
169
+ * and a `waitUntil`, judged anew on every run, get the values in their text.
170
+ */
171
+ export declare function runSteps(fixtures: Agent | PlainFixtures, test: PlainTest, options?: PlainOptions): Promise<void>;
package/dist/plain.js ADDED
@@ -0,0 +1,398 @@
1
+ /**
2
+ * Plain-English tests: a test as data, `<name>.steps.json` (its schema is
3
+ * `schemas/steps.schema.json`), beside a two-line `<name>.e2e.ts` that runs
4
+ * it through the app's own `support/plain.ts`. People write them in e2e
5
+ * Studio or by hand, and review them like code.
6
+ *
7
+ * ```json
8
+ * {
9
+ * "title": "a transferred task shows in My Work",
10
+ * "requires": ["someFeature"],
11
+ * "steps": [
12
+ * { "block": "work-order-with-task", "as": "work1", "with": { "description": "Pump leaking" } },
13
+ * { "block": "send-to-mobile", "with": { "work": "{work1}" } },
14
+ * { "do": "Search for {work1.description}" },
15
+ * { "waitUntil": "The list has finished loading" },
16
+ * { "check": "Assignment {work1.reference} is listed at {basic.site.name}", "when": "!someFeature" },
17
+ * { "verify": "work-assignment-state", "with": { "work": "{work1}", "state": "Assigned" } }
18
+ * ]
19
+ * }
20
+ * ```
21
+ *
22
+ * - `do`, `check` and `waitUntil` are sentences the agent carries out or
23
+ * judges (`agent.act`, `agent.assert`, `agent.waitFor`).
24
+ * - `block` calls one of the app's building blocks (`e2e-studio.blocks.json`): code that
25
+ * sets something up the screen does not, such as data made through an
26
+ * API. `as` names its result for later steps; `with` fills its fields.
27
+ * - `verify` calls one of the app's checks (`checks` in the same file): code
28
+ * that waits until the system holds what the test expects, and fails with
29
+ * what it holds instead. `with` fills its fields.
30
+ * - `{basic.<item>.<field>}` is the instance's basic data, such as
31
+ * `{basic.site.code}`; `{<name>.<value>}` is a value an earlier block
32
+ * returned; `{<name>}` alone, in a block field, is its whole result.
33
+ * - `requires` lists features the whole test needs: without them it is
34
+ * skipped, with the reason. `when` runs one step only with a feature, or
35
+ * only without it (`"!feature"`). The features, and whether a run has each,
36
+ * are the project's to say (`PlainOptions.features`).
37
+ *
38
+ * A file is checked when the tests are listed, so a mistake in one fails
39
+ * `npm run list` (and CI) by file and step, before anything runs.
40
+ *
41
+ * The app's `support/plain.ts` declares the test with its engine's `test`,
42
+ * after whatever starts it (signing in, opening the app):
43
+ *
44
+ * ```ts
45
+ * export function plainTest(testFile: string): void {
46
+ * const plain = loadPlainTest(testFile, options);
47
+ * test(plain.title, async ({ app, agent }) => {
48
+ * await app.open();
49
+ * await runSteps(agent, plain, options);
50
+ * });
51
+ * }
52
+ * ```
53
+ */
54
+ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
55
+ if (typeof path === "string" && /^\.\.?\//.test(path)) {
56
+ return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
57
+ return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
58
+ });
59
+ }
60
+ return path;
61
+ };
62
+ import { existsSync, readFileSync } from 'node:fs';
63
+ import path from 'node:path';
64
+ import { fileURLToPath, pathToFileURL } from 'node:url';
65
+ import { unique } from 'e2e';
66
+ import { actionProblem, actionValue, perform } from './actions.js';
67
+ export const STEPS_FILE_SUFFIX = '.steps.json';
68
+ /** The app's building blocks, the catalog e2e Studio offers too. */
69
+ export const BLOCKS_FILE = 'e2e-studio.blocks.json';
70
+ const SENTENCE = ['do', 'check', 'waitUntil'];
71
+ const NAME = /^[a-z][A-Za-z0-9]*$/;
72
+ /** `{basic.site.code}`, `{work1.description}`, `{work1}`. */
73
+ const TOKEN = /\{([a-z][A-Za-z0-9]*)(?:\.([A-Za-z_][A-Za-z0-9_]*))?(?:\.([A-Za-z_][A-Za-z0-9_]*))?\}/g;
74
+ /**
75
+ * The plain-English test of the `.e2e.ts` file at `testFile` (its
76
+ * `import.meta.url`): the `.steps.json` beside it, checked against the app's
77
+ * building blocks. Throws, naming the file and step, at the first mistake.
78
+ */
79
+ export function loadPlainTest(testFile, options = {}) {
80
+ const runner = testFile.startsWith('file:') ? fileURLToPath(testFile) : testFile;
81
+ const file = runner.replace(/\.e2e\.ts$/, STEPS_FILE_SUFFIX);
82
+ const appRoot = appRootOf(path.dirname(file));
83
+ let json;
84
+ try {
85
+ json = JSON.parse(readFileSync(file, 'utf8'));
86
+ }
87
+ catch (error) {
88
+ throw new Error(`${relativeTo(appRoot, file)}: ${error instanceof Error ? error.message : error}`);
89
+ }
90
+ return parsePlainTest(json, { file: relativeTo(appRoot, file), appRoot, ...readCatalog(appRoot) }, options);
91
+ }
92
+ /** The app's building blocks and checks from its `e2e-studio.blocks.json`; none without one. */
93
+ export function readCatalog(appRoot) {
94
+ const file = path.join(appRoot, BLOCKS_FILE);
95
+ if (!existsSync(file))
96
+ return { blocks: [], checks: [] };
97
+ const json = JSON.parse(readFileSync(file, 'utf8'));
98
+ return { blocks: json.blocks ?? [], checks: json.checks ?? [] };
99
+ }
100
+ /** Checks a steps file's content; `file` names it in errors. */
101
+ export function parsePlainTest(json, context, options = {}) {
102
+ const fail = (where, message) => new Error(`${context.file}${where}: ${message}`);
103
+ const features = options.features?.names ?? [];
104
+ const isFeature = (name) => features.includes(name);
105
+ const listFeatures = () => features.length ? `the features are ${features.join(', ')}` : 'the project names no features';
106
+ if (!isObject(json))
107
+ throw fail('', 'must be a JSON object with "title" and "steps"');
108
+ const unknownKeys = Object.keys(json).filter((k) => !['$schema', 'title', 'requires', 'steps'].includes(k));
109
+ if (unknownKeys.length)
110
+ throw fail('', `unknown key ${unknownKeys.join(', ')}`);
111
+ const { title, requires = [], steps } = json;
112
+ if (typeof title !== 'string' || !title.trim())
113
+ throw fail('', '"title" must be a sentence');
114
+ if (!Array.isArray(requires) || requires.some((f) => typeof f !== 'string' || !isFeature(f))) {
115
+ throw fail(' requires', `must list the project's features; ${listFeatures()}`);
116
+ }
117
+ if (!Array.isArray(steps) || steps.length === 0)
118
+ throw fail('', '"steps" must list at least one step');
119
+ /** The block of each result name so far. */
120
+ const results = new Map();
121
+ const checkTokens = (where, text, wholeResult) => {
122
+ for (const [token, name, value, field] of text.matchAll(TOKEN)) {
123
+ if (name === 'basic') {
124
+ if (!value || !field)
125
+ throw fail(where, `${token} names basic data as {basic.<item>.<field>}, such as {basic.site.code}`);
126
+ continue;
127
+ }
128
+ const block = results.get(name);
129
+ if (!block)
130
+ throw fail(where, `${token} names no earlier block's result`);
131
+ if (field)
132
+ throw fail(where, `${token}: a result's values are one level deep, {${name}.<value>}`);
133
+ if (value === undefined) {
134
+ if (!wholeResult)
135
+ throw fail(where, `${token} is a whole result; a sentence takes one of its values, {${name}.<value>}`);
136
+ }
137
+ else if (!block.returns?.some((r) => r.name === value)) {
138
+ const gives = block.returns?.map((r) => r.name).join(', ') || 'nothing';
139
+ throw fail(where, `${block.label} gives no ${value}; it gives ${gives}`);
140
+ }
141
+ }
142
+ };
143
+ const parsed = steps.map((raw, index) => {
144
+ const where = ` step ${index + 1}`;
145
+ if (!isObject(raw))
146
+ throw fail(where, 'must be an object such as { "do": "…" }');
147
+ const kinds = [...SENTENCE, 'block', 'verify'].filter((k) => k in raw);
148
+ if (kinds.length !== 1) {
149
+ throw fail(where, 'must have exactly one of "do", "check", "waitUntil", "block" or "verify"');
150
+ }
151
+ const kind = kinds[0];
152
+ const allowed = kind === 'block'
153
+ ? ['block', 'as', 'with', 'when']
154
+ : kind === 'verify'
155
+ ? [kind, 'with', 'when']
156
+ : kind === 'do'
157
+ ? [kind, 'actions', 'when']
158
+ : [kind, 'when'];
159
+ const extra = Object.keys(raw).filter((k) => !allowed.includes(k));
160
+ if (extra.length)
161
+ throw fail(where, `unknown key ${extra.join(', ')}`);
162
+ const when = condition(raw.when, isFeature, listFeatures, (message) => fail(where, message));
163
+ if (kind !== 'block' && kind !== 'verify') {
164
+ const text = raw[kind];
165
+ if (typeof text !== 'string' || !text.trim() || /[\r\n]/.test(text) || text.length > 500) {
166
+ throw fail(where, `"${kind}" must be one sentence of up to 500 characters`);
167
+ }
168
+ checkTokens(where, text, false);
169
+ const actions = raw.actions;
170
+ if (actions !== undefined) {
171
+ if (!Array.isArray(actions) || actions.length === 0)
172
+ throw fail(where, '"actions" must list what the step does');
173
+ actions.forEach((action, at) => {
174
+ const problem = actionProblem(action);
175
+ if (problem)
176
+ throw fail(`${where} action ${at + 1}`, problem);
177
+ const typed = actionValue(action);
178
+ if (typed)
179
+ checkTokens(`${where} action ${at + 1}`, typed, false);
180
+ });
181
+ }
182
+ return {
183
+ kind,
184
+ text: text.trim(),
185
+ ...(actions !== undefined ? { actions: actions } : {}),
186
+ ...(when ? { when } : {}),
187
+ };
188
+ }
189
+ const [catalog, what] = kind === 'block' ? [context.blocks, 'building block'] : [context.checks, 'check'];
190
+ const call = catalog.find((b) => b.id === raw[kind]);
191
+ if (!call) {
192
+ const known = catalog.map((b) => b.id).join(', ') || 'none';
193
+ throw fail(where, `no ${what} ${JSON.stringify(raw[kind])} in ${BLOCKS_FILE}; the ${what}s are ${known}`);
194
+ }
195
+ const values = raw.with ?? {};
196
+ if (!isObject(values) || Object.values(values).some((v) => typeof v !== 'string')) {
197
+ throw fail(where, '"with" must map field names to text');
198
+ }
199
+ for (const name of Object.keys(values)) {
200
+ if (!call.fields.some((f) => f.name === name))
201
+ throw fail(where, `${call.label} has no field ${name}`);
202
+ }
203
+ for (const field of call.fields) {
204
+ const value = (values[field.name] ?? '').trim();
205
+ if (field.block) {
206
+ const from = /^\{([a-z][A-Za-z0-9]*)\}$/.exec(value)?.[1];
207
+ if (!from || results.get(from)?.id !== field.block) {
208
+ const wanted = context.blocks.find((b) => b.id === field.block)?.label ?? field.block;
209
+ throw fail(where, `${field.label} must be an earlier "${wanted}" step's result, as {<its name>}`);
210
+ }
211
+ continue;
212
+ }
213
+ if (!value && !field.optional && field.default === undefined)
214
+ throw fail(where, `fill in ${field.label}`);
215
+ checkTokens(where, value, false);
216
+ // A value from another step is known only when the test runs.
217
+ if (field.options && value && !value.includes('{') && !field.options.includes(value)) {
218
+ throw fail(where, `${field.label} must be one of ${field.options.join(', ')}`);
219
+ }
220
+ }
221
+ const as = raw.as;
222
+ if (as !== undefined) {
223
+ if (typeof as !== 'string' || !NAME.test(as) || as === 'basic') {
224
+ throw fail(where, '"as" must be a name such as work1');
225
+ }
226
+ if (results.has(as))
227
+ throw fail(where, `the name ${as} is taken by an earlier step`);
228
+ results.set(as, call);
229
+ }
230
+ return {
231
+ kind,
232
+ call,
233
+ ...(as !== undefined ? { as } : {}),
234
+ with: values,
235
+ ...(when ? { when } : {}),
236
+ };
237
+ });
238
+ return {
239
+ title: title.trim(),
240
+ requires: requires,
241
+ steps: parsed,
242
+ file: context.file,
243
+ appRoot: context.appRoot,
244
+ };
245
+ }
246
+ /** The features a test needs that this run lacks. */
247
+ export function missingFeatures(test, options = {}) {
248
+ const has = options.features?.has ?? (() => false);
249
+ return test.requires.filter((feature) => !has(feature));
250
+ }
251
+ /**
252
+ * Runs a plain-English test's steps on `agent`. A `do` gets its values as
253
+ * params: basic data as is, a block's results as `unique()`, so the replay
254
+ * cache replays the steps on the next run with that run's values. A `check`
255
+ * and a `waitUntil`, judged anew on every run, get the values in their text.
256
+ */
257
+ export async function runSteps(fixtures, test, options = {}) {
258
+ const { agent, screen, browser } = 'agent' in fixtures ? fixtures : { agent: fixtures, screen: undefined, browser: undefined };
259
+ const results = new Map();
260
+ const has = options.features?.has ?? (() => false);
261
+ const lookUp = (token, name, value, field) => {
262
+ if (name === 'basic') {
263
+ if (!options.basicData)
264
+ throw new Error(`${test.file}: ${token}: the project gives no basic data`);
265
+ const data = options.basicData();
266
+ const item = data[value];
267
+ const found = item?.[field];
268
+ if (found === undefined)
269
+ throw new Error(`${test.file}: ${token}: this instance's basic data has no ${value}.${field}`);
270
+ return found;
271
+ }
272
+ const result = results.get(name);
273
+ return value === undefined ? result : result?.[value];
274
+ };
275
+ const text = (sentence) => sentence.replace(TOKEN, (token, name, value, field) => String(lookUp(token, name, value, field) ?? ''));
276
+ for (const [index, step] of test.steps.entries()) {
277
+ if (step.when && has(step.when.feature) !== step.when.present)
278
+ continue;
279
+ if (step.kind === 'block' || step.kind === 'verify') {
280
+ const call = await blockFunction(step.call, test.appRoot);
281
+ const options = {};
282
+ for (const field of step.call.fields) {
283
+ const raw = (step.with[field.name] ?? '').trim();
284
+ if (field.block)
285
+ options[field.name] = results.get(raw.slice(1, -1));
286
+ else if (raw)
287
+ options[field.name] = text(raw);
288
+ // Left empty, a field takes the function's own default.
289
+ }
290
+ if (step.kind === 'verify') {
291
+ try {
292
+ await call(options);
293
+ }
294
+ catch (error) {
295
+ const why = error instanceof Error ? error.message : String(error);
296
+ throw new Error(`${test.file} step ${index + 1}, verify ${step.call.label}: ${why}`, { cause: error });
297
+ }
298
+ continue;
299
+ }
300
+ const result = await call(options);
301
+ if (step.as)
302
+ results.set(step.as, (result ?? {}));
303
+ }
304
+ else if (step.kind === 'do') {
305
+ const named = {};
306
+ const instruction = step.text.replace(TOKEN, (token, name, value, field) => {
307
+ const param = [name, value, field].filter(Boolean).join('_');
308
+ named[param] = String(lookUp(token, name, value, field) ?? '');
309
+ return `{${param}}`;
310
+ });
311
+ // Recorded in e2e Studio: done on the exact elements, and by the agent from the sentence when one is not there.
312
+ if (step.actions && screen) {
313
+ try {
314
+ for (const action of step.actions)
315
+ await perform(action, screen, browser, text);
316
+ continue;
317
+ }
318
+ catch (error) {
319
+ const why = error instanceof Error ? error.message.split('\n')[0] : String(error);
320
+ console.warn(`${test.file} step ${index + 1}: a recorded action failed (${why}); the agent does "${step.text}" instead`);
321
+ }
322
+ }
323
+ const params = actParams(named, results);
324
+ await agent.act(instruction, Object.keys(params).length ? { params } : {});
325
+ }
326
+ else if (step.kind === 'check') {
327
+ await agent.assert(text(step.text), { screenshot: false });
328
+ }
329
+ else if (step.kind === 'waitUntil') {
330
+ await agent.waitFor(text(step.text));
331
+ }
332
+ }
333
+ }
334
+ /**
335
+ * A `do` step's params: the values its sentence names, and every block result
336
+ * so far besides, since the screen the step ends on may show any of them. The
337
+ * replay cache swaps a `unique()` value for the run's own, so block results
338
+ * go in as `unique()`; basic data, the same on every run, as is. A result the
339
+ * sentence leaves out is left out too when it sits inside another value (a
340
+ * work order number inside its reference): the cache records no step whose
341
+ * `unique()` value sits inside another param.
342
+ */
343
+ function actParams(named, results) {
344
+ const values = { ...named };
345
+ for (const [name, result] of results) {
346
+ for (const [key, value] of Object.entries(result)) {
347
+ if (typeof value === 'string' || typeof value === 'number')
348
+ values[`${name}_${key}`] ??= String(value);
349
+ }
350
+ }
351
+ const params = {};
352
+ for (const [param, value] of Object.entries(values)) {
353
+ if (param.startsWith('basic_') || !value.trim()) {
354
+ params[param] = value;
355
+ continue;
356
+ }
357
+ const inside = Object.entries(values).some(([other, v]) => other !== param && v.includes(value));
358
+ if (inside && !(param in named))
359
+ continue;
360
+ params[param] = unique(value);
361
+ }
362
+ return params;
363
+ }
364
+ const imported = new Map();
365
+ /** A building block's or a check's function, imported from its package or the app's own path. */
366
+ async function blockFunction(block, appRoot) {
367
+ const specifier = block.from.startsWith('./') ? pathToFileURL(path.join(appRoot, block.from)).href : block.from;
368
+ if (!imported.has(specifier))
369
+ imported.set(specifier, import(__rewriteRelativeImportExtension(specifier)));
370
+ const call = (await imported.get(specifier))?.[block.function];
371
+ if (typeof call !== 'function')
372
+ throw new Error(`${block.id}: ${block.from} exports no function ${block.function}`);
373
+ return call;
374
+ }
375
+ function condition(value, isFeature, listFeatures, fail) {
376
+ if (value === undefined)
377
+ return undefined;
378
+ const match = typeof value === 'string' ? /^(!?)([A-Za-z_][A-Za-z0-9_]*)$/.exec(value) : null;
379
+ if (!match || !isFeature(match[2])) {
380
+ throw fail(`"when" must be one of the project's features, or "!<feature>" for its absence; ${listFeatures()}`);
381
+ }
382
+ return { feature: match[2], present: match[1] !== '!' };
383
+ }
384
+ /** The nearest directory up from `dir` with an `e2e.config.ts`. */
385
+ function appRootOf(dir) {
386
+ for (let at = dir;; at = path.dirname(at)) {
387
+ if (existsSync(path.join(at, 'e2e.config.ts')))
388
+ return at;
389
+ if (path.dirname(at) === at)
390
+ return dir;
391
+ }
392
+ }
393
+ function relativeTo(root, file) {
394
+ return path.relative(root, file) || file;
395
+ }
396
+ function isObject(value) {
397
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
398
+ }
@@ -0,0 +1,74 @@
1
+ /**
2
+ * Running on what e2e Studio gives a run: one of its browsers, or a device
3
+ * it leased.
4
+ *
5
+ * A web run the Studio starts gets the browser it hosts in
6
+ * `E2E_STUDIO_CDP`: connected to it, the run can be watched live in the
7
+ * Studio. `studioBrowser()` is the web engine's options for that:
8
+ *
9
+ * engine: web({ ...studioBrowser() })
10
+ *
11
+ * A mobile run the Studio starts gets its device as JSON in
12
+ * `E2E_STUDIO_DEVICE`: a phone, emulator or simulator on a tester's machine,
13
+ * which runs the Studio's device host. The run drives it through the
14
+ * Studio, which relays agent-device's requests to that machine; nothing of
15
+ * the device is on the machine the run is on, not even adb.
16
+ *
17
+ * engine: mobile({ platform: 'android', device: studioLease() ? studioDevice() : process.env.ANDROID_SERIAL })
18
+ */
19
+ import type { DeviceProvider } from '@e2e-dev/mobile';
20
+ /** Where the Studio puts the address of the browser a web run drives. */
21
+ export declare const STUDIO_BROWSER_ENV = "E2E_STUDIO_CDP";
22
+ /**
23
+ * The web engine's options for a run the Studio started: connect to the
24
+ * browser it hosts, so the run can be watched live there. None for any
25
+ * other run, which launches a browser of its own.
26
+ */
27
+ export declare function studioBrowser(env?: Readonly<Record<string, string | undefined>>): {
28
+ readonly connect?: {
29
+ readonly cdpEndpoint: () => string;
30
+ };
31
+ };
32
+ /** Where the Studio puts the lease, unless the project's `mobile.leaseEnv` says otherwise. */
33
+ export declare const STUDIO_DEVICE_ENV = "E2E_STUDIO_DEVICE";
34
+ /** The device a run got from Testra Studio. */
35
+ export interface StudioDeviceLease {
36
+ /** The run's id, which names the lease. */
37
+ readonly id: string;
38
+ readonly platform: 'android' | 'ios';
39
+ /** agent-device's id for the device: an Android serial or an Apple UDID. */
40
+ readonly deviceId: string;
41
+ /** Its name, such as `Pixel 9 API 35`. */
42
+ readonly device: string;
43
+ /** The device host's id and name. */
44
+ readonly host: string;
45
+ readonly hostName: string;
46
+ /** The agent-device version the device host runs, when it said. */
47
+ readonly agentDevice?: string;
48
+ /** The agent-device daemon to drive the device through: the Studio's relay, with a token for this run. */
49
+ readonly daemon: {
50
+ readonly baseUrl: string;
51
+ readonly authToken: string;
52
+ };
53
+ /** Android: where `adb shell` runs on the device, with the same token. */
54
+ readonly adb?: string;
55
+ }
56
+ /** The run's lease, or `undefined` when the Studio did not start it on a device host. */
57
+ export declare function studioLease(env?: Readonly<Record<string, string | undefined>>): StudioDeviceLease | undefined;
58
+ /**
59
+ * The mobile engine's `device` for a run on a Studio device: the one device
60
+ * the Studio leased the run, driven through the Studio. The Studio frees it
61
+ * when the run ends, so `release` has nothing to do.
62
+ */
63
+ export declare function studioDevice(): DeviceProvider;
64
+ /** What `adb shell` gave back. */
65
+ export interface ShellResult {
66
+ readonly code: number;
67
+ readonly stdout: string;
68
+ readonly stderr: string;
69
+ }
70
+ /**
71
+ * Runs `adb shell <args>` on a Studio-leased Android device, on the device
72
+ * host's machine. Resolves with its output; rejects when it exits non-zero.
73
+ */
74
+ export declare function studioAdbShell(lease: StudioDeviceLease, args: readonly string[]): Promise<string>;