@testra-studio/kit 0.2.1 → 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,42 @@ 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
+
23
+ ## 0.3.0
24
+
25
+ - A Do step's actions may open a page by its address in the app:
26
+ `{ "open": "page/WorkTasks/List" }`, a path of the app or an http(s) URL
27
+ on it (never another scheme). `runSteps()` opens it with the `app` fixture.
28
+ - An element may be found by its label: `{ "label": "Status" }`, as
29
+ `getByLabel` finds a field.
30
+ - A Check may carry exact expectations on elements, checked with the
31
+ framework's `expect` instead of the agent judging its sentence:
32
+ `"expect": [{ "target": { "label": "Status" }, "matcher": "toHaveValue",
33
+ "value": "Released" }]`, with `toBeVisible`, `toHaveText`, `toContainText`
34
+ or `toHaveValue`. An element showing something else fails the check; one
35
+ not there (the screen changed) makes the agent judge the sentence, as a Do
36
+ step's missing element does.
37
+ - The steps schema has all three.
38
+
39
+ What a project does: pass `app` as well to `runSteps()` in a web project's
40
+ `support/plain.ts` (`{ agent, screen, browser, app }`). Without it, a step
41
+ that opens a page is the agent's, from its sentence. Steps files without
42
+ these run as they did.
43
+
8
44
  ## 0.2.1
9
45
 
10
46
  - Works with the e2e framework 0.22 and 0.23 (and `@e2e-dev/mobile` 0.12.6)
package/README.md CHANGED
@@ -57,8 +57,8 @@ export function plainTest(testFile: string): void {
57
57
  const missing = missingFeatures(plain, options);
58
58
  test(plain.title, missing.length ? { skip: `lacks ${missing.join(', ')}` } : {}, async ({ app, agent, screen, browser }) => {
59
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);
60
+ // screen, browser and app let recorded steps run on their exact elements; a mobile project passes the agent alone.
61
+ await runSteps({ agent, screen, browser, app }, plain, options);
62
62
  });
63
63
  }
64
64
  ```
@@ -92,8 +92,59 @@ A Do step recorded in e2e Studio keeps what it did, on the exact elements:
92
92
  seconds (the screen changed since it was recorded), the step falls back to
93
93
  the agent and its sentence, and the run log says which step did. An element
94
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.
95
+ `label`, `testId`, `placeholder`, `id` or `text`, with the `frame`, `dialog`
96
+ and `row` it is in.
97
+
98
+ An action may also open a page by its address in the app, through the `app`
99
+ fixture: `{ "open": "page/WorkTasks/List" }` (kit 0.3.0, as is `label`).
100
+
101
+ ### Exact checks
102
+
103
+ A Check may say what it expects of exact elements (kit 0.3.0), which
104
+ `runSteps()` checks with the framework's `expect` instead of asking the
105
+ agent:
106
+
107
+ ```json
108
+ {
109
+ "check": "The request's status is Released",
110
+ "expect": [
111
+ { "target": { "role": "heading", "name": "Request" }, "matcher": "toBeVisible" },
112
+ { "target": { "label": "Status" }, "matcher": "toHaveValue", "value": "Released" }
113
+ ]
114
+ }
115
+ ```
116
+
117
+ The matchers are `toBeVisible`, `toHaveText`, `toContainText` and
118
+ `toHaveValue`; a value may hold `{…}` tokens. An element that shows
119
+ something else fails the check, with the framework's message. An element
120
+ that is not there within 15 seconds (the screen changed) makes the agent
121
+ judge the sentence instead, as for a Do step.
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.
97
148
 
98
149
  ## Basic data
99
150
 
package/dist/actions.d.ts CHANGED
@@ -7,11 +7,17 @@
7
7
  * { "do": "Search for pump", "actions": [
8
8
  * { "fill": { "role": "searchbox", "name": "Search" }, "value": "pump" },
9
9
  * { "press": { "role": "searchbox", "name": "Search" }, "key": "Enter" } ] }
10
+ *
11
+ * An action may also open a page by its address in the app (`open`), and a
12
+ * Check may carry exact expectations on elements (`CheckExpectation`), which
13
+ * a run checks with the framework's `expect` instead of asking the agent.
10
14
  */
11
15
  /** An element, as the web engine finds it: one way, inside its frame, dialog and row. */
12
16
  export interface StepTarget {
13
17
  readonly role?: string;
14
18
  readonly name?: string;
19
+ /** A field by its label, as `getByLabel` finds it. Kit 0.3.0. */
20
+ readonly label?: string;
15
21
  /** How a long name starts. */
16
22
  readonly nameStarts?: string;
17
23
  readonly testId?: string;
@@ -22,6 +28,8 @@ export interface StepTarget {
22
28
  readonly row?: string;
23
29
  /** The iframe it is in, as a CSS selector. */
24
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;
25
33
  }
26
34
  export type StepAction = {
27
35
  readonly tap: StepTarget;
@@ -45,7 +53,15 @@ export type StepAction = {
45
53
  readonly key: string;
46
54
  } | {
47
55
  readonly key: string;
56
+ }
57
+ /** Opens a page by its address: a path of the app, such as `page/WorkTasks/List`, or a whole URL on it. Kit 0.3.0. */
58
+ | {
59
+ readonly open: string;
48
60
  };
61
+ /** The app, as a test gets it: for an `open` action. */
62
+ export interface AppLike {
63
+ open(path?: string): Promise<unknown>;
64
+ }
49
65
  /** The parts of the web engine's locator the actions use. */
50
66
  export interface LocatorLike {
51
67
  tap(options?: {
@@ -72,10 +88,15 @@ export interface LocatorLike {
72
88
  press(key: string, options?: {
73
89
  timeout?: number;
74
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;
75
95
  getByRole(role: never, name?: string | RegExp): LocatorLike;
76
96
  getByTestId(id: string): LocatorLike;
77
97
  getByPlaceholder(text: string): LocatorLike;
78
98
  getByText(text: string): LocatorLike;
99
+ getByLabel(text: string): LocatorLike;
79
100
  filter(options: {
80
101
  hasText: string;
81
102
  }): LocatorLike;
@@ -86,6 +107,7 @@ export interface ScreenLike {
86
107
  getByTestId(id: string): LocatorLike;
87
108
  getByPlaceholder(text: string): LocatorLike;
88
109
  getByText(text: string): LocatorLike;
110
+ getByLabel(text: string): LocatorLike;
89
111
  }
90
112
  /** The web engine's `browser`, for an id, a frame and a key on whatever has focus. */
91
113
  export interface BrowserLike {
@@ -101,9 +123,53 @@ export interface BrowserLike {
101
123
  export declare function actionProblem(value: unknown): string | undefined;
102
124
  /** The values an action types, fills or chooses, for its `{…}` tokens. */
103
125
  export declare function actionValue(action: StepAction): string | undefined;
104
- /** 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. */
105
127
  export declare function locate(target: StepTarget, screen: ScreenLike, browser: BrowserLike | undefined): LocatorLike;
106
128
  /** How long one recorded action waits for its element before the step falls back to its sentence. */
107
129
  export declare const ACTION_TIMEOUT = 15000;
108
130
  /** 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>;
131
+ export declare function perform(action: StepAction, screen: ScreenLike, browser: BrowserLike | undefined, value: (text: string) => string, app?: AppLike): Promise<void>;
132
+ /** The matchers an expectation may use, as the framework's `expect` names them. */
133
+ export declare const MATCHERS: readonly ['toBeVisible', 'toHaveText', 'toContainText', 'toHaveValue'];
134
+ /**
135
+ * What a Check expects of one element, checked with the framework's
136
+ * `expect`: shown, or showing a text or a value (its `{…}` tokens are the
137
+ * run's values). Kit 0.3.0.
138
+ *
139
+ * { "check": "The request's status is Released", "expect": [
140
+ * { "target": { "label": "Status" }, "matcher": "toHaveValue", "value": "Released" } ] }
141
+ */
142
+ export type CheckExpectation = {
143
+ readonly target: StepTarget;
144
+ readonly matcher: 'toBeVisible';
145
+ } | {
146
+ readonly target: StepTarget;
147
+ readonly matcher: 'toHaveText' | 'toContainText' | 'toHaveValue';
148
+ readonly value: string;
149
+ };
150
+ /** The framework's `expect`, in the matchers an expectation uses. */
151
+ export type ExpectLike = (locator: LocatorLike) => {
152
+ toBeVisible(options?: {
153
+ timeout?: number;
154
+ }): Promise<unknown>;
155
+ toHaveText(value: string, options?: {
156
+ timeout?: number;
157
+ }): Promise<unknown>;
158
+ toContainText(value: string, options?: {
159
+ timeout?: number;
160
+ }): Promise<unknown>;
161
+ toHaveValue(value: string, options?: {
162
+ timeout?: number;
163
+ }): Promise<unknown>;
164
+ };
165
+ /** Why `value` is no expectation, or nothing when it is one. */
166
+ export declare function expectationProblem(value: unknown): string | undefined;
167
+ /** How long an expectation waits for its element to show before the check falls back to its sentence. */
168
+ export declare const EXPECT_TIMEOUT = 15000;
169
+ /**
170
+ * Checks one expectation. The element not showing is `missing`: the screen
171
+ * changed, so the check falls back to the agent judging its sentence, as a
172
+ * Do step's missing element does. The element showing something else fails,
173
+ * with the framework's message: that is what the test is there to catch.
174
+ */
175
+ export declare function expectOn(expectation: CheckExpectation, screen: ScreenLike, browser: BrowserLike | undefined, value: (text: string) => string, expect: ExpectLike): Promise<'held' | 'missing'>;
package/dist/actions.js CHANGED
@@ -7,14 +7,42 @@
7
7
  * { "do": "Search for pump", "actions": [
8
8
  * { "fill": { "role": "searchbox", "name": "Search" }, "value": "pump" },
9
9
  * { "press": { "role": "searchbox", "name": "Search" }, "key": "Enter" } ] }
10
+ *
11
+ * An action may also open a page by its address in the app (`open`), and a
12
+ * Check may carry exact expectations on elements (`CheckExpectation`), which
13
+ * a run checks with the framework's `expect` instead of asking the agent.
10
14
  */
11
- const TARGET_KEYS = ['role', 'name', 'nameStarts', 'testId', 'placeholder', 'id', 'text', 'dialog', 'row', 'frame'];
15
+ const TARGET_KEYS = [
16
+ 'role',
17
+ 'name',
18
+ 'nameStarts',
19
+ 'label',
20
+ 'testId',
21
+ 'placeholder',
22
+ 'id',
23
+ 'text',
24
+ 'dialog',
25
+ 'row',
26
+ 'frame',
27
+ 'nth',
28
+ ];
12
29
  const WITH_VALUE = ['fill', 'type', 'select'];
13
30
  const ON_TARGET = ['tap', 'doubleTap', 'check', 'uncheck'];
31
+ /** An address an `open` action takes: an http(s) URL, or a path of the app that names no other scheme (`javascript:`, `file:`). */
32
+ const ADDRESS = /^(?:https?:\/\/\S+|(?![A-Za-z][A-Za-z0-9+.-]*:)\S+)$/;
14
33
  /** Why `value` is no recorded action, or nothing when it is one. */
15
34
  export function actionProblem(value) {
16
35
  if (!isObject(value))
17
36
  return 'an action is an object such as { "tap": { "role": "button", "name": "Save" } }';
37
+ if ('open' in value) {
38
+ if (Object.keys(value).length !== 1)
39
+ return 'open: an action opens one address, with nothing beside it';
40
+ const address = value.open;
41
+ if (typeof address !== 'string' || !address || address.length > 500 || !ADDRESS.test(address)) {
42
+ return 'open needs the address of a page of the app, such as "page/WorkTasks/List"';
43
+ }
44
+ return undefined;
45
+ }
18
46
  const keys = Object.keys(value);
19
47
  const kind = keys.find((k) => [...ON_TARGET, ...WITH_VALUE, 'press'].includes(k)) ?? (keys.includes('key') ? 'key' : '');
20
48
  const allowed = WITH_VALUE.includes(kind)
@@ -23,7 +51,7 @@ export function actionProblem(value) {
23
51
  ? ['press', 'key']
24
52
  : [kind];
25
53
  if (!kind)
26
- return `${JSON.stringify(value)} is no action: tap, doubleTap, fill, type, select, check, uncheck, press or key`;
54
+ return `${JSON.stringify(value)} is no action: tap, doubleTap, fill, type, select, check, uncheck, press, key or open`;
27
55
  const extra = keys.filter((k) => !allowed.includes(k));
28
56
  if (extra.length)
29
57
  return `${kind}: unknown key ${extra.join(', ')}`;
@@ -43,17 +71,22 @@ function targetProblem(target) {
43
71
  const extra = Object.keys(target).filter((k) => !TARGET_KEYS.includes(k));
44
72
  if (extra.length)
45
73
  return `an element has no ${extra.join(', ')}`;
46
- 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))
47
79
  return "an element's values are text";
48
80
  const ways = [
49
81
  target.role !== undefined && (target.name !== undefined) !== (target.nameStarts !== undefined),
82
+ target.label !== undefined,
50
83
  target.testId !== undefined,
51
84
  target.placeholder !== undefined,
52
85
  target.id !== undefined,
53
86
  target.text !== undefined,
54
87
  ].filter(Boolean).length;
55
88
  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';
89
+ return 'an element is found one way: a role with a name (or how it starts), a label, a test id, a placeholder, an id or a text';
57
90
  }
58
91
  return undefined;
59
92
  }
@@ -61,8 +94,46 @@ function targetProblem(target) {
61
94
  export function actionValue(action) {
62
95
  return 'value' in action ? action.value : undefined;
63
96
  }
64
- /** 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. */
65
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) {
66
137
  const frame = target.frame ? need(browser, 'an element in a frame').frameLocator(target.frame) : undefined;
67
138
  if (target.id !== undefined)
68
139
  return (frame ?? need(browser, 'an element by its id')).locator(`#${target.id}`);
@@ -76,42 +147,112 @@ export function locate(target, screen, browser) {
76
147
  if (target.role && target.nameStarts !== undefined) {
77
148
  return scope.getByRole(target.role, new RegExp(`^${target.nameStarts.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`));
78
149
  }
150
+ if (target.label !== undefined)
151
+ return scope.getByLabel(target.label);
79
152
  if (target.testId !== undefined)
80
153
  return scope.getByTestId(target.testId);
81
154
  if (target.placeholder !== undefined)
82
155
  return scope.getByPlaceholder(target.placeholder);
83
156
  return scope.getByText(target.text ?? '');
84
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/;
85
160
  /** How long one recorded action waits for its element before the step falls back to its sentence. */
86
161
  export const ACTION_TIMEOUT = 15_000;
87
162
  /** Does one recorded action, its value with the run's values in place of `{…}` (`value`). */
88
- export async function perform(action, screen, browser, value) {
163
+ export async function perform(action, screen, browser, value, app) {
164
+ if ('open' in action)
165
+ return void (await need(app, 'opening a page', 'app').open(action.open));
89
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
+ };
90
186
  if ('tap' in action)
91
- return void (await locate(action.tap, screen, browser).tap(timeout));
187
+ return on(action.tap, (e) => e.tap(timeout));
92
188
  if ('doubleTap' in action)
93
- return void (await locate(action.doubleTap, screen, browser).doubleTap(timeout));
189
+ return on(action.doubleTap, (e) => e.doubleTap(timeout));
94
190
  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
- }
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));
102
196
  if ('check' in action)
103
- return void (await locate(action.check, screen, browser).check(timeout));
197
+ return on(action.check, (e) => e.check(timeout));
104
198
  if ('uncheck' in action)
105
- return void (await locate(action.uncheck, screen, browser).uncheck(timeout));
199
+ return on(action.uncheck, (e) => e.uncheck(timeout));
106
200
  if ('press' in action)
107
- return void (await locate(action.press, screen, browser).press(action.key, timeout));
201
+ return on(action.press, (e) => e.press(action.key, timeout));
108
202
  await need(browser, 'a key on whatever has focus').keyboard.press(action.key);
109
203
  }
110
- function need(value, what) {
204
+ function need(value, what, fixture = 'browser') {
111
205
  if (value === undefined)
112
- throw new Error(`${what} needs the browser fixture, which the runner did not pass`);
206
+ throw new Error(`${what} needs the ${fixture} fixture, which the runner did not pass`);
113
207
  return value;
114
208
  }
209
+ // ── Exact expectations on a Check ────────────────────────────────────────
210
+ /** The matchers an expectation may use, as the framework's `expect` names them. */
211
+ export const MATCHERS = ['toBeVisible', 'toHaveText', 'toContainText', 'toHaveValue'];
212
+ /** Why `value` is no expectation, or nothing when it is one. */
213
+ export function expectationProblem(value) {
214
+ if (!isObject(value))
215
+ return 'an expectation is an object such as { "target": {…}, "matcher": "toBeVisible" }';
216
+ const extra = Object.keys(value).filter((k) => !['target', 'matcher', 'value'].includes(k));
217
+ if (extra.length)
218
+ return `an expectation has no ${extra.join(', ')}`;
219
+ const matcher = value.matcher;
220
+ if (typeof matcher !== 'string' || !MATCHERS.includes(matcher)) {
221
+ return `"matcher" must be one of ${MATCHERS.join(', ')}`;
222
+ }
223
+ if (matcher === 'toBeVisible') {
224
+ if (value.value !== undefined)
225
+ return 'toBeVisible takes no "value"';
226
+ }
227
+ else if (typeof value.value !== 'string' || value.value.length > 500) {
228
+ return `${matcher} needs a "value" of up to 500 characters`;
229
+ }
230
+ return targetProblem(value.target);
231
+ }
232
+ /** How long an expectation waits for its element to show before the check falls back to its sentence. */
233
+ export const EXPECT_TIMEOUT = 15_000;
234
+ /**
235
+ * Checks one expectation. The element not showing is `missing`: the screen
236
+ * changed, so the check falls back to the agent judging its sentence, as a
237
+ * Do step's missing element does. The element showing something else fails,
238
+ * with the framework's message: that is what the test is there to catch.
239
+ */
240
+ export async function expectOn(expectation, screen, browser, value, expect) {
241
+ const timeout = { timeout: EXPECT_TIMEOUT };
242
+ const found = locate(expectation.target, screen, browser);
243
+ try {
244
+ await expect(found.first && expectation.target.nth === undefined ? found.first() : found).toBeVisible(timeout);
245
+ }
246
+ catch {
247
+ return 'missing';
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);
251
+ if (expectation.matcher === 'toBeVisible')
252
+ return 'held';
253
+ await expect(shown)[expectation.matcher](value(expectation.value), timeout);
254
+ return 'held';
255
+ }
115
256
  function isObject(value) {
116
257
  return typeof value === 'object' && value !== null && !Array.isArray(value);
117
258
  }
package/dist/index.d.ts CHANGED
@@ -9,7 +9,7 @@
9
9
  * - `readBasicData()`: an instance's basic data, as the Studio edits it.
10
10
  * - `schemas/`: the JSON Schemas of the files the Studio and a project share.
11
11
  */
12
- export { ACTION_TIMEOUT, type BrowserLike, type LocatorLike, locate, type ScreenLike, type StepAction, type StepTarget, } from './actions.ts';
12
+ export { ACTION_TIMEOUT, type AppLike, type BrowserLike, type CheckExpectation, EXPECT_TIMEOUT, type ExpectLike, type LocatorLike, locate, MATCHERS, type ScreenLike, type StepAction, type StepTarget, } from './actions.ts';
13
13
  export { BASIC_DATA_ITEMS_FILE, type BasicDataOptions, basicDataItems, type CodeAndName, readBasicData, SHARED_BASIC_DATA_FILE, } from './basic-data.ts';
14
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
15
  export { type ShellResult, STUDIO_BROWSER_ENV, STUDIO_DEVICE_ENV, type StudioDeviceLease, studioAdbShell, studioBrowser, studioDevice, studioLease, } from './studio.ts';
package/dist/index.js CHANGED
@@ -9,7 +9,7 @@
9
9
  * - `readBasicData()`: an instance's basic data, as the Studio edits it.
10
10
  * - `schemas/`: the JSON Schemas of the files the Studio and a project share.
11
11
  */
12
- export { ACTION_TIMEOUT, locate, } from './actions.js';
12
+ export { ACTION_TIMEOUT, EXPECT_TIMEOUT, locate, MATCHERS, } from './actions.js';
13
13
  export { BASIC_DATA_ITEMS_FILE, basicDataItems, readBasicData, SHARED_BASIC_DATA_FILE, } from './basic-data.js';
14
14
  export { BLOCKS_FILE, loadPlainTest, missingFeatures, parsePlainTest, readCatalog, runSteps, STEPS_FILE_SUFFIX, } from './plain.js';
15
15
  export { STUDIO_BROWSER_ENV, STUDIO_DEVICE_ENV, studioAdbShell, studioBrowser, studioDevice, studioLease, } from './studio.js';
package/dist/plain.d.ts CHANGED
@@ -51,7 +51,7 @@
51
51
  * }
52
52
  * ```
53
53
  */
54
- import { type BrowserLike, type ScreenLike, type StepAction } from './actions.ts';
54
+ import { type AppLike, type BrowserLike, type CheckExpectation, type ExpectLike, type ScreenLike, type StepAction } from './actions.ts';
55
55
  /** The agent the steps run on: the e2e framework's, as a test gets it. */
56
56
  export interface Agent {
57
57
  act(instruction: string, options?: {
@@ -71,6 +71,10 @@ export interface PlainFixtures {
71
71
  readonly agent: Agent;
72
72
  readonly screen?: ScreenLike;
73
73
  readonly browser?: BrowserLike;
74
+ /** The app, for an `open` action; without it, a step that opens a page is the agent's. Kit 0.3.0. */
75
+ readonly app?: AppLike;
76
+ /** The framework's `expect`, for a Check's expectations; e2e's own when left out. */
77
+ readonly expect?: ExpectLike;
74
78
  }
75
79
  /** What a project tells the runner about itself. */
76
80
  export interface PlainOptions {
@@ -96,6 +100,13 @@ export type PlainStep = {
96
100
  readonly text: string;
97
101
  /** For a Do step recorded in e2e Studio: what it did, on the exact elements; the sentence is the fallback. */
98
102
  readonly actions?: readonly StepAction[];
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
+ */
109
+ readonly expect?: readonly CheckExpectation[];
99
110
  readonly when?: Condition;
100
111
  } | {
101
112
  /** A building block, or a check. */
package/dist/plain.js CHANGED
@@ -62,8 +62,8 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
62
62
  import { existsSync, readFileSync } from 'node:fs';
63
63
  import path from 'node:path';
64
64
  import { fileURLToPath, pathToFileURL } from 'node:url';
65
- import { unique } from 'e2e';
66
- import { actionProblem, actionValue, perform } from './actions.js';
65
+ import { expect as e2eExpect, unique } from 'e2e';
66
+ import { actionProblem, actionValue, expectationProblem, expectOn, perform, } from './actions.js';
67
67
  export const STEPS_FILE_SUFFIX = '.steps.json';
68
68
  /** The app's building blocks, the catalog e2e Studio offers too. */
69
69
  export const BLOCKS_FILE = 'e2e-studio.blocks.json';
@@ -154,8 +154,10 @@ export function parsePlainTest(json, context, options = {}) {
154
154
  : kind === 'verify'
155
155
  ? [kind, 'with', 'when']
156
156
  : kind === 'do'
157
- ? [kind, 'actions', 'when']
158
- : [kind, 'when'];
157
+ ? [kind, 'actions', 'expect', 'when']
158
+ : kind === 'check'
159
+ ? [kind, 'expect', 'when']
160
+ : [kind, 'when'];
159
161
  const extra = Object.keys(raw).filter((k) => !allowed.includes(k));
160
162
  if (extra.length)
161
163
  throw fail(where, `unknown key ${extra.join(', ')}`);
@@ -179,10 +181,27 @@ export function parsePlainTest(json, context, options = {}) {
179
181
  checkTokens(`${where} action ${at + 1}`, typed, false);
180
182
  });
181
183
  }
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
+ }
188
+ if (expected !== undefined) {
189
+ if (!Array.isArray(expected) || expected.length === 0 || expected.length > 10)
190
+ throw fail(where, '"expect" must list from 1 to 10 expectations');
191
+ expected.forEach((expectation, at) => {
192
+ const problem = expectationProblem(expectation);
193
+ if (problem)
194
+ throw fail(`${where} expectation ${at + 1}`, problem);
195
+ const shown = expectation.value;
196
+ if (shown)
197
+ checkTokens(`${where} expectation ${at + 1}`, shown, false);
198
+ });
199
+ }
182
200
  return {
183
201
  kind,
184
202
  text: text.trim(),
185
203
  ...(actions !== undefined ? { actions: actions } : {}),
204
+ ...(expected !== undefined ? { expect: expected } : {}),
186
205
  ...(when ? { when } : {}),
187
206
  };
188
207
  }
@@ -255,7 +274,8 @@ export function missingFeatures(test, options = {}) {
255
274
  * and a `waitUntil`, judged anew on every run, get the values in their text.
256
275
  */
257
276
  export async function runSteps(fixtures, test, options = {}) {
258
- const { agent, screen, browser } = 'agent' in fixtures ? fixtures : { agent: fixtures, screen: undefined, browser: undefined };
277
+ const { agent, screen, browser, app } = 'agent' in fixtures ? fixtures : { agent: fixtures, screen: undefined, browser: undefined, app: undefined };
278
+ const expect = ('agent' in fixtures ? fixtures.expect : undefined) ?? e2eExpect;
259
279
  const results = new Map();
260
280
  const has = options.features?.has ?? (() => false);
261
281
  const lookUp = (token, name, value, field) => {
@@ -310,20 +330,61 @@ export async function runSteps(fixtures, test, options = {}) {
310
330
  });
311
331
  // Recorded in e2e Studio: done on the exact elements, and by the agent from the sentence when one is not there.
312
332
  if (step.actions && screen) {
333
+ let done = false;
313
334
  try {
314
335
  for (const action of step.actions)
315
- await perform(action, screen, browser, text);
316
- continue;
336
+ await perform(action, screen, browser, text, app);
337
+ done = true;
317
338
  }
318
339
  catch (error) {
319
340
  const why = error instanceof Error ? error.message.split('\n')[0] : String(error);
320
341
  console.warn(`${test.file} step ${index + 1}: a recorded action failed (${why}); the agent does "${step.text}" instead`);
321
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;
322
365
  }
323
366
  const params = actParams(named, results);
324
367
  await agent.act(instruction, Object.keys(params).length ? { params } : {});
325
368
  }
326
369
  else if (step.kind === 'check') {
370
+ // Exact expectations, checked with expect; an element that is not there means the screen changed, so the agent judges.
371
+ if (step.expect && screen) {
372
+ let missing = false;
373
+ for (const expectation of step.expect) {
374
+ try {
375
+ missing = (await expectOn(expectation, screen, browser, text, expect)) === 'missing';
376
+ }
377
+ catch (error) {
378
+ const why = error instanceof Error ? error.message : String(error);
379
+ throw new Error(`${test.file} step ${index + 1}, check "${step.text}": ${why}`, { cause: error });
380
+ }
381
+ if (missing)
382
+ break;
383
+ }
384
+ if (!missing)
385
+ continue;
386
+ console.warn(`${test.file} step ${index + 1}: an expected element is not there; the agent judges "${step.text}" instead`);
387
+ }
327
388
  await agent.assert(text(step.text), { screenshot: false });
328
389
  }
329
390
  else if (step.kind === 'waitUntil') {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@testra-studio/kit",
3
- "version": "0.2.1",
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
  {
@@ -83,6 +95,15 @@
83
95
  },
84
96
  "when": {
85
97
  "$ref": "#/$defs/when"
98
+ },
99
+ "expect": {
100
+ "type": "array",
101
+ "minItems": 1,
102
+ "maxItems": 10,
103
+ "items": {
104
+ "$ref": "#/$defs/expectation"
105
+ },
106
+ "description": "Exact expectations on elements, checked with expect, in place of the agent judging the sentence. An element that is not there makes the agent judge the sentence instead. Needs @testra-studio/kit 0.3.0 or later."
86
107
  }
87
108
  }
88
109
  },
@@ -142,7 +163,7 @@
142
163
  },
143
164
  "target": {
144
165
  "type": "object",
145
- "description": "An element, as the web engine finds it: a role with its name (or how a long name starts), else 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).",
146
167
  "additionalProperties": false,
147
168
  "properties": {
148
169
  "role": {
@@ -157,6 +178,11 @@
157
178
  "type": "string",
158
179
  "minLength": 1
159
180
  },
181
+ "label": {
182
+ "type": "string",
183
+ "minLength": 1,
184
+ "description": "A field by its label. Needs @testra-studio/kit 0.3.0 or later."
185
+ },
160
186
  "testId": {
161
187
  "type": "string",
162
188
  "minLength": 1
@@ -184,6 +210,12 @@
184
210
  "frame": {
185
211
  "type": "string",
186
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."
187
219
  }
188
220
  },
189
221
  "oneOf": [
@@ -194,6 +226,9 @@
194
226
  {
195
227
  "required": ["nameStarts"]
196
228
  },
229
+ {
230
+ "required": ["label"]
231
+ },
197
232
  {
198
233
  "required": ["testId"]
199
234
  },
@@ -216,6 +251,31 @@
216
251
  {
217
252
  "required": ["name"]
218
253
  },
254
+ {
255
+ "required": ["label"]
256
+ },
257
+ {
258
+ "required": ["testId"]
259
+ },
260
+ {
261
+ "required": ["placeholder"]
262
+ },
263
+ {
264
+ "required": ["id"]
265
+ },
266
+ {
267
+ "required": ["text"]
268
+ }
269
+ ]
270
+ }
271
+ },
272
+ {
273
+ "required": ["label"],
274
+ "not": {
275
+ "anyOf": [
276
+ {
277
+ "required": ["role"]
278
+ },
219
279
  {
220
280
  "required": ["testId"]
221
281
  },
@@ -238,6 +298,9 @@
238
298
  {
239
299
  "required": ["role"]
240
300
  },
301
+ {
302
+ "required": ["label"]
303
+ },
241
304
  {
242
305
  "required": ["placeholder"]
243
306
  },
@@ -257,6 +320,9 @@
257
320
  {
258
321
  "required": ["role"]
259
322
  },
323
+ {
324
+ "required": ["label"]
325
+ },
260
326
  {
261
327
  "required": ["testId"]
262
328
  },
@@ -276,6 +342,9 @@
276
342
  {
277
343
  "required": ["role"]
278
344
  },
345
+ {
346
+ "required": ["label"]
347
+ },
279
348
  {
280
349
  "required": ["testId"]
281
350
  },
@@ -295,6 +364,9 @@
295
364
  {
296
365
  "required": ["role"]
297
366
  },
367
+ {
368
+ "required": ["label"]
369
+ },
298
370
  {
299
371
  "required": ["testId"]
300
372
  },
@@ -422,8 +494,56 @@
422
494
  "description": "A key, such as Enter or Tab."
423
495
  }
424
496
  }
497
+ },
498
+ {
499
+ "type": "object",
500
+ "required": ["open"],
501
+ "additionalProperties": false,
502
+ "properties": {
503
+ "open": {
504
+ "type": "string",
505
+ "minLength": 1,
506
+ "maxLength": 500,
507
+ "pattern": "^(?:https?://\\S+|(?![A-Za-z][A-Za-z0-9+.-]*:)\\S+)$",
508
+ "description": "Opens a page by its address: a path of the app, such as \"page/WorkTasks/List\", or a whole URL on it. Needs @testra-studio/kit 0.3.0 or later."
509
+ }
510
+ }
425
511
  }
426
512
  ]
513
+ },
514
+ "expectation": {
515
+ "type": "object",
516
+ "required": ["target", "matcher"],
517
+ "additionalProperties": false,
518
+ "description": "What a Check expects of one element, checked with the framework's expect. Needs @testra-studio/kit 0.3.0 or later.",
519
+ "properties": {
520
+ "target": {
521
+ "$ref": "#/$defs/target"
522
+ },
523
+ "matcher": {
524
+ "enum": ["toBeVisible", "toHaveText", "toContainText", "toHaveValue"]
525
+ },
526
+ "value": {
527
+ "type": "string",
528
+ "maxLength": 500,
529
+ "description": "The text or value expected; its {…} tokens are the run's values. Not for toBeVisible."
530
+ }
531
+ },
532
+ "if": {
533
+ "properties": {
534
+ "matcher": {
535
+ "const": "toBeVisible"
536
+ }
537
+ }
538
+ },
539
+ "then": {
540
+ "not": {
541
+ "required": ["value"]
542
+ }
543
+ },
544
+ "else": {
545
+ "required": ["value"]
546
+ }
427
547
  }
428
548
  }
429
549
  }