@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 +23 -0
- package/LICENSE +21 -0
- package/README.md +89 -2
- package/dist/basic-data.d.ts +39 -0
- package/dist/basic-data.js +109 -0
- package/dist/index.d.ts +13 -0
- package/dist/index.js +13 -0
- package/dist/plain.d.ts +158 -0
- package/dist/plain.js +360 -0
- package/dist/studio.d.ts +74 -0
- package/dist/studio.js +93 -0
- package/package.json +46 -4
- package/schemas/basic-data.items.schema.json +87 -0
- package/schemas/instance.schema.json +31 -0
- package/schemas/steps.schema.json +79 -0
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
|
-
#
|
|
1
|
+
# @testra-studio/kit
|
|
2
2
|
|
|
3
|
-
|
|
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
|
+
}
|
package/dist/index.d.ts
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, 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';
|
package/dist/plain.d.ts
ADDED
|
@@ -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
|
+
}
|
package/dist/studio.d.ts
ADDED
|
@@ -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.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
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
|
+
}
|