@testra-studio/kit 0.3.0 → 0.4.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 +15 -0
- package/README.md +26 -0
- package/dist/actions.d.ts +7 -1
- package/dist/actions.js +81 -17
- package/dist/plain.d.ts +6 -1
- package/dist/plain.js +28 -2
- package/package.json +1 -1
- package/schemas/steps.schema.json +19 -1
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,21 @@ A major version (or, before 1.0, a minor one) changes a format or a
|
|
|
5
5
|
variable e2e Studio and the project share; the Studio's project check names
|
|
6
6
|
the oldest kit it works with.
|
|
7
7
|
|
|
8
|
+
## 0.4.0
|
|
9
|
+
|
|
10
|
+
- A Do step with actions may say what shows when it is done, in a Check's
|
|
11
|
+
`expect` form: `runSteps()` waits for it after the actions, so the next
|
|
12
|
+
step does not start on a page still busy (a lookup resolving after Tab, a
|
|
13
|
+
save). Showing something else fails the step; not there, the agent
|
|
14
|
+
finishes the step from its sentence.
|
|
15
|
+
- An element may say which of several it is, from 0: `"nth": 1`. An element
|
|
16
|
+
without one that matches several when a step runs (or as it is done) is
|
|
17
|
+
the first of them, as a hand-written test's `.first()` takes it, and the
|
|
18
|
+
run warns. Before, such a step fell back to the agent.
|
|
19
|
+
- The steps schema has both.
|
|
20
|
+
|
|
21
|
+
What a project does: nothing. Steps files without these run as they did.
|
|
22
|
+
|
|
8
23
|
## 0.3.0
|
|
9
24
|
|
|
10
25
|
- A Do step's actions may open a page by its address in the app:
|
package/README.md
CHANGED
|
@@ -120,6 +120,32 @@ something else fails the check, with the framework's message. An element
|
|
|
120
120
|
that is not there within 15 seconds (the screen changed) makes the agent
|
|
121
121
|
judge the sentence instead, as for a Do step.
|
|
122
122
|
|
|
123
|
+
A Do step with actions may say what shows when it is done, in the same
|
|
124
|
+
form (kit 0.4.0). `runSteps()` waits for it after the actions, so the next
|
|
125
|
+
step does not start on a page still busy, as a lookup resolving after Tab:
|
|
126
|
+
|
|
127
|
+
```json
|
|
128
|
+
{
|
|
129
|
+
"do": "Set WO Site to {basic.site.code}",
|
|
130
|
+
"actions": [
|
|
131
|
+
{ "fill": { "role": "combobox", "name": "WO Site" }, "value": "{basic.site.code}" },
|
|
132
|
+
{ "press": { "role": "combobox", "name": "WO Site" }, "key": "Tab" }
|
|
133
|
+
],
|
|
134
|
+
"expect": [
|
|
135
|
+
{ "target": { "role": "combobox", "name": "WO Site" }, "matcher": "toHaveValue",
|
|
136
|
+
"value": "{basic.site.code} - {basic.site.name}" }
|
|
137
|
+
]
|
|
138
|
+
}
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Showing something else fails the step; not there, the agent finishes the
|
|
142
|
+
step from its sentence.
|
|
143
|
+
|
|
144
|
+
An element may say which of several matching ones it is, from 0 (kit 0.4.0):
|
|
145
|
+
`{ "role": "button", "name": "New", "nth": 1 }`. One that does not, and
|
|
146
|
+
matches several when the step runs, is the first of them, and the run
|
|
147
|
+
warns.
|
|
148
|
+
|
|
123
149
|
## Basic data
|
|
124
150
|
|
|
125
151
|
`readBasicData({ dir, instance, fromEnv })` takes each item, listed in
|
package/dist/actions.d.ts
CHANGED
|
@@ -28,6 +28,8 @@ export interface StepTarget {
|
|
|
28
28
|
readonly row?: string;
|
|
29
29
|
/** The iframe it is in, as a CSS selector. */
|
|
30
30
|
readonly frame?: string;
|
|
31
|
+
/** Which of several matching elements, from 0: as `.first()` (0) or `.nth(n)` found it. Kit 0.4.0. */
|
|
32
|
+
readonly nth?: number;
|
|
31
33
|
}
|
|
32
34
|
export type StepAction = {
|
|
33
35
|
readonly tap: StepTarget;
|
|
@@ -86,6 +88,10 @@ export interface LocatorLike {
|
|
|
86
88
|
press(key: string, options?: {
|
|
87
89
|
timeout?: number;
|
|
88
90
|
}): Promise<unknown>;
|
|
91
|
+
/** How many elements match now, without waiting; where the engine has it. */
|
|
92
|
+
count?(): Promise<number>;
|
|
93
|
+
first?(): LocatorLike;
|
|
94
|
+
nth?(index: number): LocatorLike;
|
|
89
95
|
getByRole(role: never, name?: string | RegExp): LocatorLike;
|
|
90
96
|
getByTestId(id: string): LocatorLike;
|
|
91
97
|
getByPlaceholder(text: string): LocatorLike;
|
|
@@ -117,7 +123,7 @@ export interface BrowserLike {
|
|
|
117
123
|
export declare function actionProblem(value: unknown): string | undefined;
|
|
118
124
|
/** The values an action types, fills or chooses, for its `{…}` tokens. */
|
|
119
125
|
export declare function actionValue(action: StepAction): string | undefined;
|
|
120
|
-
/** The web engine's locator for a target, inside its frame, dialog and row. */
|
|
126
|
+
/** The web engine's locator for a target, inside its frame, dialog and row; the `nth` of them when it says. */
|
|
121
127
|
export declare function locate(target: StepTarget, screen: ScreenLike, browser: BrowserLike | undefined): LocatorLike;
|
|
122
128
|
/** How long one recorded action waits for its element before the step falls back to its sentence. */
|
|
123
129
|
export declare const ACTION_TIMEOUT = 15000;
|
package/dist/actions.js
CHANGED
|
@@ -24,6 +24,7 @@ const TARGET_KEYS = [
|
|
|
24
24
|
'dialog',
|
|
25
25
|
'row',
|
|
26
26
|
'frame',
|
|
27
|
+
'nth',
|
|
27
28
|
];
|
|
28
29
|
const WITH_VALUE = ['fill', 'type', 'select'];
|
|
29
30
|
const ON_TARGET = ['tap', 'doubleTap', 'check', 'uncheck'];
|
|
@@ -70,7 +71,11 @@ function targetProblem(target) {
|
|
|
70
71
|
const extra = Object.keys(target).filter((k) => !TARGET_KEYS.includes(k));
|
|
71
72
|
if (extra.length)
|
|
72
73
|
return `an element has no ${extra.join(', ')}`;
|
|
73
|
-
|
|
74
|
+
const { nth, ...found } = target;
|
|
75
|
+
if (nth !== undefined && !(Number.isInteger(nth) && nth >= 0 && nth < 100)) {
|
|
76
|
+
return '"nth" is which of several matching elements, a whole number from 0';
|
|
77
|
+
}
|
|
78
|
+
if (Object.values(found).some((v) => typeof v !== 'string' || !v))
|
|
74
79
|
return "an element's values are text";
|
|
75
80
|
const ways = [
|
|
76
81
|
target.role !== undefined && (target.name !== undefined) !== (target.nameStarts !== undefined),
|
|
@@ -89,8 +94,46 @@ function targetProblem(target) {
|
|
|
89
94
|
export function actionValue(action) {
|
|
90
95
|
return 'value' in action ? action.value : undefined;
|
|
91
96
|
}
|
|
92
|
-
/** The web engine's locator for a target, inside its frame, dialog and row. */
|
|
97
|
+
/** The web engine's locator for a target, inside its frame, dialog and row; the `nth` of them when it says. */
|
|
93
98
|
export function locate(target, screen, browser) {
|
|
99
|
+
const all = matching(target, screen, browser);
|
|
100
|
+
return target.nth === undefined
|
|
101
|
+
? all
|
|
102
|
+
: need(all.nth?.bind(all), 'an element by which of several', 'engine')(target.nth);
|
|
103
|
+
}
|
|
104
|
+
/**
|
|
105
|
+
* The element a recorded action or expectation works on. When the target
|
|
106
|
+
* matches several now (IFS Cloud shows a second New in a panel that opened,
|
|
107
|
+
* say), the first is taken, as a hand-written test's `.first()` does, and the
|
|
108
|
+
* run says so: the step's own expectations catch it when that was wrong.
|
|
109
|
+
*/
|
|
110
|
+
async function element(target, screen, browser) {
|
|
111
|
+
const found = locate(target, screen, browser);
|
|
112
|
+
if (target.nth !== undefined || !found.count || !found.first)
|
|
113
|
+
return found;
|
|
114
|
+
const count = await found.count();
|
|
115
|
+
if (count <= 1)
|
|
116
|
+
return found;
|
|
117
|
+
console.warn(`${describe(target)} matches ${count} elements; the first is used`);
|
|
118
|
+
return found.first();
|
|
119
|
+
}
|
|
120
|
+
/** A target as a run's warning names it: `button "New"`. */
|
|
121
|
+
function describe(target) {
|
|
122
|
+
const { role, name, nameStarts, label, testId, placeholder, id, text, dialog } = target;
|
|
123
|
+
const what = role
|
|
124
|
+
? `${role} ${JSON.stringify(name ?? `${nameStarts}…`)}`
|
|
125
|
+
: label !== undefined
|
|
126
|
+
? `the field labelled ${JSON.stringify(label)}`
|
|
127
|
+
: testId !== undefined
|
|
128
|
+
? `test id ${JSON.stringify(testId)}`
|
|
129
|
+
: placeholder !== undefined
|
|
130
|
+
? `placeholder ${JSON.stringify(placeholder)}`
|
|
131
|
+
: id !== undefined
|
|
132
|
+
? `#${id}`
|
|
133
|
+
: `text ${JSON.stringify(text)}`;
|
|
134
|
+
return dialog ? `${what} in dialog ${JSON.stringify(dialog)}` : what;
|
|
135
|
+
}
|
|
136
|
+
function matching(target, screen, browser) {
|
|
94
137
|
const frame = target.frame ? need(browser, 'an element in a frame').frameLocator(target.frame) : undefined;
|
|
95
138
|
if (target.id !== undefined)
|
|
96
139
|
return (frame ?? need(browser, 'an element by its id')).locator(`#${target.id}`);
|
|
@@ -112,6 +155,8 @@ export function locate(target, screen, browser) {
|
|
|
112
155
|
return scope.getByPlaceholder(target.placeholder);
|
|
113
156
|
return scope.getByText(target.text ?? '');
|
|
114
157
|
}
|
|
158
|
+
/** The engine's error for a locator that matched several elements where it needs one. */
|
|
159
|
+
const AMBIGUOUS = /LOCATOR_AMBIGUOUS|matched \d+ (?:nodes|elements), expected exactly one/;
|
|
115
160
|
/** How long one recorded action waits for its element before the step falls back to its sentence. */
|
|
116
161
|
export const ACTION_TIMEOUT = 15_000;
|
|
117
162
|
/** Does one recorded action, its value with the run's values in place of `{…}` (`value`). */
|
|
@@ -119,24 +164,41 @@ export async function perform(action, screen, browser, value, app) {
|
|
|
119
164
|
if ('open' in action)
|
|
120
165
|
return void (await need(app, 'opening a page', 'app').open(action.open));
|
|
121
166
|
const timeout = { timeout: ACTION_TIMEOUT };
|
|
167
|
+
/**
|
|
168
|
+
* Does `act` on the target's element. One more of it may show between
|
|
169
|
+
* counting them and acting (a panel opening): then it is done once more,
|
|
170
|
+
* on the first, as when there were several to begin with.
|
|
171
|
+
*/
|
|
172
|
+
const on = async (target, act) => {
|
|
173
|
+
const found = await element(target, screen, browser);
|
|
174
|
+
try {
|
|
175
|
+
await act(found);
|
|
176
|
+
}
|
|
177
|
+
catch (error) {
|
|
178
|
+
const all = locate(target, screen, browser);
|
|
179
|
+
if (target.nth !== undefined || !all.first || !AMBIGUOUS.test(String(error?.message ?? error))) {
|
|
180
|
+
throw error;
|
|
181
|
+
}
|
|
182
|
+
console.warn(`${describe(target)} matched several elements as it was done; the first is used`);
|
|
183
|
+
await act(all.first());
|
|
184
|
+
}
|
|
185
|
+
};
|
|
122
186
|
if ('tap' in action)
|
|
123
|
-
return
|
|
187
|
+
return on(action.tap, (e) => e.tap(timeout));
|
|
124
188
|
if ('doubleTap' in action)
|
|
125
|
-
return
|
|
189
|
+
return on(action.doubleTap, (e) => e.doubleTap(timeout));
|
|
126
190
|
if ('fill' in action)
|
|
127
|
-
return
|
|
128
|
-
if ('type' in action)
|
|
129
|
-
return
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
return void (await locate(action.select, screen, browser).selectOption(value(action.value), timeout));
|
|
133
|
-
}
|
|
191
|
+
return on(action.fill, (e) => e.fill(value(action.value), timeout));
|
|
192
|
+
if ('type' in action)
|
|
193
|
+
return on(action.type, (e) => e.pressSequentially(value(action.value), timeout));
|
|
194
|
+
if ('select' in action)
|
|
195
|
+
return on(action.select, (e) => e.selectOption(value(action.value), timeout));
|
|
134
196
|
if ('check' in action)
|
|
135
|
-
return
|
|
197
|
+
return on(action.check, (e) => e.check(timeout));
|
|
136
198
|
if ('uncheck' in action)
|
|
137
|
-
return
|
|
199
|
+
return on(action.uncheck, (e) => e.uncheck(timeout));
|
|
138
200
|
if ('press' in action)
|
|
139
|
-
return
|
|
201
|
+
return on(action.press, (e) => e.press(action.key, timeout));
|
|
140
202
|
await need(browser, 'a key on whatever has focus').keyboard.press(action.key);
|
|
141
203
|
}
|
|
142
204
|
function need(value, what, fixture = 'browser') {
|
|
@@ -177,16 +239,18 @@ export const EXPECT_TIMEOUT = 15_000;
|
|
|
177
239
|
*/
|
|
178
240
|
export async function expectOn(expectation, screen, browser, value, expect) {
|
|
179
241
|
const timeout = { timeout: EXPECT_TIMEOUT };
|
|
180
|
-
const
|
|
242
|
+
const found = locate(expectation.target, screen, browser);
|
|
181
243
|
try {
|
|
182
|
-
await expect(
|
|
244
|
+
await expect(found.first && expectation.target.nth === undefined ? found.first() : found).toBeVisible(timeout);
|
|
183
245
|
}
|
|
184
246
|
catch {
|
|
185
247
|
return 'missing';
|
|
186
248
|
}
|
|
249
|
+
// Shown now: when several match, the first is the one checked, as an action takes it.
|
|
250
|
+
const shown = await element(expectation.target, screen, browser);
|
|
187
251
|
if (expectation.matcher === 'toBeVisible')
|
|
188
252
|
return 'held';
|
|
189
|
-
await expect(
|
|
253
|
+
await expect(shown)[expectation.matcher](value(expectation.value), timeout);
|
|
190
254
|
return 'held';
|
|
191
255
|
}
|
|
192
256
|
function isObject(value) {
|
package/dist/plain.d.ts
CHANGED
|
@@ -100,7 +100,12 @@ export type PlainStep = {
|
|
|
100
100
|
readonly text: string;
|
|
101
101
|
/** For a Do step recorded in e2e Studio: what it did, on the exact elements; the sentence is the fallback. */
|
|
102
102
|
readonly actions?: readonly StepAction[];
|
|
103
|
-
/**
|
|
103
|
+
/**
|
|
104
|
+
* For a Check: what it expects of exact elements, checked with `expect`;
|
|
105
|
+
* the sentence is the fallback. For a Do step with actions (kit 0.4.0):
|
|
106
|
+
* what shows when it is done, waited for after the actions, so the next
|
|
107
|
+
* step does not start on a page still busy (a lookup resolving, a save).
|
|
108
|
+
*/
|
|
104
109
|
readonly expect?: readonly CheckExpectation[];
|
|
105
110
|
readonly when?: Condition;
|
|
106
111
|
} | {
|
package/dist/plain.js
CHANGED
|
@@ -154,7 +154,7 @@ export function parsePlainTest(json, context, options = {}) {
|
|
|
154
154
|
: kind === 'verify'
|
|
155
155
|
? [kind, 'with', 'when']
|
|
156
156
|
: kind === 'do'
|
|
157
|
-
? [kind, 'actions', 'when']
|
|
157
|
+
? [kind, 'actions', 'expect', 'when']
|
|
158
158
|
: kind === 'check'
|
|
159
159
|
? [kind, 'expect', 'when']
|
|
160
160
|
: [kind, 'when'];
|
|
@@ -182,6 +182,9 @@ export function parsePlainTest(json, context, options = {}) {
|
|
|
182
182
|
});
|
|
183
183
|
}
|
|
184
184
|
const expected = raw.expect;
|
|
185
|
+
if (expected !== undefined && kind === 'do' && actions === undefined) {
|
|
186
|
+
throw fail(where, '"expect" on a Do step is what shows when its actions are done: it needs "actions"');
|
|
187
|
+
}
|
|
185
188
|
if (expected !== undefined) {
|
|
186
189
|
if (!Array.isArray(expected) || expected.length === 0 || expected.length > 10)
|
|
187
190
|
throw fail(where, '"expect" must list from 1 to 10 expectations');
|
|
@@ -327,15 +330,38 @@ export async function runSteps(fixtures, test, options = {}) {
|
|
|
327
330
|
});
|
|
328
331
|
// Recorded in e2e Studio: done on the exact elements, and by the agent from the sentence when one is not there.
|
|
329
332
|
if (step.actions && screen) {
|
|
333
|
+
let done = false;
|
|
330
334
|
try {
|
|
331
335
|
for (const action of step.actions)
|
|
332
336
|
await perform(action, screen, browser, text, app);
|
|
333
|
-
|
|
337
|
+
done = true;
|
|
334
338
|
}
|
|
335
339
|
catch (error) {
|
|
336
340
|
const why = error instanceof Error ? error.message.split('\n')[0] : String(error);
|
|
337
341
|
console.warn(`${test.file} step ${index + 1}: a recorded action failed (${why}); the agent does "${step.text}" instead`);
|
|
338
342
|
}
|
|
343
|
+
// Done when what it shows when done is there: waited for, so the next step starts on a settled page.
|
|
344
|
+
if (done && step.expect) {
|
|
345
|
+
for (const expectation of step.expect) {
|
|
346
|
+
let settled;
|
|
347
|
+
try {
|
|
348
|
+
settled = await expectOn(expectation, screen, browser, text, expect);
|
|
349
|
+
}
|
|
350
|
+
catch (error) {
|
|
351
|
+
const why = error instanceof Error ? error.message : String(error);
|
|
352
|
+
throw new Error(`${test.file} step ${index + 1}, do "${step.text}": after its actions, ${why}`, {
|
|
353
|
+
cause: error,
|
|
354
|
+
});
|
|
355
|
+
}
|
|
356
|
+
if (settled === 'missing') {
|
|
357
|
+
done = false;
|
|
358
|
+
console.warn(`${test.file} step ${index + 1}: what it shows when done is not there; the agent finishes "${step.text}"`);
|
|
359
|
+
break;
|
|
360
|
+
}
|
|
361
|
+
}
|
|
362
|
+
}
|
|
363
|
+
if (done)
|
|
364
|
+
continue;
|
|
339
365
|
}
|
|
340
366
|
const params = actParams(named, results);
|
|
341
367
|
await agent.act(instruction, Object.keys(params).length ? { params } : {});
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@testra-studio/kit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
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
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -70,7 +70,19 @@
|
|
|
70
70
|
"$ref": "#/$defs/action"
|
|
71
71
|
},
|
|
72
72
|
"description": "For a Do step recorded in e2e Studio: what it did, on the exact elements. The sentence is what the agent does when one of them is not found. Needs @testra-studio/kit 0.2.0 or later."
|
|
73
|
+
},
|
|
74
|
+
"expect": {
|
|
75
|
+
"type": "array",
|
|
76
|
+
"minItems": 1,
|
|
77
|
+
"maxItems": 10,
|
|
78
|
+
"items": {
|
|
79
|
+
"$ref": "#/$defs/expectation"
|
|
80
|
+
},
|
|
81
|
+
"description": "For a Do step with actions: what shows when it is done, waited for after the actions, so the next step does not start on a page still busy. Shown otherwise fails the step; not there, the agent finishes the step from its sentence. Needs @testra-studio/kit 0.4.0 or later."
|
|
73
82
|
}
|
|
83
|
+
},
|
|
84
|
+
"dependentRequired": {
|
|
85
|
+
"expect": ["actions"]
|
|
74
86
|
}
|
|
75
87
|
},
|
|
76
88
|
{
|
|
@@ -151,7 +163,7 @@
|
|
|
151
163
|
},
|
|
152
164
|
"target": {
|
|
153
165
|
"type": "object",
|
|
154
|
-
"description": "An element, as the web engine finds it: a role with its name (or how a long name starts), else a label (kit 0.3.0), a test id, a placeholder, an id or a text; inside a frame, a dialog and a grid row when it was in one.",
|
|
166
|
+
"description": "An element, as the web engine finds it: a role with its name (or how a long name starts), else a label (kit 0.3.0), a test id, a placeholder, an id or a text; inside a frame, a dialog and a grid row when it was in one; and which of several, when it was one of them (kit 0.4.0).",
|
|
155
167
|
"additionalProperties": false,
|
|
156
168
|
"properties": {
|
|
157
169
|
"role": {
|
|
@@ -198,6 +210,12 @@
|
|
|
198
210
|
"frame": {
|
|
199
211
|
"type": "string",
|
|
200
212
|
"minLength": 1
|
|
213
|
+
},
|
|
214
|
+
"nth": {
|
|
215
|
+
"type": "integer",
|
|
216
|
+
"minimum": 0,
|
|
217
|
+
"maximum": 99,
|
|
218
|
+
"description": "Which of several matching elements, from 0, as .first() or .nth(n) found it. Needs @testra-studio/kit 0.4.0 or later."
|
|
201
219
|
}
|
|
202
220
|
},
|
|
203
221
|
"oneOf": [
|