@testra-studio/kit 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +39 -0
- package/LICENSE +21 -0
- package/README.md +112 -2
- package/dist/actions.d.ts +109 -0
- package/dist/actions.js +117 -0
- package/dist/basic-data.d.ts +39 -0
- package/dist/basic-data.js +109 -0
- package/dist/index.d.ts +15 -0
- package/dist/index.js +15 -0
- package/dist/plain.d.ts +171 -0
- package/dist/plain.js +398 -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 +429 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,39 @@
|
|
|
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.2.0
|
|
9
|
+
|
|
10
|
+
- A Do step may keep the `actions` it was recorded with in e2e Studio:
|
|
11
|
+
tap, doubleTap, fill, type, select, check, uncheck, press and key, each
|
|
12
|
+
on an element as a structured target (a role and name, a test id, a
|
|
13
|
+
placeholder, an id or a text, inside its frame, dialog and row).
|
|
14
|
+
`runSteps()` does them on the exact elements, with no model call, and
|
|
15
|
+
falls back to the agent and the step's sentence when one is not there.
|
|
16
|
+
- `runSteps()` takes `{ agent, screen, browser }`, which the actions need;
|
|
17
|
+
given the agent alone, as before, every Do step is the agent's.
|
|
18
|
+
- The steps schema has `actions` on Do steps.
|
|
19
|
+
|
|
20
|
+
What a project does: pass `{ agent, screen, browser }` to `runSteps()` in a
|
|
21
|
+
web project's `support/plain.ts`. Nothing else changes; steps files without
|
|
22
|
+
actions run as they did.
|
|
23
|
+
|
|
24
|
+
## 0.1.0
|
|
25
|
+
|
|
26
|
+
The first version, moved out of a project's own test kit so any project on
|
|
27
|
+
the e2e framework can run under e2e Studio:
|
|
28
|
+
|
|
29
|
+
- `studioBrowser()`: the web engine's options for the browser the Studio
|
|
30
|
+
hosts a run in (`E2E_STUDIO_CDP`), so it can be watched live.
|
|
31
|
+
- `studioDevice()`, `studioLease()`, `studioAdbShell()`: the device the
|
|
32
|
+
Studio leased a mobile run (`E2E_STUDIO_DEVICE`).
|
|
33
|
+
- `loadPlainTest()`, `runSteps()`, `missingFeatures()`: plain-English steps
|
|
34
|
+
files, with building blocks, checks, `{basic.…}` tokens and a project's
|
|
35
|
+
features passed in as `PlainOptions`.
|
|
36
|
+
- `readBasicData()`: an instance's basic data, from the variable, the local
|
|
37
|
+
file, the instance's file and the shared file, in that order.
|
|
38
|
+
- `schemas/`: the JSON Schemas of steps files, `basic-data.items.json` and
|
|
39
|
+
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,113 @@
|
|
|
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, screen, browser }) => {
|
|
59
|
+
await app.open();
|
|
60
|
+
// screen and browser let recorded steps run on their exact elements; a mobile project passes the agent alone.
|
|
61
|
+
await runSteps({ agent, screen, browser }, plain, options);
|
|
62
|
+
});
|
|
63
|
+
}
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
```ts
|
|
67
|
+
// tests/checkout/full-cart.e2e.ts
|
|
68
|
+
import { plainTest } from '../../support/plain.ts';
|
|
69
|
+
|
|
70
|
+
plainTest(import.meta.url);
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Building blocks and checks are listed in `e2e-studio.blocks.json`, beside
|
|
74
|
+
`e2e.config.ts`.
|
|
75
|
+
|
|
76
|
+
### Recorded steps
|
|
77
|
+
|
|
78
|
+
A Do step recorded in e2e Studio keeps what it did, on the exact elements:
|
|
79
|
+
|
|
80
|
+
```json
|
|
81
|
+
{
|
|
82
|
+
"do": "Search for pump",
|
|
83
|
+
"actions": [
|
|
84
|
+
{ "fill": { "role": "searchbox", "name": "Search" }, "value": "pump" },
|
|
85
|
+
{ "press": { "role": "searchbox", "name": "Search" }, "key": "Enter" }
|
|
86
|
+
]
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
`runSteps()` does the actions through the web engine's `screen` and
|
|
91
|
+
`browser`, with no model call. When one of them is not found within 15
|
|
92
|
+
seconds (the screen changed since it was recorded), the step falls back to
|
|
93
|
+
the agent and its sentence, and the run log says which step did. An element
|
|
94
|
+
is structured, never code: a role with its name (or `nameStarts`), else a
|
|
95
|
+
`testId`, `placeholder`, `id` or `text`, with the `frame`, `dialog` and
|
|
96
|
+
`row` it is in.
|
|
97
|
+
|
|
98
|
+
## Basic data
|
|
99
|
+
|
|
100
|
+
`readBasicData({ dir, instance, fromEnv })` takes each item, listed in
|
|
101
|
+
`<dir>/basic-data.items.json` ([schema](schemas/basic-data.items.schema.json)),
|
|
102
|
+
from the first source that sets it: the `fromEnv` variable's JSON,
|
|
103
|
+
`<instance>.local.json`, `basicData` in `<instance>.json`
|
|
104
|
+
([schema](schemas/instance.schema.json)), then `basic-data.json`.
|
|
105
|
+
|
|
106
|
+
## Releasing
|
|
107
|
+
|
|
108
|
+
The kit is built and tested with the Studio, on every pull request. A pull
|
|
109
|
+
request that changes it bumps `version` in `package.json` and adds a
|
|
110
|
+
`CHANGELOG.md` section; merged to main, the pipeline publishes that version to
|
|
111
|
+
npm (`scripts/publish-kit.ts`, with the `NPM_TOKEN` repository variable). Before 1.0, a minor version is a
|
|
112
|
+
change projects must react to; the Studio's project check warns about a kit
|
|
113
|
+
older than it works with (`KIT_MINIMUM` in `apps/server/src/projects.ts`).
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Recorded actions: what a Do step recorded in e2e Studio did, kept in the
|
|
3
|
+
* steps file so a run does it on the exact elements (`StepAction`), with the
|
|
4
|
+
* element as a structured target (`StepTarget`) the kit builds the web
|
|
5
|
+
* engine's locator from. Nothing here evaluates code from the file.
|
|
6
|
+
*
|
|
7
|
+
* { "do": "Search for pump", "actions": [
|
|
8
|
+
* { "fill": { "role": "searchbox", "name": "Search" }, "value": "pump" },
|
|
9
|
+
* { "press": { "role": "searchbox", "name": "Search" }, "key": "Enter" } ] }
|
|
10
|
+
*/
|
|
11
|
+
/** An element, as the web engine finds it: one way, inside its frame, dialog and row. */
|
|
12
|
+
export interface StepTarget {
|
|
13
|
+
readonly role?: string;
|
|
14
|
+
readonly name?: string;
|
|
15
|
+
/** How a long name starts. */
|
|
16
|
+
readonly nameStarts?: string;
|
|
17
|
+
readonly testId?: string;
|
|
18
|
+
readonly placeholder?: string;
|
|
19
|
+
readonly id?: string;
|
|
20
|
+
readonly text?: string;
|
|
21
|
+
readonly dialog?: string;
|
|
22
|
+
readonly row?: string;
|
|
23
|
+
/** The iframe it is in, as a CSS selector. */
|
|
24
|
+
readonly frame?: string;
|
|
25
|
+
}
|
|
26
|
+
export type StepAction = {
|
|
27
|
+
readonly tap: StepTarget;
|
|
28
|
+
} | {
|
|
29
|
+
readonly doubleTap: StepTarget;
|
|
30
|
+
} | {
|
|
31
|
+
readonly fill: StepTarget;
|
|
32
|
+
readonly value: string;
|
|
33
|
+
} | {
|
|
34
|
+
readonly type: StepTarget;
|
|
35
|
+
readonly value: string;
|
|
36
|
+
} | {
|
|
37
|
+
readonly select: StepTarget;
|
|
38
|
+
readonly value: string;
|
|
39
|
+
} | {
|
|
40
|
+
readonly check: StepTarget;
|
|
41
|
+
} | {
|
|
42
|
+
readonly uncheck: StepTarget;
|
|
43
|
+
} | {
|
|
44
|
+
readonly press: StepTarget;
|
|
45
|
+
readonly key: string;
|
|
46
|
+
} | {
|
|
47
|
+
readonly key: string;
|
|
48
|
+
};
|
|
49
|
+
/** The parts of the web engine's locator the actions use. */
|
|
50
|
+
export interface LocatorLike {
|
|
51
|
+
tap(options?: {
|
|
52
|
+
timeout?: number;
|
|
53
|
+
}): Promise<unknown>;
|
|
54
|
+
doubleTap(options?: {
|
|
55
|
+
timeout?: number;
|
|
56
|
+
}): Promise<unknown>;
|
|
57
|
+
fill(value: string, options?: {
|
|
58
|
+
timeout?: number;
|
|
59
|
+
}): Promise<unknown>;
|
|
60
|
+
pressSequentially(text: string, options?: {
|
|
61
|
+
timeout?: number;
|
|
62
|
+
}): Promise<unknown>;
|
|
63
|
+
selectOption(value: string, options?: {
|
|
64
|
+
timeout?: number;
|
|
65
|
+
}): Promise<unknown>;
|
|
66
|
+
check(options?: {
|
|
67
|
+
timeout?: number;
|
|
68
|
+
}): Promise<unknown>;
|
|
69
|
+
uncheck(options?: {
|
|
70
|
+
timeout?: number;
|
|
71
|
+
}): Promise<unknown>;
|
|
72
|
+
press(key: string, options?: {
|
|
73
|
+
timeout?: number;
|
|
74
|
+
}): Promise<unknown>;
|
|
75
|
+
getByRole(role: never, name?: string | RegExp): LocatorLike;
|
|
76
|
+
getByTestId(id: string): LocatorLike;
|
|
77
|
+
getByPlaceholder(text: string): LocatorLike;
|
|
78
|
+
getByText(text: string): LocatorLike;
|
|
79
|
+
filter(options: {
|
|
80
|
+
hasText: string;
|
|
81
|
+
}): LocatorLike;
|
|
82
|
+
}
|
|
83
|
+
/** The web engine's `screen`, or a frame's. */
|
|
84
|
+
export interface ScreenLike {
|
|
85
|
+
getByRole(role: never, name?: string | RegExp): LocatorLike;
|
|
86
|
+
getByTestId(id: string): LocatorLike;
|
|
87
|
+
getByPlaceholder(text: string): LocatorLike;
|
|
88
|
+
getByText(text: string): LocatorLike;
|
|
89
|
+
}
|
|
90
|
+
/** The web engine's `browser`, for an id, a frame and a key on whatever has focus. */
|
|
91
|
+
export interface BrowserLike {
|
|
92
|
+
locator(selector: string): LocatorLike;
|
|
93
|
+
frameLocator(selector: string): ScreenLike & {
|
|
94
|
+
locator(selector: string): LocatorLike;
|
|
95
|
+
};
|
|
96
|
+
readonly keyboard: {
|
|
97
|
+
press(key: string): Promise<unknown>;
|
|
98
|
+
};
|
|
99
|
+
}
|
|
100
|
+
/** Why `value` is no recorded action, or nothing when it is one. */
|
|
101
|
+
export declare function actionProblem(value: unknown): string | undefined;
|
|
102
|
+
/** The values an action types, fills or chooses, for its `{…}` tokens. */
|
|
103
|
+
export declare function actionValue(action: StepAction): string | undefined;
|
|
104
|
+
/** The web engine's locator for a target, inside its frame, dialog and row. */
|
|
105
|
+
export declare function locate(target: StepTarget, screen: ScreenLike, browser: BrowserLike | undefined): LocatorLike;
|
|
106
|
+
/** How long one recorded action waits for its element before the step falls back to its sentence. */
|
|
107
|
+
export declare const ACTION_TIMEOUT = 15000;
|
|
108
|
+
/** Does one recorded action, its value with the run's values in place of `{…}` (`value`). */
|
|
109
|
+
export declare function perform(action: StepAction, screen: ScreenLike, browser: BrowserLike | undefined, value: (text: string) => string): Promise<void>;
|
package/dist/actions.js
ADDED
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Recorded actions: what a Do step recorded in e2e Studio did, kept in the
|
|
3
|
+
* steps file so a run does it on the exact elements (`StepAction`), with the
|
|
4
|
+
* element as a structured target (`StepTarget`) the kit builds the web
|
|
5
|
+
* engine's locator from. Nothing here evaluates code from the file.
|
|
6
|
+
*
|
|
7
|
+
* { "do": "Search for pump", "actions": [
|
|
8
|
+
* { "fill": { "role": "searchbox", "name": "Search" }, "value": "pump" },
|
|
9
|
+
* { "press": { "role": "searchbox", "name": "Search" }, "key": "Enter" } ] }
|
|
10
|
+
*/
|
|
11
|
+
const TARGET_KEYS = ['role', 'name', 'nameStarts', 'testId', 'placeholder', 'id', 'text', 'dialog', 'row', 'frame'];
|
|
12
|
+
const WITH_VALUE = ['fill', 'type', 'select'];
|
|
13
|
+
const ON_TARGET = ['tap', 'doubleTap', 'check', 'uncheck'];
|
|
14
|
+
/** Why `value` is no recorded action, or nothing when it is one. */
|
|
15
|
+
export function actionProblem(value) {
|
|
16
|
+
if (!isObject(value))
|
|
17
|
+
return 'an action is an object such as { "tap": { "role": "button", "name": "Save" } }';
|
|
18
|
+
const keys = Object.keys(value);
|
|
19
|
+
const kind = keys.find((k) => [...ON_TARGET, ...WITH_VALUE, 'press'].includes(k)) ?? (keys.includes('key') ? 'key' : '');
|
|
20
|
+
const allowed = WITH_VALUE.includes(kind)
|
|
21
|
+
? [kind, 'value']
|
|
22
|
+
: kind === 'press'
|
|
23
|
+
? ['press', 'key']
|
|
24
|
+
: [kind];
|
|
25
|
+
if (!kind)
|
|
26
|
+
return `${JSON.stringify(value)} is no action: tap, doubleTap, fill, type, select, check, uncheck, press or key`;
|
|
27
|
+
const extra = keys.filter((k) => !allowed.includes(k));
|
|
28
|
+
if (extra.length)
|
|
29
|
+
return `${kind}: unknown key ${extra.join(', ')}`;
|
|
30
|
+
if (WITH_VALUE.includes(kind) && typeof value.value !== 'string')
|
|
31
|
+
return `${kind} needs a "value"`;
|
|
32
|
+
if ((kind === 'press' || kind === 'key') &&
|
|
33
|
+
(typeof value.key !== 'string' || !/^[A-Za-z0-9+]{1,40}$/.test(value.key))) {
|
|
34
|
+
return `${kind} needs a "key" such as Enter or Tab`;
|
|
35
|
+
}
|
|
36
|
+
if (kind === 'key')
|
|
37
|
+
return undefined;
|
|
38
|
+
return targetProblem(value[kind]);
|
|
39
|
+
}
|
|
40
|
+
function targetProblem(target) {
|
|
41
|
+
if (!isObject(target))
|
|
42
|
+
return 'an element is an object such as { "role": "button", "name": "Save" }';
|
|
43
|
+
const extra = Object.keys(target).filter((k) => !TARGET_KEYS.includes(k));
|
|
44
|
+
if (extra.length)
|
|
45
|
+
return `an element has no ${extra.join(', ')}`;
|
|
46
|
+
if (Object.values(target).some((v) => typeof v !== 'string' || !v))
|
|
47
|
+
return "an element's values are text";
|
|
48
|
+
const ways = [
|
|
49
|
+
target.role !== undefined && (target.name !== undefined) !== (target.nameStarts !== undefined),
|
|
50
|
+
target.testId !== undefined,
|
|
51
|
+
target.placeholder !== undefined,
|
|
52
|
+
target.id !== undefined,
|
|
53
|
+
target.text !== undefined,
|
|
54
|
+
].filter(Boolean).length;
|
|
55
|
+
if (ways !== 1 || (target.role !== undefined && target.name === undefined && target.nameStarts === undefined)) {
|
|
56
|
+
return 'an element is found one way: a role with a name (or how it starts), a test id, a placeholder, an id or a text';
|
|
57
|
+
}
|
|
58
|
+
return undefined;
|
|
59
|
+
}
|
|
60
|
+
/** The values an action types, fills or chooses, for its `{…}` tokens. */
|
|
61
|
+
export function actionValue(action) {
|
|
62
|
+
return 'value' in action ? action.value : undefined;
|
|
63
|
+
}
|
|
64
|
+
/** The web engine's locator for a target, inside its frame, dialog and row. */
|
|
65
|
+
export function locate(target, screen, browser) {
|
|
66
|
+
const frame = target.frame ? need(browser, 'an element in a frame').frameLocator(target.frame) : undefined;
|
|
67
|
+
if (target.id !== undefined)
|
|
68
|
+
return (frame ?? need(browser, 'an element by its id')).locator(`#${target.id}`);
|
|
69
|
+
let scope = frame ?? screen;
|
|
70
|
+
if (target.dialog)
|
|
71
|
+
scope = scope.getByRole('dialog', target.dialog);
|
|
72
|
+
if (target.row)
|
|
73
|
+
scope = scope.getByRole('row').filter({ hasText: target.row });
|
|
74
|
+
if (target.role && target.name !== undefined)
|
|
75
|
+
return scope.getByRole(target.role, target.name);
|
|
76
|
+
if (target.role && target.nameStarts !== undefined) {
|
|
77
|
+
return scope.getByRole(target.role, new RegExp(`^${target.nameStarts.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`));
|
|
78
|
+
}
|
|
79
|
+
if (target.testId !== undefined)
|
|
80
|
+
return scope.getByTestId(target.testId);
|
|
81
|
+
if (target.placeholder !== undefined)
|
|
82
|
+
return scope.getByPlaceholder(target.placeholder);
|
|
83
|
+
return scope.getByText(target.text ?? '');
|
|
84
|
+
}
|
|
85
|
+
/** How long one recorded action waits for its element before the step falls back to its sentence. */
|
|
86
|
+
export const ACTION_TIMEOUT = 15_000;
|
|
87
|
+
/** Does one recorded action, its value with the run's values in place of `{…}` (`value`). */
|
|
88
|
+
export async function perform(action, screen, browser, value) {
|
|
89
|
+
const timeout = { timeout: ACTION_TIMEOUT };
|
|
90
|
+
if ('tap' in action)
|
|
91
|
+
return void (await locate(action.tap, screen, browser).tap(timeout));
|
|
92
|
+
if ('doubleTap' in action)
|
|
93
|
+
return void (await locate(action.doubleTap, screen, browser).doubleTap(timeout));
|
|
94
|
+
if ('fill' in action)
|
|
95
|
+
return void (await locate(action.fill, screen, browser).fill(value(action.value), timeout));
|
|
96
|
+
if ('type' in action) {
|
|
97
|
+
return void (await locate(action.type, screen, browser).pressSequentially(value(action.value), timeout));
|
|
98
|
+
}
|
|
99
|
+
if ('select' in action) {
|
|
100
|
+
return void (await locate(action.select, screen, browser).selectOption(value(action.value), timeout));
|
|
101
|
+
}
|
|
102
|
+
if ('check' in action)
|
|
103
|
+
return void (await locate(action.check, screen, browser).check(timeout));
|
|
104
|
+
if ('uncheck' in action)
|
|
105
|
+
return void (await locate(action.uncheck, screen, browser).uncheck(timeout));
|
|
106
|
+
if ('press' in action)
|
|
107
|
+
return void (await locate(action.press, screen, browser).press(action.key, timeout));
|
|
108
|
+
await need(browser, 'a key on whatever has focus').keyboard.press(action.key);
|
|
109
|
+
}
|
|
110
|
+
function need(value, what) {
|
|
111
|
+
if (value === undefined)
|
|
112
|
+
throw new Error(`${what} needs the browser fixture, which the runner did not pass`);
|
|
113
|
+
return value;
|
|
114
|
+
}
|
|
115
|
+
function isObject(value) {
|
|
116
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
117
|
+
}
|
|
@@ -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,15 @@
|
|
|
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
|
+
* whose recorded Do steps run on the exact elements they were recorded on.
|
|
9
|
+
* - `readBasicData()`: an instance's basic data, as the Studio edits it.
|
|
10
|
+
* - `schemas/`: the JSON Schemas of the files the Studio and a project share.
|
|
11
|
+
*/
|
|
12
|
+
export { ACTION_TIMEOUT, type BrowserLike, type LocatorLike, locate, type ScreenLike, type StepAction, type StepTarget, } from './actions.ts';
|
|
13
|
+
export { BASIC_DATA_ITEMS_FILE, type BasicDataOptions, basicDataItems, type CodeAndName, readBasicData, SHARED_BASIC_DATA_FILE, } from './basic-data.ts';
|
|
14
|
+
export { type Agent, BLOCKS_FILE, type BlockDefinition, type Catalog, type Condition, loadPlainTest, missingFeatures, type PlainFixtures, type PlainOptions, type PlainStep, type PlainTest, parsePlainTest, readCatalog, runSteps, STEPS_FILE_SUFFIX, } from './plain.ts';
|
|
15
|
+
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,15 @@
|
|
|
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
|
+
* whose recorded Do steps run on the exact elements they were recorded on.
|
|
9
|
+
* - `readBasicData()`: an instance's basic data, as the Studio edits it.
|
|
10
|
+
* - `schemas/`: the JSON Schemas of the files the Studio and a project share.
|
|
11
|
+
*/
|
|
12
|
+
export { ACTION_TIMEOUT, locate, } from './actions.js';
|
|
13
|
+
export { BASIC_DATA_ITEMS_FILE, basicDataItems, readBasicData, SHARED_BASIC_DATA_FILE, } from './basic-data.js';
|
|
14
|
+
export { BLOCKS_FILE, loadPlainTest, missingFeatures, parsePlainTest, readCatalog, runSteps, STEPS_FILE_SUFFIX, } from './plain.js';
|
|
15
|
+
export { STUDIO_BROWSER_ENV, STUDIO_DEVICE_ENV, studioAdbShell, studioBrowser, studioDevice, studioLease, } from './studio.js';
|