@testra-studio/kit 0.3.0 → 0.4.1

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,30 @@ 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.1
9
+
10
+ - A recorded Tab on a combobox waits until its list has closed before the
11
+ next action: a lookup checks its value with the app after Tab, and a Save
12
+ pressed meanwhile was lost. One still open after 10 s is warned of, and
13
+ the run goes on.
14
+
15
+ What a project does: nothing.
16
+
17
+ ## 0.4.0
18
+
19
+ - A Do step with actions may say what shows when it is done, in a Check's
20
+ `expect` form: `runSteps()` waits for it after the actions, so the next
21
+ step does not start on a page still busy (a lookup resolving after Tab, a
22
+ save). Showing something else fails the step; not there, the agent
23
+ finishes the step from its sentence.
24
+ - An element may say which of several it is, from 0: `"nth": 1`. An element
25
+ without one that matches several when a step runs (or as it is done) is
26
+ the first of them, as a hand-written test's `.first()` takes it, and the
27
+ run warns. Before, such a step fell back to the agent.
28
+ - The steps schema has both.
29
+
30
+ What a project does: nothing. Steps files without these run as they did.
31
+
8
32
  ## 0.3.0
9
33
 
10
34
  - 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,12 +123,22 @@ 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;
124
- /** Does one recorded action, its value with the run's values in place of `{…}` (`value`). */
125
- export declare function perform(action: StepAction, screen: ScreenLike, browser: BrowserLike | undefined, value: (text: string) => string, app?: AppLike): Promise<void>;
130
+ /** How long a combobox left with Tab is waited for to check its value, before the run goes on and says so. */
131
+ export declare const LOOKUP_TIMEOUT = 10000;
132
+ /**
133
+ * Does one recorded action, its value with the run's values in place of `{…}` (`value`).
134
+ *
135
+ * A combobox left with Tab checks its value with the app (a lookup: its list
136
+ * stays open until the value is found), and what is pressed meanwhile may be
137
+ * lost, as a Save is. So with the framework's `expect`, Tab on a combobox
138
+ * waits until its list has closed; one still open after `LOOKUP_TIMEOUT` is
139
+ * said, and the run goes on. Kit 0.4.1.
140
+ */
141
+ export declare function perform(action: StepAction, screen: ScreenLike, browser: BrowserLike | undefined, value: (text: string) => string, app?: AppLike, expect?: ExpectLike): Promise<void>;
126
142
  /** The matchers an expectation may use, as the framework's `expect` names them. */
127
143
  export declare const MATCHERS: readonly ['toBeVisible', 'toHaveText', 'toContainText', 'toHaveValue'];
128
144
  /**
@@ -155,6 +171,12 @@ export type ExpectLike = (locator: LocatorLike) => {
155
171
  toHaveValue(value: string, options?: {
156
172
  timeout?: number;
157
173
  }): Promise<unknown>;
174
+ /** Where the framework has it: what says a combobox left with Tab has closed its list. Kit 0.4.1. */
175
+ readonly not?: {
176
+ toBeExpanded?(options?: {
177
+ timeout?: number;
178
+ }): Promise<unknown>;
179
+ };
158
180
  };
159
181
  /** Why `value` is no expectation, or nothing when it is one. */
160
182
  export declare function expectationProblem(value: unknown): string | undefined;
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,33 +155,78 @@ 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
- /** Does one recorded action, its value with the run's values in place of `{…}` (`value`). */
118
- export async function perform(action, screen, browser, value, app) {
162
+ /** How long a combobox left with Tab is waited for to check its value, before the run goes on and says so. */
163
+ export const LOOKUP_TIMEOUT = 10_000;
164
+ /**
165
+ * Does one recorded action, its value with the run's values in place of `{…}` (`value`).
166
+ *
167
+ * A combobox left with Tab checks its value with the app (a lookup: its list
168
+ * stays open until the value is found), and what is pressed meanwhile may be
169
+ * lost, as a Save is. So with the framework's `expect`, Tab on a combobox
170
+ * waits until its list has closed; one still open after `LOOKUP_TIMEOUT` is
171
+ * said, and the run goes on. Kit 0.4.1.
172
+ */
173
+ export async function perform(action, screen, browser, value, app, expect) {
119
174
  if ('open' in action)
120
175
  return void (await need(app, 'opening a page', 'app').open(action.open));
121
176
  const timeout = { timeout: ACTION_TIMEOUT };
177
+ /**
178
+ * Does `act` on the target's element. One more of it may show between
179
+ * counting them and acting (a panel opening): then it is done once more,
180
+ * on the first, as when there were several to begin with.
181
+ */
182
+ const on = async (target, act) => {
183
+ const found = await element(target, screen, browser);
184
+ try {
185
+ await act(found);
186
+ }
187
+ catch (error) {
188
+ const all = locate(target, screen, browser);
189
+ if (target.nth !== undefined || !all.first || !AMBIGUOUS.test(String(error?.message ?? error))) {
190
+ throw error;
191
+ }
192
+ console.warn(`${describe(target)} matched several elements as it was done; the first is used`);
193
+ await act(all.first());
194
+ }
195
+ };
122
196
  if ('tap' in action)
123
- return void (await locate(action.tap, screen, browser).tap(timeout));
197
+ return on(action.tap, (e) => e.tap(timeout));
124
198
  if ('doubleTap' in action)
125
- return void (await locate(action.doubleTap, screen, browser).doubleTap(timeout));
199
+ return on(action.doubleTap, (e) => e.doubleTap(timeout));
126
200
  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
- }
201
+ return on(action.fill, (e) => e.fill(value(action.value), timeout));
202
+ if ('type' in action)
203
+ return on(action.type, (e) => e.pressSequentially(value(action.value), timeout));
204
+ if ('select' in action)
205
+ return on(action.select, (e) => e.selectOption(value(action.value), timeout));
134
206
  if ('check' in action)
135
- return void (await locate(action.check, screen, browser).check(timeout));
207
+ return on(action.check, (e) => e.check(timeout));
136
208
  if ('uncheck' in action)
137
- return void (await locate(action.uncheck, screen, browser).uncheck(timeout));
138
- if ('press' in action)
139
- return void (await locate(action.press, screen, browser).press(action.key, timeout));
209
+ return on(action.uncheck, (e) => e.uncheck(timeout));
210
+ if ('press' in action) {
211
+ await on(action.press, (e) => e.press(action.key, timeout));
212
+ if (action.key === 'Tab' && action.press.role === 'combobox')
213
+ await closed(action.press, screen, browser, expect);
214
+ return;
215
+ }
140
216
  await need(browser, 'a key on whatever has focus').keyboard.press(action.key);
141
217
  }
218
+ /** Waits until a combobox left with Tab has closed its list: its value is checked. Never fails the action. */
219
+ async function closed(target, screen, browser, expect) {
220
+ if (!expect)
221
+ return;
222
+ try {
223
+ const found = await element(target, screen, browser);
224
+ await expect(found).not?.toBeExpanded?.({ timeout: LOOKUP_TIMEOUT });
225
+ }
226
+ catch {
227
+ console.warn(`${describe(target)} still has its list open ${LOOKUP_TIMEOUT / 1000} s after Tab; the run goes on without waiting for it`);
228
+ }
229
+ }
142
230
  function need(value, what, fixture = 'browser') {
143
231
  if (value === undefined)
144
232
  throw new Error(`${what} needs the ${fixture} fixture, which the runner did not pass`);
@@ -177,16 +265,18 @@ export const EXPECT_TIMEOUT = 15_000;
177
265
  */
178
266
  export async function expectOn(expectation, screen, browser, value, expect) {
179
267
  const timeout = { timeout: EXPECT_TIMEOUT };
180
- const element = locate(expectation.target, screen, browser);
268
+ const found = locate(expectation.target, screen, browser);
181
269
  try {
182
- await expect(element).toBeVisible(timeout);
270
+ await expect(found.first && expectation.target.nth === undefined ? found.first() : found).toBeVisible(timeout);
183
271
  }
184
272
  catch {
185
273
  return 'missing';
186
274
  }
275
+ // Shown now: when several match, the first is the one checked, as an action takes it.
276
+ const shown = await element(expectation.target, screen, browser);
187
277
  if (expectation.matcher === 'toBeVisible')
188
278
  return 'held';
189
- await expect(element)[expectation.matcher](value(expectation.value), timeout);
279
+ await expect(shown)[expectation.matcher](value(expectation.value), timeout);
190
280
  return 'held';
191
281
  }
192
282
  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
- await perform(action, screen, browser, text, app);
333
- continue;
336
+ await perform(action, screen, browser, text, app, expect);
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.1",
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": [