@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 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
- if (Object.values(target).some((v) => typeof v !== 'string' || !v))
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 void (await locate(action.tap, screen, browser).tap(timeout));
187
+ return on(action.tap, (e) => e.tap(timeout));
124
188
  if ('doubleTap' in action)
125
- return void (await locate(action.doubleTap, screen, browser).doubleTap(timeout));
189
+ return on(action.doubleTap, (e) => e.doubleTap(timeout));
126
190
  if ('fill' in action)
127
- return void (await locate(action.fill, screen, browser).fill(value(action.value), timeout));
128
- if ('type' in action) {
129
- return void (await locate(action.type, screen, browser).pressSequentially(value(action.value), timeout));
130
- }
131
- if ('select' in action) {
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 void (await locate(action.check, screen, browser).check(timeout));
197
+ return on(action.check, (e) => e.check(timeout));
136
198
  if ('uncheck' in action)
137
- return void (await locate(action.uncheck, screen, browser).uncheck(timeout));
199
+ return on(action.uncheck, (e) => e.uncheck(timeout));
138
200
  if ('press' in action)
139
- return void (await locate(action.press, screen, browser).press(action.key, timeout));
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 element = locate(expectation.target, screen, browser);
242
+ const found = locate(expectation.target, screen, browser);
181
243
  try {
182
- await expect(element).toBeVisible(timeout);
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(element)[expectation.matcher](value(expectation.value), timeout);
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
- /** For a Check: what it expects of exact elements, checked with `expect`; the sentence is the fallback. */
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
- continue;
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.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": [