@testra-studio/kit 0.0.0-stage → 0.1.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 ADDED
@@ -0,0 +1,23 @@
1
+ # @testra-studio/kit
2
+
3
+ Each version names what changed for a test project, and what it must do.
4
+ A major version (or, before 1.0, a minor one) changes a format or a
5
+ variable e2e Studio and the project share; the Studio's project check names
6
+ the oldest kit it works with.
7
+
8
+ ## 0.1.0
9
+
10
+ The first version, moved out of a project's own test kit so any project on
11
+ the e2e framework can run under e2e Studio:
12
+
13
+ - `studioBrowser()`: the web engine's options for the browser the Studio
14
+ hosts a run in (`E2E_STUDIO_CDP`), so it can be watched live.
15
+ - `studioDevice()`, `studioLease()`, `studioAdbShell()`: the device the
16
+ Studio leased a mobile run (`E2E_STUDIO_DEVICE`).
17
+ - `loadPlainTest()`, `runSteps()`, `missingFeatures()`: plain-English steps
18
+ files, with building blocks, checks, `{basic.…}` tokens and a project's
19
+ features passed in as `PlainOptions`.
20
+ - `readBasicData()`: an instance's basic data, from the variable, the local
21
+ file, the instance's file and the shared file, in that order.
22
+ - `schemas/`: the JSON Schemas of steps files, `basic-data.items.json` and
23
+ instance files.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 IFS
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,90 @@
1
- # Temporary Holding Version
1
+ # @testra-studio/kit
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ What a test project on the [e2e framework](https://www.npmjs.com/package/e2e)
4
+ needs to run under e2e Studio, whatever system it tests: the browser or
5
+ device the Studio gives a run, plain-English steps files, and an instance's
6
+ basic data. It lives in the testra-studio repository, beside the Studio it
7
+ pairs with, and is published to npm under the MIT licence.
8
+
9
+ ## Install
10
+
11
+ ```sh
12
+ npm install @testra-studio/kit
13
+ ```
14
+
15
+ It needs the e2e framework (`e2e`), and `@e2e-dev/mobile` for a mobile project.
16
+
17
+ ## A web project
18
+
19
+ ```ts
20
+ import { web } from '@e2e-dev/web';
21
+ import { studioBrowser } from '@testra-studio/kit';
22
+
23
+ export default {
24
+ targets: [{ name: 'web', engine: web({ ...studioBrowser() }), app: { url: 'https://staging.example.com' } }],
25
+ };
26
+ ```
27
+
28
+ ## A mobile project
29
+
30
+ ```ts
31
+ import { mobile } from '@e2e-dev/mobile';
32
+ import { studioDevice, studioLease } from '@testra-studio/kit';
33
+
34
+ const device = studioLease() ? studioDevice() : process.env.ANDROID_SERIAL;
35
+ export default { targets: [{ name: 'app', engine: mobile({ platform: 'android', device }) }], workers: 1 };
36
+ ```
37
+
38
+ ## Plain-English tests
39
+
40
+ A test is `<name>.steps.json` ([schema](schemas/steps.schema.json)) beside
41
+ a two-line `<name>.e2e.ts`. The project's `support/plain.ts` declares it with
42
+ its own engine's `test`, after whatever starts it:
43
+
44
+ ```ts
45
+ import { test } from '@e2e-dev/web';
46
+ import { loadPlainTest, missingFeatures, type PlainOptions, readBasicData, runSteps } from '@testra-studio/kit';
47
+
48
+ const options: PlainOptions = {
49
+ // Optional: features a test may require, and whether this run has each.
50
+ features: { names: ['newCheckout'], has: (feature) => process.env.FEATURES?.includes(feature) ?? false },
51
+ // Optional: the instance's basic data, for {basic.<item>.<field>}.
52
+ basicData: () => readBasicData({ dir: 'environments', instance: process.env.APP_ENV ?? 'staging' }),
53
+ };
54
+
55
+ export function plainTest(testFile: string): void {
56
+ const plain = loadPlainTest(testFile, options);
57
+ const missing = missingFeatures(plain, options);
58
+ test(plain.title, missing.length ? { skip: `lacks ${missing.join(', ')}` } : {}, async ({ app, agent }) => {
59
+ await app.open();
60
+ await runSteps(agent, plain, options);
61
+ });
62
+ }
63
+ ```
64
+
65
+ ```ts
66
+ // tests/checkout/full-cart.e2e.ts
67
+ import { plainTest } from '../../support/plain.ts';
68
+
69
+ plainTest(import.meta.url);
70
+ ```
71
+
72
+ Building blocks and checks are listed in `e2e-studio.blocks.json`, beside
73
+ `e2e.config.ts`.
74
+
75
+ ## Basic data
76
+
77
+ `readBasicData({ dir, instance, fromEnv })` takes each item, listed in
78
+ `<dir>/basic-data.items.json` ([schema](schemas/basic-data.items.schema.json)),
79
+ from the first source that sets it: the `fromEnv` variable's JSON,
80
+ `<instance>.local.json`, `basicData` in `<instance>.json`
81
+ ([schema](schemas/instance.schema.json)), then `basic-data.json`.
82
+
83
+ ## Releasing
84
+
85
+ The kit is built and tested with the Studio, on every pull request. A pull
86
+ request that changes it bumps `version` in `package.json` and adds a
87
+ `CHANGELOG.md` section; merged to main, the pipeline publishes that version to
88
+ npm (`scripts/publish-kit.ts`, with the `NPM_TOKEN` repository variable). Before 1.0, a minor version is a
89
+ change projects must react to; the Studio's project check warns about a kit
90
+ older than it works with (`KIT_MINIMUM` in `apps/server/src/projects.ts`).
@@ -0,0 +1,39 @@
1
+ /**
2
+ * Basic data: the existing records on a system under test that tests work
3
+ * with, such as a site or a customer, each a code and a name. A folder of
4
+ * instance files describes it in `basic-data.items.json` (its schema is
5
+ * `schemas/basic-data.items.schema.json`); the values live outside the code,
6
+ * so changing one never needs a code change. First source that sets an item
7
+ * wins:
8
+ *
9
+ * 1. the `fromEnv` variable, a JSON object, for CI or a single run
10
+ * 2. `<instance>.local.json`, gitignored, for one person's own values
11
+ * 3. `basicData` in `<instance>.json`, the instance's values
12
+ * 4. `basic-data.json`, values most instances share
13
+ *
14
+ * An item is replaced whole, never merged: a site's code and name always
15
+ * come from the same source. A missing item, a malformed one, or one that
16
+ * is no basic data fails by name, with where to set it.
17
+ *
18
+ * e2e Studio edits the same files on its Settings page, item by item.
19
+ */
20
+ /** A record as a lookup shows it: `M-CMB - MASS Colombo`. */
21
+ export interface CodeAndName {
22
+ readonly code: string;
23
+ readonly name: string;
24
+ }
25
+ export declare const BASIC_DATA_ITEMS_FILE = "basic-data.items.json";
26
+ export declare const SHARED_BASIC_DATA_FILE = "basic-data.json";
27
+ export interface BasicDataOptions {
28
+ /** The folder of instance files: `environments`. */
29
+ readonly dir: string;
30
+ /** The instance a run is on, its file `<instance>.json`. */
31
+ readonly instance: string;
32
+ /** A variable whose JSON sets items over every file, such as `APP_BASIC_DATA`. */
33
+ readonly fromEnv?: string;
34
+ readonly env?: Readonly<Record<string, string | undefined>>;
35
+ }
36
+ /** The kinds of basic data the folder describes, by key. */
37
+ export declare function basicDataItems(dir: string): string[];
38
+ /** The instance's basic data from every source, checked; a missing or malformed item fails by name. */
39
+ export declare function readBasicData(options: BasicDataOptions): Record<string, CodeAndName>;
@@ -0,0 +1,109 @@
1
+ /**
2
+ * Basic data: the existing records on a system under test that tests work
3
+ * with, such as a site or a customer, each a code and a name. A folder of
4
+ * instance files describes it in `basic-data.items.json` (its schema is
5
+ * `schemas/basic-data.items.schema.json`); the values live outside the code,
6
+ * so changing one never needs a code change. First source that sets an item
7
+ * wins:
8
+ *
9
+ * 1. the `fromEnv` variable, a JSON object, for CI or a single run
10
+ * 2. `<instance>.local.json`, gitignored, for one person's own values
11
+ * 3. `basicData` in `<instance>.json`, the instance's values
12
+ * 4. `basic-data.json`, values most instances share
13
+ *
14
+ * An item is replaced whole, never merged: a site's code and name always
15
+ * come from the same source. A missing item, a malformed one, or one that
16
+ * is no basic data fails by name, with where to set it.
17
+ *
18
+ * e2e Studio edits the same files on its Settings page, item by item.
19
+ */
20
+ import { existsSync, readFileSync } from 'node:fs';
21
+ import path from 'node:path';
22
+ export const BASIC_DATA_ITEMS_FILE = 'basic-data.items.json';
23
+ export const SHARED_BASIC_DATA_FILE = 'basic-data.json';
24
+ /** The kinds of basic data the folder describes, by key. */
25
+ export function basicDataItems(dir) {
26
+ const file = path.join(dir, BASIC_DATA_ITEMS_FILE);
27
+ if (!existsSync(file))
28
+ throw new Error(`${file} does not exist: it lists the kinds of basic data`);
29
+ const described = parse(file, readFileSync(file, 'utf8'));
30
+ if (!described.items || typeof described.items !== 'object' || Array.isArray(described.items)) {
31
+ throw new Error(`${file}: "items" must be an object of basic data items`);
32
+ }
33
+ return Object.keys(described.items);
34
+ }
35
+ /** The instance's basic data from every source, checked; a missing or malformed item fails by name. */
36
+ export function readBasicData(options) {
37
+ const { dir, instance } = options;
38
+ const env = options.env ?? process.env;
39
+ const items = basicDataItems(dir);
40
+ const instanceFile = path.join(dir, `${instance}.json`);
41
+ const sources = [
42
+ options.fromEnv ? fromJson(options.fromEnv, env[options.fromEnv]) : undefined,
43
+ fromFile(path.join(dir, `${instance}.local.json`)),
44
+ existsSync(instanceFile)
45
+ ? fromValue(`basicData in ${instanceFile}`, parse(instanceFile, readFileSync(instanceFile, 'utf8')).basicData)
46
+ : undefined,
47
+ fromFile(path.join(dir, SHARED_BASIC_DATA_FILE)),
48
+ ].filter((source) => source !== undefined);
49
+ for (const { label, values } of sources) {
50
+ const unknown = Object.keys(values).filter((key) => !items.includes(key));
51
+ if (unknown.length > 0) {
52
+ throw new Error(`${label}: ${unknown.join(', ')} not basic data; the items are ${items.join(', ')}`);
53
+ }
54
+ }
55
+ const missing = [];
56
+ const data = {};
57
+ for (const item of items) {
58
+ const source = sources.find(({ values }) => Object.hasOwn(values, item));
59
+ if (source === undefined) {
60
+ missing.push(item);
61
+ continue;
62
+ }
63
+ data[item] = codeAndName(source.values[item], (message) => new Error(`${source.label}: ${item} ${message}`));
64
+ }
65
+ if (missing.length > 0) {
66
+ const places = [
67
+ `basicData in ${path.join(dir, `${instance}.json`)}`,
68
+ path.join(dir, SHARED_BASIC_DATA_FILE),
69
+ path.join(dir, `${instance}.local.json`),
70
+ ...(options.fromEnv ? [options.fromEnv] : []),
71
+ ];
72
+ throw new Error(`basic data ${missing.join(', ')} not set for ${instance}; set it in ${places.join(', or ')}`);
73
+ }
74
+ return data;
75
+ }
76
+ function codeAndName(value, problem) {
77
+ const record = value;
78
+ if (typeof record?.code !== 'string' || typeof record.name !== 'string' || !record.code || !record.name) {
79
+ throw problem(`must be { "code": "…", "name": "…" }, got ${JSON.stringify(value)}`);
80
+ }
81
+ return { code: record.code, name: record.name };
82
+ }
83
+ /** A JSON file's object, or no source when the file does not exist. */
84
+ function fromFile(file) {
85
+ return existsSync(file) ? fromJson(file, readFileSync(file, 'utf8')) : undefined;
86
+ }
87
+ /** A JSON text's object, or no source when the text is unset. */
88
+ function fromJson(label, text) {
89
+ if (!text)
90
+ return undefined;
91
+ return fromValue(label, parse(label, text));
92
+ }
93
+ /** An object as a source, or no source when it is absent. */
94
+ function fromValue(label, value) {
95
+ if (value === undefined)
96
+ return undefined;
97
+ if (typeof value !== 'object' || value === null || Array.isArray(value)) {
98
+ throw new Error(`${label}: must be a JSON object of basic data items, got ${JSON.stringify(value)}`);
99
+ }
100
+ return { label, values: value };
101
+ }
102
+ function parse(label, text) {
103
+ try {
104
+ return JSON.parse(text);
105
+ }
106
+ catch (cause) {
107
+ throw new Error(`${label}: not valid JSON (${cause.message})`);
108
+ }
109
+ }
@@ -0,0 +1,13 @@
1
+ /**
2
+ * @testra-studio/kit: what a test project on the e2e framework needs to run
3
+ * under e2e Studio, whatever system it tests.
4
+ *
5
+ * - `studioBrowser()` and `studioDevice()`: drive the browser or device the
6
+ * Studio gives a run, so it can be watched live there.
7
+ * - `loadPlainTest()` and `runSteps()`: plain-English tests, as steps files.
8
+ * - `readBasicData()`: an instance's basic data, as the Studio edits it.
9
+ * - `schemas/`: the JSON Schemas of the files the Studio and a project share.
10
+ */
11
+ export { BASIC_DATA_ITEMS_FILE, type BasicDataOptions, basicDataItems, type CodeAndName, readBasicData, SHARED_BASIC_DATA_FILE, } from './basic-data.ts';
12
+ export { type Agent, BLOCKS_FILE, type BlockDefinition, type Catalog, type Condition, loadPlainTest, missingFeatures, type PlainOptions, type PlainStep, type PlainTest, parsePlainTest, readCatalog, runSteps, STEPS_FILE_SUFFIX, } from './plain.ts';
13
+ export { type ShellResult, STUDIO_BROWSER_ENV, STUDIO_DEVICE_ENV, type StudioDeviceLease, studioAdbShell, studioBrowser, studioDevice, studioLease, } from './studio.ts';
package/dist/index.js ADDED
@@ -0,0 +1,13 @@
1
+ /**
2
+ * @testra-studio/kit: what a test project on the e2e framework needs to run
3
+ * under e2e Studio, whatever system it tests.
4
+ *
5
+ * - `studioBrowser()` and `studioDevice()`: drive the browser or device the
6
+ * Studio gives a run, so it can be watched live there.
7
+ * - `loadPlainTest()` and `runSteps()`: plain-English tests, as steps files.
8
+ * - `readBasicData()`: an instance's basic data, as the Studio edits it.
9
+ * - `schemas/`: the JSON Schemas of the files the Studio and a project share.
10
+ */
11
+ export { BASIC_DATA_ITEMS_FILE, basicDataItems, readBasicData, SHARED_BASIC_DATA_FILE, } from './basic-data.js';
12
+ export { BLOCKS_FILE, loadPlainTest, missingFeatures, parsePlainTest, readCatalog, runSteps, STEPS_FILE_SUFFIX, } from './plain.js';
13
+ export { STUDIO_BROWSER_ENV, STUDIO_DEVICE_ENV, studioAdbShell, studioBrowser, studioDevice, studioLease, } from './studio.js';
@@ -0,0 +1,158 @@
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
+ /** The agent the steps run on: the e2e framework's, as a test gets it. */
55
+ export interface Agent {
56
+ act(instruction: string, options?: {
57
+ readonly params?: Record<string, unknown>;
58
+ }): Promise<unknown>;
59
+ assert(statement: string, options?: {
60
+ readonly screenshot?: boolean;
61
+ }): Promise<unknown>;
62
+ waitFor(condition: string): Promise<unknown>;
63
+ }
64
+ /** What a project tells the runner about itself. */
65
+ export interface PlainOptions {
66
+ /**
67
+ * The features a test may require, or a step be conditioned on, and
68
+ * whether this run has each (a release track's, say). Without them, a
69
+ * steps file may use neither `requires` nor `when`.
70
+ */
71
+ readonly features?: {
72
+ readonly names: readonly string[];
73
+ readonly has: (feature: string) => boolean;
74
+ };
75
+ /** The instance's basic data, by item and field, for `{basic.<item>.<field>}`; see `readBasicData`. */
76
+ readonly basicData?: () => Readonly<Record<string, object>>;
77
+ }
78
+ /** A step's own condition: run it only with `feature`, or only without it. */
79
+ export interface Condition {
80
+ readonly feature: string;
81
+ readonly present: boolean;
82
+ }
83
+ export type PlainStep = {
84
+ readonly kind: 'do' | 'check' | 'waitUntil';
85
+ readonly text: string;
86
+ readonly when?: Condition;
87
+ } | {
88
+ /** A building block, or a check. */
89
+ readonly kind: 'block' | 'verify';
90
+ readonly call: BlockDefinition;
91
+ /** A block's name for its result. */
92
+ readonly as?: string;
93
+ readonly with: Readonly<Record<string, string>>;
94
+ readonly when?: Condition;
95
+ };
96
+ /** A plain-English test, checked and ready to run. */
97
+ export interface PlainTest {
98
+ readonly title: string;
99
+ readonly requires: readonly string[];
100
+ readonly steps: readonly PlainStep[];
101
+ /** The steps file, for messages. */
102
+ readonly file: string;
103
+ /** The app's directory, the one holding `e2e.config.ts`: where a block's `./path` starts. */
104
+ readonly appRoot: string;
105
+ }
106
+ /** A building block or a check as `e2e-studio.blocks.json` lists it; the runner needs only these parts. */
107
+ export interface BlockDefinition {
108
+ readonly id: string;
109
+ readonly label: string;
110
+ /** The function to call, with one options object. */
111
+ readonly function: string;
112
+ /** Where it comes from: a package, or `./a/path` from the app's directory. */
113
+ readonly from: string;
114
+ readonly fields: readonly {
115
+ readonly name: string;
116
+ readonly label: string;
117
+ readonly default?: string;
118
+ readonly optional?: boolean;
119
+ /** Takes an earlier step's result of this block. */
120
+ readonly block?: string;
121
+ /** The values it takes, when it takes one of a few. */
122
+ readonly options?: readonly string[];
123
+ }[];
124
+ readonly returns?: readonly {
125
+ readonly name: string;
126
+ readonly label: string;
127
+ }[];
128
+ }
129
+ /** An app's building blocks and checks. */
130
+ export interface Catalog {
131
+ readonly blocks: readonly BlockDefinition[];
132
+ readonly checks: readonly BlockDefinition[];
133
+ }
134
+ export declare const STEPS_FILE_SUFFIX = ".steps.json";
135
+ /** The app's building blocks, the catalog e2e Studio offers too. */
136
+ export declare const BLOCKS_FILE = "e2e-studio.blocks.json";
137
+ /**
138
+ * The plain-English test of the `.e2e.ts` file at `testFile` (its
139
+ * `import.meta.url`): the `.steps.json` beside it, checked against the app's
140
+ * building blocks. Throws, naming the file and step, at the first mistake.
141
+ */
142
+ export declare function loadPlainTest(testFile: string, options?: PlainOptions): PlainTest;
143
+ /** The app's building blocks and checks from its `e2e-studio.blocks.json`; none without one. */
144
+ export declare function readCatalog(appRoot: string): Catalog;
145
+ /** Checks a steps file's content; `file` names it in errors. */
146
+ export declare function parsePlainTest(json: unknown, context: Catalog & {
147
+ readonly file: string;
148
+ readonly appRoot: string;
149
+ }, options?: PlainOptions): PlainTest;
150
+ /** The features a test needs that this run lacks. */
151
+ export declare function missingFeatures(test: PlainTest, options?: PlainOptions): string[];
152
+ /**
153
+ * Runs a plain-English test's steps on `agent`. A `do` gets its values as
154
+ * params: basic data as is, a block's results as `unique()`, so the replay
155
+ * cache replays the steps on the next run with that run's values. A `check`
156
+ * and a `waitUntil`, judged anew on every run, get the values in their text.
157
+ */
158
+ export declare function runSteps(agent: Agent, test: PlainTest, options?: PlainOptions): Promise<void>;
package/dist/plain.js ADDED
@@ -0,0 +1,360 @@
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
+ export const STEPS_FILE_SUFFIX = '.steps.json';
67
+ /** The app's building blocks, the catalog e2e Studio offers too. */
68
+ export const BLOCKS_FILE = 'e2e-studio.blocks.json';
69
+ const SENTENCE = ['do', 'check', 'waitUntil'];
70
+ const NAME = /^[a-z][A-Za-z0-9]*$/;
71
+ /** `{basic.site.code}`, `{work1.description}`, `{work1}`. */
72
+ const TOKEN = /\{([a-z][A-Za-z0-9]*)(?:\.([A-Za-z_][A-Za-z0-9_]*))?(?:\.([A-Za-z_][A-Za-z0-9_]*))?\}/g;
73
+ /**
74
+ * The plain-English test of the `.e2e.ts` file at `testFile` (its
75
+ * `import.meta.url`): the `.steps.json` beside it, checked against the app's
76
+ * building blocks. Throws, naming the file and step, at the first mistake.
77
+ */
78
+ export function loadPlainTest(testFile, options = {}) {
79
+ const runner = testFile.startsWith('file:') ? fileURLToPath(testFile) : testFile;
80
+ const file = runner.replace(/\.e2e\.ts$/, STEPS_FILE_SUFFIX);
81
+ const appRoot = appRootOf(path.dirname(file));
82
+ let json;
83
+ try {
84
+ json = JSON.parse(readFileSync(file, 'utf8'));
85
+ }
86
+ catch (error) {
87
+ throw new Error(`${relativeTo(appRoot, file)}: ${error instanceof Error ? error.message : error}`);
88
+ }
89
+ return parsePlainTest(json, { file: relativeTo(appRoot, file), appRoot, ...readCatalog(appRoot) }, options);
90
+ }
91
+ /** The app's building blocks and checks from its `e2e-studio.blocks.json`; none without one. */
92
+ export function readCatalog(appRoot) {
93
+ const file = path.join(appRoot, BLOCKS_FILE);
94
+ if (!existsSync(file))
95
+ return { blocks: [], checks: [] };
96
+ const json = JSON.parse(readFileSync(file, 'utf8'));
97
+ return { blocks: json.blocks ?? [], checks: json.checks ?? [] };
98
+ }
99
+ /** Checks a steps file's content; `file` names it in errors. */
100
+ export function parsePlainTest(json, context, options = {}) {
101
+ const fail = (where, message) => new Error(`${context.file}${where}: ${message}`);
102
+ const features = options.features?.names ?? [];
103
+ const isFeature = (name) => features.includes(name);
104
+ const listFeatures = () => features.length ? `the features are ${features.join(', ')}` : 'the project names no features';
105
+ if (!isObject(json))
106
+ throw fail('', 'must be a JSON object with "title" and "steps"');
107
+ const unknownKeys = Object.keys(json).filter((k) => !['$schema', 'title', 'requires', 'steps'].includes(k));
108
+ if (unknownKeys.length)
109
+ throw fail('', `unknown key ${unknownKeys.join(', ')}`);
110
+ const { title, requires = [], steps } = json;
111
+ if (typeof title !== 'string' || !title.trim())
112
+ throw fail('', '"title" must be a sentence');
113
+ if (!Array.isArray(requires) || requires.some((f) => typeof f !== 'string' || !isFeature(f))) {
114
+ throw fail(' requires', `must list the project's features; ${listFeatures()}`);
115
+ }
116
+ if (!Array.isArray(steps) || steps.length === 0)
117
+ throw fail('', '"steps" must list at least one step');
118
+ /** The block of each result name so far. */
119
+ const results = new Map();
120
+ const checkTokens = (where, text, wholeResult) => {
121
+ for (const [token, name, value, field] of text.matchAll(TOKEN)) {
122
+ if (name === 'basic') {
123
+ if (!value || !field)
124
+ throw fail(where, `${token} names basic data as {basic.<item>.<field>}, such as {basic.site.code}`);
125
+ continue;
126
+ }
127
+ const block = results.get(name);
128
+ if (!block)
129
+ throw fail(where, `${token} names no earlier block's result`);
130
+ if (field)
131
+ throw fail(where, `${token}: a result's values are one level deep, {${name}.<value>}`);
132
+ if (value === undefined) {
133
+ if (!wholeResult)
134
+ throw fail(where, `${token} is a whole result; a sentence takes one of its values, {${name}.<value>}`);
135
+ }
136
+ else if (!block.returns?.some((r) => r.name === value)) {
137
+ const gives = block.returns?.map((r) => r.name).join(', ') || 'nothing';
138
+ throw fail(where, `${block.label} gives no ${value}; it gives ${gives}`);
139
+ }
140
+ }
141
+ };
142
+ const parsed = steps.map((raw, index) => {
143
+ const where = ` step ${index + 1}`;
144
+ if (!isObject(raw))
145
+ throw fail(where, 'must be an object such as { "do": "…" }');
146
+ const kinds = [...SENTENCE, 'block', 'verify'].filter((k) => k in raw);
147
+ if (kinds.length !== 1) {
148
+ throw fail(where, 'must have exactly one of "do", "check", "waitUntil", "block" or "verify"');
149
+ }
150
+ const kind = kinds[0];
151
+ const allowed = kind === 'block' ? ['block', 'as', 'with', 'when'] : kind === 'verify' ? [kind, 'with', 'when'] : [kind, 'when'];
152
+ const extra = Object.keys(raw).filter((k) => !allowed.includes(k));
153
+ if (extra.length)
154
+ throw fail(where, `unknown key ${extra.join(', ')}`);
155
+ const when = condition(raw.when, isFeature, listFeatures, (message) => fail(where, message));
156
+ if (kind !== 'block' && kind !== 'verify') {
157
+ const text = raw[kind];
158
+ if (typeof text !== 'string' || !text.trim() || /[\r\n]/.test(text) || text.length > 500) {
159
+ throw fail(where, `"${kind}" must be one sentence of up to 500 characters`);
160
+ }
161
+ checkTokens(where, text, false);
162
+ return { kind, text: text.trim(), ...(when ? { when } : {}) };
163
+ }
164
+ const [catalog, what] = kind === 'block' ? [context.blocks, 'building block'] : [context.checks, 'check'];
165
+ const call = catalog.find((b) => b.id === raw[kind]);
166
+ if (!call) {
167
+ const known = catalog.map((b) => b.id).join(', ') || 'none';
168
+ throw fail(where, `no ${what} ${JSON.stringify(raw[kind])} in ${BLOCKS_FILE}; the ${what}s are ${known}`);
169
+ }
170
+ const values = raw.with ?? {};
171
+ if (!isObject(values) || Object.values(values).some((v) => typeof v !== 'string')) {
172
+ throw fail(where, '"with" must map field names to text');
173
+ }
174
+ for (const name of Object.keys(values)) {
175
+ if (!call.fields.some((f) => f.name === name))
176
+ throw fail(where, `${call.label} has no field ${name}`);
177
+ }
178
+ for (const field of call.fields) {
179
+ const value = (values[field.name] ?? '').trim();
180
+ if (field.block) {
181
+ const from = /^\{([a-z][A-Za-z0-9]*)\}$/.exec(value)?.[1];
182
+ if (!from || results.get(from)?.id !== field.block) {
183
+ const wanted = context.blocks.find((b) => b.id === field.block)?.label ?? field.block;
184
+ throw fail(where, `${field.label} must be an earlier "${wanted}" step's result, as {<its name>}`);
185
+ }
186
+ continue;
187
+ }
188
+ if (!value && !field.optional && field.default === undefined)
189
+ throw fail(where, `fill in ${field.label}`);
190
+ checkTokens(where, value, false);
191
+ // A value from another step is known only when the test runs.
192
+ if (field.options && value && !value.includes('{') && !field.options.includes(value)) {
193
+ throw fail(where, `${field.label} must be one of ${field.options.join(', ')}`);
194
+ }
195
+ }
196
+ const as = raw.as;
197
+ if (as !== undefined) {
198
+ if (typeof as !== 'string' || !NAME.test(as) || as === 'basic') {
199
+ throw fail(where, '"as" must be a name such as work1');
200
+ }
201
+ if (results.has(as))
202
+ throw fail(where, `the name ${as} is taken by an earlier step`);
203
+ results.set(as, call);
204
+ }
205
+ return {
206
+ kind,
207
+ call,
208
+ ...(as !== undefined ? { as } : {}),
209
+ with: values,
210
+ ...(when ? { when } : {}),
211
+ };
212
+ });
213
+ return {
214
+ title: title.trim(),
215
+ requires: requires,
216
+ steps: parsed,
217
+ file: context.file,
218
+ appRoot: context.appRoot,
219
+ };
220
+ }
221
+ /** The features a test needs that this run lacks. */
222
+ export function missingFeatures(test, options = {}) {
223
+ const has = options.features?.has ?? (() => false);
224
+ return test.requires.filter((feature) => !has(feature));
225
+ }
226
+ /**
227
+ * Runs a plain-English test's steps on `agent`. A `do` gets its values as
228
+ * params: basic data as is, a block's results as `unique()`, so the replay
229
+ * cache replays the steps on the next run with that run's values. A `check`
230
+ * and a `waitUntil`, judged anew on every run, get the values in their text.
231
+ */
232
+ export async function runSteps(agent, test, options = {}) {
233
+ const results = new Map();
234
+ const has = options.features?.has ?? (() => false);
235
+ const lookUp = (token, name, value, field) => {
236
+ if (name === 'basic') {
237
+ if (!options.basicData)
238
+ throw new Error(`${test.file}: ${token}: the project gives no basic data`);
239
+ const data = options.basicData();
240
+ const item = data[value];
241
+ const found = item?.[field];
242
+ if (found === undefined)
243
+ throw new Error(`${test.file}: ${token}: this instance's basic data has no ${value}.${field}`);
244
+ return found;
245
+ }
246
+ const result = results.get(name);
247
+ return value === undefined ? result : result?.[value];
248
+ };
249
+ const text = (sentence) => sentence.replace(TOKEN, (token, name, value, field) => String(lookUp(token, name, value, field) ?? ''));
250
+ for (const [index, step] of test.steps.entries()) {
251
+ if (step.when && has(step.when.feature) !== step.when.present)
252
+ continue;
253
+ if (step.kind === 'block' || step.kind === 'verify') {
254
+ const call = await blockFunction(step.call, test.appRoot);
255
+ const options = {};
256
+ for (const field of step.call.fields) {
257
+ const raw = (step.with[field.name] ?? '').trim();
258
+ if (field.block)
259
+ options[field.name] = results.get(raw.slice(1, -1));
260
+ else if (raw)
261
+ options[field.name] = text(raw);
262
+ // Left empty, a field takes the function's own default.
263
+ }
264
+ if (step.kind === 'verify') {
265
+ try {
266
+ await call(options);
267
+ }
268
+ catch (error) {
269
+ const why = error instanceof Error ? error.message : String(error);
270
+ throw new Error(`${test.file} step ${index + 1}, verify ${step.call.label}: ${why}`, { cause: error });
271
+ }
272
+ continue;
273
+ }
274
+ const result = await call(options);
275
+ if (step.as)
276
+ results.set(step.as, (result ?? {}));
277
+ }
278
+ else if (step.kind === 'do') {
279
+ const named = {};
280
+ const instruction = step.text.replace(TOKEN, (token, name, value, field) => {
281
+ const param = [name, value, field].filter(Boolean).join('_');
282
+ named[param] = String(lookUp(token, name, value, field) ?? '');
283
+ return `{${param}}`;
284
+ });
285
+ const params = actParams(named, results);
286
+ await agent.act(instruction, Object.keys(params).length ? { params } : {});
287
+ }
288
+ else if (step.kind === 'check') {
289
+ await agent.assert(text(step.text), { screenshot: false });
290
+ }
291
+ else if (step.kind === 'waitUntil') {
292
+ await agent.waitFor(text(step.text));
293
+ }
294
+ }
295
+ }
296
+ /**
297
+ * A `do` step's params: the values its sentence names, and every block result
298
+ * so far besides, since the screen the step ends on may show any of them. The
299
+ * replay cache swaps a `unique()` value for the run's own, so block results
300
+ * go in as `unique()`; basic data, the same on every run, as is. A result the
301
+ * sentence leaves out is left out too when it sits inside another value (a
302
+ * work order number inside its reference): the cache records no step whose
303
+ * `unique()` value sits inside another param.
304
+ */
305
+ function actParams(named, results) {
306
+ const values = { ...named };
307
+ for (const [name, result] of results) {
308
+ for (const [key, value] of Object.entries(result)) {
309
+ if (typeof value === 'string' || typeof value === 'number')
310
+ values[`${name}_${key}`] ??= String(value);
311
+ }
312
+ }
313
+ const params = {};
314
+ for (const [param, value] of Object.entries(values)) {
315
+ if (param.startsWith('basic_') || !value.trim()) {
316
+ params[param] = value;
317
+ continue;
318
+ }
319
+ const inside = Object.entries(values).some(([other, v]) => other !== param && v.includes(value));
320
+ if (inside && !(param in named))
321
+ continue;
322
+ params[param] = unique(value);
323
+ }
324
+ return params;
325
+ }
326
+ const imported = new Map();
327
+ /** A building block's or a check's function, imported from its package or the app's own path. */
328
+ async function blockFunction(block, appRoot) {
329
+ const specifier = block.from.startsWith('./') ? pathToFileURL(path.join(appRoot, block.from)).href : block.from;
330
+ if (!imported.has(specifier))
331
+ imported.set(specifier, import(__rewriteRelativeImportExtension(specifier)));
332
+ const call = (await imported.get(specifier))?.[block.function];
333
+ if (typeof call !== 'function')
334
+ throw new Error(`${block.id}: ${block.from} exports no function ${block.function}`);
335
+ return call;
336
+ }
337
+ function condition(value, isFeature, listFeatures, fail) {
338
+ if (value === undefined)
339
+ return undefined;
340
+ const match = typeof value === 'string' ? /^(!?)([A-Za-z_][A-Za-z0-9_]*)$/.exec(value) : null;
341
+ if (!match || !isFeature(match[2])) {
342
+ throw fail(`"when" must be one of the project's features, or "!<feature>" for its absence; ${listFeatures()}`);
343
+ }
344
+ return { feature: match[2], present: match[1] !== '!' };
345
+ }
346
+ /** The nearest directory up from `dir` with an `e2e.config.ts`. */
347
+ function appRootOf(dir) {
348
+ for (let at = dir;; at = path.dirname(at)) {
349
+ if (existsSync(path.join(at, 'e2e.config.ts')))
350
+ return at;
351
+ if (path.dirname(at) === at)
352
+ return dir;
353
+ }
354
+ }
355
+ function relativeTo(root, file) {
356
+ return path.relative(root, file) || file;
357
+ }
358
+ function isObject(value) {
359
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
360
+ }
@@ -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>;
package/dist/studio.js ADDED
@@ -0,0 +1,93 @@
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
+ /** Where the Studio puts the address of the browser a web run drives. */
20
+ export const STUDIO_BROWSER_ENV = 'E2E_STUDIO_CDP';
21
+ /**
22
+ * The web engine's options for a run the Studio started: connect to the
23
+ * browser it hosts, so the run can be watched live there. None for any
24
+ * other run, which launches a browser of its own.
25
+ */
26
+ export function studioBrowser(env = process.env) {
27
+ const endpoint = env[STUDIO_BROWSER_ENV];
28
+ return endpoint ? { connect: { cdpEndpoint: () => endpoint } } : {};
29
+ }
30
+ /** Where the Studio puts the lease, unless the project's `mobile.leaseEnv` says otherwise. */
31
+ export const STUDIO_DEVICE_ENV = 'E2E_STUDIO_DEVICE';
32
+ /** The run's lease, or `undefined` when the Studio did not start it on a device host. */
33
+ export function studioLease(env = process.env) {
34
+ const raw = env[STUDIO_DEVICE_ENV];
35
+ if (!raw)
36
+ return undefined;
37
+ const lease = JSON.parse(raw);
38
+ if (typeof lease.id !== 'string' ||
39
+ typeof lease.deviceId !== 'string' ||
40
+ typeof lease.daemon?.baseUrl !== 'string' ||
41
+ typeof lease.daemon.authToken !== 'string') {
42
+ throw new Error(`${STUDIO_DEVICE_ENV} is not a Testra Studio device lease`);
43
+ }
44
+ return lease;
45
+ }
46
+ /**
47
+ * The mobile engine's `device` for a run on a Studio device: the one device
48
+ * the Studio leased the run, driven through the Studio. The Studio frees it
49
+ * when the run ends, so `release` has nothing to do.
50
+ */
51
+ export function studioDevice() {
52
+ return {
53
+ name: 'Testra Studio',
54
+ async acquire(request) {
55
+ const lease = studioLease(request.env);
56
+ if (!lease) {
57
+ throw new Error(`no device lease in ${STUDIO_DEVICE_ENV}: studioDevice() is for runs Testra Studio starts`);
58
+ }
59
+ if (lease.platform !== request.platform) {
60
+ throw new Error(`the Studio leased an ${lease.platform} device to a ${request.platform} target`);
61
+ }
62
+ if (request.slots > 1) {
63
+ throw new Error('Testra Studio leases one device per run; set workers: 1');
64
+ }
65
+ if (lease.agentDevice && lease.agentDevice !== request.agentDeviceVersion) {
66
+ request.log(`device host ${lease.hostName} runs agent-device ${lease.agentDevice} and this run ${request.agentDeviceVersion}; if commands misbehave, bring the one behind up to date`);
67
+ }
68
+ request.log(`${lease.device} (${lease.deviceId}) on ${lease.hostName}`);
69
+ return { id: lease.id, deviceId: lease.deviceId, daemon: lease.daemon };
70
+ },
71
+ async release() { },
72
+ };
73
+ }
74
+ /**
75
+ * Runs `adb shell <args>` on a Studio-leased Android device, on the device
76
+ * host's machine. Resolves with its output; rejects when it exits non-zero.
77
+ */
78
+ export async function studioAdbShell(lease, args) {
79
+ if (!lease.adb)
80
+ throw new Error(`${lease.device} is no Android device; adb runs on Android devices only`);
81
+ const response = await fetch(lease.adb, {
82
+ method: 'POST',
83
+ headers: { authorization: `Bearer ${lease.daemon.authToken}`, 'content-type': 'application/json' },
84
+ body: JSON.stringify({ args: ['shell', ...args] }),
85
+ });
86
+ if (!response.ok)
87
+ throw new Error(`adb shell through Testra Studio: ${response.status} ${await response.text()}`);
88
+ const result = (await response.json());
89
+ if (result.code !== 0) {
90
+ throw Object.assign(new Error(`adb shell ${args.join(' ')} exited ${result.code}: ${result.stderr.trim()}`), result);
91
+ }
92
+ return result.stdout;
93
+ }
package/package.json CHANGED
@@ -1,6 +1,48 @@
1
1
  {
2
2
  "name": "@testra-studio/kit",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "What a test project on the e2e framework needs to run under e2e Studio: its browser and devices, plain-English steps files, and basic data.",
5
+ "type": "module",
6
+ "license": "MIT",
7
+ "files": [
8
+ "dist",
9
+ "schemas",
10
+ "README.md",
11
+ "CHANGELOG.md",
12
+ "LICENSE"
13
+ ],
14
+ "exports": {
15
+ ".": {
16
+ "types": "./dist/index.d.ts",
17
+ "default": "./dist/index.js"
18
+ },
19
+ "./schemas/*": "./schemas/*",
20
+ "./package.json": "./package.json"
21
+ },
22
+ "scripts": {
23
+ "build": "rm -rf dist && tsc -p tsconfig.build.json",
24
+ "test": "node --disable-warning=ExperimentalWarning --test \"test/**/*.test.ts\"",
25
+ "prepack": "npm run build"
26
+ },
27
+ "peerDependencies": {
28
+ "@e2e-dev/mobile": "^0.12.4",
29
+ "e2e": "^0.21.3"
30
+ },
31
+ "peerDependenciesMeta": {
32
+ "@e2e-dev/mobile": {
33
+ "optional": true
34
+ }
35
+ },
36
+ "devDependencies": {
37
+ "@e2e-dev/mobile": "0.12.4"
38
+ },
39
+ "publishConfig": {
40
+ "access": "public"
41
+ },
42
+ "keywords": [
43
+ "e2e",
44
+ "testing",
45
+ "e2e-studio",
46
+ "plain-english-tests"
47
+ ]
48
+ }
@@ -0,0 +1,87 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://testra-studio/schemas/basic-data.items.schema.json",
4
+ "title": "The kinds of basic data",
5
+ "description": "basic-data.items.json, in a folder of instance files: every kind of basic data (existing records tests work with, each a code and a name), and where an instance lists each, for the Studio to pick and check values. Addresses take {serverUrl} and the instance file's other values, such as {realm}.",
6
+ "type": "object",
7
+ "required": ["items"],
8
+ "properties": {
9
+ "$schema": { "type": "string" },
10
+ "$comment": { "type": "string" },
11
+ "source": {
12
+ "type": "object",
13
+ "description": "Where instances list their records: an OData service. Without it, values are typed in.",
14
+ "required": ["odata"],
15
+ "additionalProperties": false,
16
+ "properties": {
17
+ "odata": { "$ref": "#/$defs/address", "description": "The OData service the lookups' entity sets are under." },
18
+ "signIn": {
19
+ "type": "object",
20
+ "description": "An OpenID Connect password grant, for a bearer token.",
21
+ "required": ["tokenUrl", "clientId"],
22
+ "additionalProperties": false,
23
+ "properties": {
24
+ "tokenUrl": { "$ref": "#/$defs/address" },
25
+ "clientId": { "type": "string", "minLength": 1 },
26
+ "clientIdFrom": {
27
+ "$ref": "#/$defs/variable",
28
+ "description": "A credential that, when kept for the instance, is the client id instead."
29
+ },
30
+ "scope": { "type": "string", "default": "openid" },
31
+ "realmFrom": {
32
+ "$ref": "#/$defs/address",
33
+ "description": "An address that, asked without a token, names {realm} in its WWW-Authenticate header, as Keycloak does; used when the instance's file gives no realm."
34
+ }
35
+ }
36
+ },
37
+ "credentials": {
38
+ "type": "array",
39
+ "description": "The credentials to sign in with, by the names the Studio keeps them under for an instance; the first pair kept is used.",
40
+ "items": {
41
+ "type": "object",
42
+ "required": ["username", "password"],
43
+ "additionalProperties": false,
44
+ "properties": { "username": { "$ref": "#/$defs/variable" }, "password": { "$ref": "#/$defs/variable" } }
45
+ }
46
+ }
47
+ }
48
+ },
49
+ "items": {
50
+ "type": "object",
51
+ "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
52
+ "additionalProperties": {
53
+ "type": "object",
54
+ "required": ["label"],
55
+ "additionalProperties": false,
56
+ "properties": {
57
+ "label": { "type": "string", "minLength": 1 },
58
+ "help": { "type": "string" },
59
+ "lookup": {
60
+ "type": "object",
61
+ "required": ["set", "code", "name"],
62
+ "additionalProperties": false,
63
+ "properties": {
64
+ "set": {
65
+ "type": "string",
66
+ "pattern": "^[A-Za-z0-9_][A-Za-z0-9_./-]*$",
67
+ "description": "The entity set under the service: Customers, or Orders.svc/Customers."
68
+ },
69
+ "code": { "$ref": "#/$defs/name" },
70
+ "name": { "$ref": "#/$defs/name" },
71
+ "filter": {
72
+ "type": "string",
73
+ "maxLength": 1000,
74
+ "description": "An OData filter; {site.code} is another item's value."
75
+ }
76
+ }
77
+ }
78
+ }
79
+ }
80
+ }
81
+ },
82
+ "$defs": {
83
+ "address": { "type": "string", "pattern": "^(https?://|\\{serverUrl\\})\\S*$" },
84
+ "variable": { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]*$" },
85
+ "name": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }
86
+ }
87
+ }
@@ -0,0 +1,31 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://testra-studio/schemas/instance.schema.json",
4
+ "title": "An instance",
5
+ "description": "One file a parameter's options are read from, such as environments/<name>.json. The Studio reads the values below; any others are the project's own, such as the attributes its config names (a track) and the values its basic data's addresses take (a realm).",
6
+ "type": "object",
7
+ "properties": {
8
+ "$schema": { "type": "string" },
9
+ "serverUrl": {
10
+ "type": "string",
11
+ "pattern": "^https?://\\S+$",
12
+ "description": "The instance as the Studio's machine reaches it: where recordings start, and what Check and basic data lookups ask."
13
+ },
14
+ "deviceServerUrl": {
15
+ "type": "string",
16
+ "pattern": "^https?://\\S+$",
17
+ "description": "The instance as a device or emulator reaches it, when that differs."
18
+ },
19
+ "basicData": {
20
+ "type": "object",
21
+ "description": "The instance's own basic data, over the shared basic-data.json; the items are basic-data.items.json's.",
22
+ "additionalProperties": {
23
+ "type": "object",
24
+ "required": ["code", "name"],
25
+ "additionalProperties": false,
26
+ "properties": { "code": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 } }
27
+ }
28
+ }
29
+ },
30
+ "additionalProperties": true
31
+ }
@@ -0,0 +1,79 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://testra-studio/schemas/steps.schema.json",
4
+ "title": "A plain-English test",
5
+ "description": "A test's steps, in <name>.steps.json beside the <name>.e2e.ts that runs them. An AI agent carries out each \"do\", judges each \"check\" against the screen, and waits for each \"waitUntil\"; \"block\" and \"verify\" call the project's building blocks and checks (e2e-studio.blocks.json). In a sentence, {work1.description} is a value an earlier block returned, and {basic.site.code} the instance's basic data.",
6
+ "type": "object",
7
+ "required": ["title", "steps"],
8
+ "additionalProperties": false,
9
+ "properties": {
10
+ "$schema": { "type": "string" },
11
+ "title": { "type": "string", "minLength": 1, "description": "What the test proves, as a sentence." },
12
+ "requires": {
13
+ "type": "array",
14
+ "items": { "type": "string" },
15
+ "description": "Features the system under test must have; the project's runner skips the test without them."
16
+ },
17
+ "steps": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/step" } }
18
+ },
19
+ "$defs": {
20
+ "sentence": { "type": "string", "minLength": 1, "maxLength": 500, "pattern": "^[^\\n]*$" },
21
+ "when": {
22
+ "type": "string",
23
+ "pattern": "^!?[A-Za-z_][A-Za-z0-9_]*$",
24
+ "description": "Only with this feature, or only without it (\"!feature\")."
25
+ },
26
+ "fields": {
27
+ "type": "object",
28
+ "additionalProperties": { "type": "string" },
29
+ "description": "The call's fields by name; a field that takes an earlier block's result is \"{work1}\"."
30
+ },
31
+ "step": {
32
+ "oneOf": [
33
+ {
34
+ "type": "object",
35
+ "required": ["do"],
36
+ "additionalProperties": false,
37
+ "properties": { "do": { "$ref": "#/$defs/sentence" }, "when": { "$ref": "#/$defs/when" } }
38
+ },
39
+ {
40
+ "type": "object",
41
+ "required": ["check"],
42
+ "additionalProperties": false,
43
+ "properties": { "check": { "$ref": "#/$defs/sentence" }, "when": { "$ref": "#/$defs/when" } }
44
+ },
45
+ {
46
+ "type": "object",
47
+ "required": ["waitUntil"],
48
+ "additionalProperties": false,
49
+ "properties": { "waitUntil": { "$ref": "#/$defs/sentence" }, "when": { "$ref": "#/$defs/when" } }
50
+ },
51
+ {
52
+ "type": "object",
53
+ "required": ["block"],
54
+ "additionalProperties": false,
55
+ "properties": {
56
+ "block": { "type": "string", "description": "A building block's id." },
57
+ "as": {
58
+ "type": "string",
59
+ "pattern": "^[a-z][A-Za-z0-9]*$",
60
+ "description": "What later steps call its result: work1."
61
+ },
62
+ "with": { "$ref": "#/$defs/fields" },
63
+ "when": { "$ref": "#/$defs/when" }
64
+ }
65
+ },
66
+ {
67
+ "type": "object",
68
+ "required": ["verify"],
69
+ "additionalProperties": false,
70
+ "properties": {
71
+ "verify": { "type": "string", "description": "A check's id." },
72
+ "with": { "$ref": "#/$defs/fields" },
73
+ "when": { "$ref": "#/$defs/when" }
74
+ }
75
+ }
76
+ ]
77
+ }
78
+ }
79
+ }