@testra-studio/kit 0.2.1 → 0.3.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,27 @@ 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.3.0
9
+
10
+ - A Do step's actions may open a page by its address in the app:
11
+ `{ "open": "page/WorkTasks/List" }`, a path of the app or an http(s) URL
12
+ on it (never another scheme). `runSteps()` opens it with the `app` fixture.
13
+ - An element may be found by its label: `{ "label": "Status" }`, as
14
+ `getByLabel` finds a field.
15
+ - A Check may carry exact expectations on elements, checked with the
16
+ framework's `expect` instead of the agent judging its sentence:
17
+ `"expect": [{ "target": { "label": "Status" }, "matcher": "toHaveValue",
18
+ "value": "Released" }]`, with `toBeVisible`, `toHaveText`, `toContainText`
19
+ or `toHaveValue`. An element showing something else fails the check; one
20
+ not there (the screen changed) makes the agent judge the sentence, as a Do
21
+ step's missing element does.
22
+ - The steps schema has all three.
23
+
24
+ What a project does: pass `app` as well to `runSteps()` in a web project's
25
+ `support/plain.ts` (`{ agent, screen, browser, app }`). Without it, a step
26
+ that opens a page is the agent's, from its sentence. Steps files without
27
+ these run as they did.
28
+
8
29
  ## 0.2.1
9
30
 
10
31
  - 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,33 @@ 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.
97
122
 
98
123
  ## Basic data
99
124
 
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;
@@ -45,7 +51,15 @@ export type StepAction = {
45
51
  readonly key: string;
46
52
  } | {
47
53
  readonly key: string;
54
+ }
55
+ /** 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. */
56
+ | {
57
+ readonly open: string;
48
58
  };
59
+ /** The app, as a test gets it: for an `open` action. */
60
+ export interface AppLike {
61
+ open(path?: string): Promise<unknown>;
62
+ }
49
63
  /** The parts of the web engine's locator the actions use. */
50
64
  export interface LocatorLike {
51
65
  tap(options?: {
@@ -76,6 +90,7 @@ export interface LocatorLike {
76
90
  getByTestId(id: string): LocatorLike;
77
91
  getByPlaceholder(text: string): LocatorLike;
78
92
  getByText(text: string): LocatorLike;
93
+ getByLabel(text: string): LocatorLike;
79
94
  filter(options: {
80
95
  hasText: string;
81
96
  }): LocatorLike;
@@ -86,6 +101,7 @@ export interface ScreenLike {
86
101
  getByTestId(id: string): LocatorLike;
87
102
  getByPlaceholder(text: string): LocatorLike;
88
103
  getByText(text: string): LocatorLike;
104
+ getByLabel(text: string): LocatorLike;
89
105
  }
90
106
  /** The web engine's `browser`, for an id, a frame and a key on whatever has focus. */
91
107
  export interface BrowserLike {
@@ -106,4 +122,48 @@ export declare function locate(target: StepTarget, screen: ScreenLike, browser:
106
122
  /** How long one recorded action waits for its element before the step falls back to its sentence. */
107
123
  export declare const ACTION_TIMEOUT = 15000;
108
124
  /** 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>;
125
+ export declare function perform(action: StepAction, screen: ScreenLike, browser: BrowserLike | undefined, value: (text: string) => string, app?: AppLike): Promise<void>;
126
+ /** The matchers an expectation may use, as the framework's `expect` names them. */
127
+ export declare const MATCHERS: readonly ['toBeVisible', 'toHaveText', 'toContainText', 'toHaveValue'];
128
+ /**
129
+ * What a Check expects of one element, checked with the framework's
130
+ * `expect`: shown, or showing a text or a value (its `{…}` tokens are the
131
+ * run's values). Kit 0.3.0.
132
+ *
133
+ * { "check": "The request's status is Released", "expect": [
134
+ * { "target": { "label": "Status" }, "matcher": "toHaveValue", "value": "Released" } ] }
135
+ */
136
+ export type CheckExpectation = {
137
+ readonly target: StepTarget;
138
+ readonly matcher: 'toBeVisible';
139
+ } | {
140
+ readonly target: StepTarget;
141
+ readonly matcher: 'toHaveText' | 'toContainText' | 'toHaveValue';
142
+ readonly value: string;
143
+ };
144
+ /** The framework's `expect`, in the matchers an expectation uses. */
145
+ export type ExpectLike = (locator: LocatorLike) => {
146
+ toBeVisible(options?: {
147
+ timeout?: number;
148
+ }): Promise<unknown>;
149
+ toHaveText(value: string, options?: {
150
+ timeout?: number;
151
+ }): Promise<unknown>;
152
+ toContainText(value: string, options?: {
153
+ timeout?: number;
154
+ }): Promise<unknown>;
155
+ toHaveValue(value: string, options?: {
156
+ timeout?: number;
157
+ }): Promise<unknown>;
158
+ };
159
+ /** Why `value` is no expectation, or nothing when it is one. */
160
+ export declare function expectationProblem(value: unknown): string | undefined;
161
+ /** How long an expectation waits for its element to show before the check falls back to its sentence. */
162
+ export declare const EXPECT_TIMEOUT = 15000;
163
+ /**
164
+ * Checks one expectation. The element not showing is `missing`: the screen
165
+ * changed, so the check falls back to the agent judging its sentence, as a
166
+ * Do step's missing element does. The element showing something else fails,
167
+ * with the framework's message: that is what the test is there to catch.
168
+ */
169
+ 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,41 @@
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
+ ];
12
28
  const WITH_VALUE = ['fill', 'type', 'select'];
13
29
  const ON_TARGET = ['tap', 'doubleTap', 'check', 'uncheck'];
30
+ /** An address an `open` action takes: an http(s) URL, or a path of the app that names no other scheme (`javascript:`, `file:`). */
31
+ const ADDRESS = /^(?:https?:\/\/\S+|(?![A-Za-z][A-Za-z0-9+.-]*:)\S+)$/;
14
32
  /** Why `value` is no recorded action, or nothing when it is one. */
15
33
  export function actionProblem(value) {
16
34
  if (!isObject(value))
17
35
  return 'an action is an object such as { "tap": { "role": "button", "name": "Save" } }';
36
+ if ('open' in value) {
37
+ if (Object.keys(value).length !== 1)
38
+ return 'open: an action opens one address, with nothing beside it';
39
+ const address = value.open;
40
+ if (typeof address !== 'string' || !address || address.length > 500 || !ADDRESS.test(address)) {
41
+ return 'open needs the address of a page of the app, such as "page/WorkTasks/List"';
42
+ }
43
+ return undefined;
44
+ }
18
45
  const keys = Object.keys(value);
19
46
  const kind = keys.find((k) => [...ON_TARGET, ...WITH_VALUE, 'press'].includes(k)) ?? (keys.includes('key') ? 'key' : '');
20
47
  const allowed = WITH_VALUE.includes(kind)
@@ -23,7 +50,7 @@ export function actionProblem(value) {
23
50
  ? ['press', 'key']
24
51
  : [kind];
25
52
  if (!kind)
26
- return `${JSON.stringify(value)} is no action: tap, doubleTap, fill, type, select, check, uncheck, press or key`;
53
+ return `${JSON.stringify(value)} is no action: tap, doubleTap, fill, type, select, check, uncheck, press, key or open`;
27
54
  const extra = keys.filter((k) => !allowed.includes(k));
28
55
  if (extra.length)
29
56
  return `${kind}: unknown key ${extra.join(', ')}`;
@@ -47,13 +74,14 @@ function targetProblem(target) {
47
74
  return "an element's values are text";
48
75
  const ways = [
49
76
  target.role !== undefined && (target.name !== undefined) !== (target.nameStarts !== undefined),
77
+ target.label !== undefined,
50
78
  target.testId !== undefined,
51
79
  target.placeholder !== undefined,
52
80
  target.id !== undefined,
53
81
  target.text !== undefined,
54
82
  ].filter(Boolean).length;
55
83
  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';
84
+ 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
85
  }
58
86
  return undefined;
59
87
  }
@@ -76,6 +104,8 @@ export function locate(target, screen, browser) {
76
104
  if (target.role && target.nameStarts !== undefined) {
77
105
  return scope.getByRole(target.role, new RegExp(`^${target.nameStarts.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`));
78
106
  }
107
+ if (target.label !== undefined)
108
+ return scope.getByLabel(target.label);
79
109
  if (target.testId !== undefined)
80
110
  return scope.getByTestId(target.testId);
81
111
  if (target.placeholder !== undefined)
@@ -85,7 +115,9 @@ export function locate(target, screen, browser) {
85
115
  /** How long one recorded action waits for its element before the step falls back to its sentence. */
86
116
  export const ACTION_TIMEOUT = 15_000;
87
117
  /** Does one recorded action, its value with the run's values in place of `{…}` (`value`). */
88
- export async function perform(action, screen, browser, value) {
118
+ export async function perform(action, screen, browser, value, app) {
119
+ if ('open' in action)
120
+ return void (await need(app, 'opening a page', 'app').open(action.open));
89
121
  const timeout = { timeout: ACTION_TIMEOUT };
90
122
  if ('tap' in action)
91
123
  return void (await locate(action.tap, screen, browser).tap(timeout));
@@ -107,11 +139,56 @@ export async function perform(action, screen, browser, value) {
107
139
  return void (await locate(action.press, screen, browser).press(action.key, timeout));
108
140
  await need(browser, 'a key on whatever has focus').keyboard.press(action.key);
109
141
  }
110
- function need(value, what) {
142
+ function need(value, what, fixture = 'browser') {
111
143
  if (value === undefined)
112
- throw new Error(`${what} needs the browser fixture, which the runner did not pass`);
144
+ throw new Error(`${what} needs the ${fixture} fixture, which the runner did not pass`);
113
145
  return value;
114
146
  }
147
+ // ── Exact expectations on a Check ────────────────────────────────────────
148
+ /** The matchers an expectation may use, as the framework's `expect` names them. */
149
+ export const MATCHERS = ['toBeVisible', 'toHaveText', 'toContainText', 'toHaveValue'];
150
+ /** Why `value` is no expectation, or nothing when it is one. */
151
+ export function expectationProblem(value) {
152
+ if (!isObject(value))
153
+ return 'an expectation is an object such as { "target": {…}, "matcher": "toBeVisible" }';
154
+ const extra = Object.keys(value).filter((k) => !['target', 'matcher', 'value'].includes(k));
155
+ if (extra.length)
156
+ return `an expectation has no ${extra.join(', ')}`;
157
+ const matcher = value.matcher;
158
+ if (typeof matcher !== 'string' || !MATCHERS.includes(matcher)) {
159
+ return `"matcher" must be one of ${MATCHERS.join(', ')}`;
160
+ }
161
+ if (matcher === 'toBeVisible') {
162
+ if (value.value !== undefined)
163
+ return 'toBeVisible takes no "value"';
164
+ }
165
+ else if (typeof value.value !== 'string' || value.value.length > 500) {
166
+ return `${matcher} needs a "value" of up to 500 characters`;
167
+ }
168
+ return targetProblem(value.target);
169
+ }
170
+ /** How long an expectation waits for its element to show before the check falls back to its sentence. */
171
+ export const EXPECT_TIMEOUT = 15_000;
172
+ /**
173
+ * Checks one expectation. The element not showing is `missing`: the screen
174
+ * changed, so the check falls back to the agent judging its sentence, as a
175
+ * Do step's missing element does. The element showing something else fails,
176
+ * with the framework's message: that is what the test is there to catch.
177
+ */
178
+ export async function expectOn(expectation, screen, browser, value, expect) {
179
+ const timeout = { timeout: EXPECT_TIMEOUT };
180
+ const element = locate(expectation.target, screen, browser);
181
+ try {
182
+ await expect(element).toBeVisible(timeout);
183
+ }
184
+ catch {
185
+ return 'missing';
186
+ }
187
+ if (expectation.matcher === 'toBeVisible')
188
+ return 'held';
189
+ await expect(element)[expectation.matcher](value(expectation.value), timeout);
190
+ return 'held';
191
+ }
115
192
  function isObject(value) {
116
193
  return typeof value === 'object' && value !== null && !Array.isArray(value);
117
194
  }
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,8 @@ 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
+ /** For a Check: what it expects of exact elements, checked with `expect`; the sentence is the fallback. */
104
+ readonly expect?: readonly CheckExpectation[];
99
105
  readonly when?: Condition;
100
106
  } | {
101
107
  /** 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';
@@ -155,7 +155,9 @@ export function parsePlainTest(json, context, options = {}) {
155
155
  ? [kind, 'with', 'when']
156
156
  : kind === 'do'
157
157
  ? [kind, 'actions', 'when']
158
- : [kind, '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,24 @@ 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) {
186
+ if (!Array.isArray(expected) || expected.length === 0 || expected.length > 10)
187
+ throw fail(where, '"expect" must list from 1 to 10 expectations');
188
+ expected.forEach((expectation, at) => {
189
+ const problem = expectationProblem(expectation);
190
+ if (problem)
191
+ throw fail(`${where} expectation ${at + 1}`, problem);
192
+ const shown = expectation.value;
193
+ if (shown)
194
+ checkTokens(`${where} expectation ${at + 1}`, shown, false);
195
+ });
196
+ }
182
197
  return {
183
198
  kind,
184
199
  text: text.trim(),
185
200
  ...(actions !== undefined ? { actions: actions } : {}),
201
+ ...(expected !== undefined ? { expect: expected } : {}),
186
202
  ...(when ? { when } : {}),
187
203
  };
188
204
  }
@@ -255,7 +271,8 @@ export function missingFeatures(test, options = {}) {
255
271
  * and a `waitUntil`, judged anew on every run, get the values in their text.
256
272
  */
257
273
  export async function runSteps(fixtures, test, options = {}) {
258
- const { agent, screen, browser } = 'agent' in fixtures ? fixtures : { agent: fixtures, screen: undefined, browser: undefined };
274
+ const { agent, screen, browser, app } = 'agent' in fixtures ? fixtures : { agent: fixtures, screen: undefined, browser: undefined, app: undefined };
275
+ const expect = ('agent' in fixtures ? fixtures.expect : undefined) ?? e2eExpect;
259
276
  const results = new Map();
260
277
  const has = options.features?.has ?? (() => false);
261
278
  const lookUp = (token, name, value, field) => {
@@ -312,7 +329,7 @@ export async function runSteps(fixtures, test, options = {}) {
312
329
  if (step.actions && screen) {
313
330
  try {
314
331
  for (const action of step.actions)
315
- await perform(action, screen, browser, text);
332
+ await perform(action, screen, browser, text, app);
316
333
  continue;
317
334
  }
318
335
  catch (error) {
@@ -324,6 +341,24 @@ export async function runSteps(fixtures, test, options = {}) {
324
341
  await agent.act(instruction, Object.keys(params).length ? { params } : {});
325
342
  }
326
343
  else if (step.kind === 'check') {
344
+ // Exact expectations, checked with expect; an element that is not there means the screen changed, so the agent judges.
345
+ if (step.expect && screen) {
346
+ let missing = false;
347
+ for (const expectation of step.expect) {
348
+ try {
349
+ missing = (await expectOn(expectation, screen, browser, text, expect)) === 'missing';
350
+ }
351
+ catch (error) {
352
+ const why = error instanceof Error ? error.message : String(error);
353
+ throw new Error(`${test.file} step ${index + 1}, check "${step.text}": ${why}`, { cause: error });
354
+ }
355
+ if (missing)
356
+ break;
357
+ }
358
+ if (!missing)
359
+ continue;
360
+ console.warn(`${test.file} step ${index + 1}: an expected element is not there; the agent judges "${step.text}" instead`);
361
+ }
327
362
  await agent.assert(text(step.text), { screenshot: false });
328
363
  }
329
364
  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.3.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",
@@ -83,6 +83,15 @@
83
83
  },
84
84
  "when": {
85
85
  "$ref": "#/$defs/when"
86
+ },
87
+ "expect": {
88
+ "type": "array",
89
+ "minItems": 1,
90
+ "maxItems": 10,
91
+ "items": {
92
+ "$ref": "#/$defs/expectation"
93
+ },
94
+ "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
95
  }
87
96
  }
88
97
  },
@@ -142,7 +151,7 @@
142
151
  },
143
152
  "target": {
144
153
  "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.",
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.",
146
155
  "additionalProperties": false,
147
156
  "properties": {
148
157
  "role": {
@@ -157,6 +166,11 @@
157
166
  "type": "string",
158
167
  "minLength": 1
159
168
  },
169
+ "label": {
170
+ "type": "string",
171
+ "minLength": 1,
172
+ "description": "A field by its label. Needs @testra-studio/kit 0.3.0 or later."
173
+ },
160
174
  "testId": {
161
175
  "type": "string",
162
176
  "minLength": 1
@@ -194,6 +208,9 @@
194
208
  {
195
209
  "required": ["nameStarts"]
196
210
  },
211
+ {
212
+ "required": ["label"]
213
+ },
197
214
  {
198
215
  "required": ["testId"]
199
216
  },
@@ -216,6 +233,31 @@
216
233
  {
217
234
  "required": ["name"]
218
235
  },
236
+ {
237
+ "required": ["label"]
238
+ },
239
+ {
240
+ "required": ["testId"]
241
+ },
242
+ {
243
+ "required": ["placeholder"]
244
+ },
245
+ {
246
+ "required": ["id"]
247
+ },
248
+ {
249
+ "required": ["text"]
250
+ }
251
+ ]
252
+ }
253
+ },
254
+ {
255
+ "required": ["label"],
256
+ "not": {
257
+ "anyOf": [
258
+ {
259
+ "required": ["role"]
260
+ },
219
261
  {
220
262
  "required": ["testId"]
221
263
  },
@@ -238,6 +280,9 @@
238
280
  {
239
281
  "required": ["role"]
240
282
  },
283
+ {
284
+ "required": ["label"]
285
+ },
241
286
  {
242
287
  "required": ["placeholder"]
243
288
  },
@@ -257,6 +302,9 @@
257
302
  {
258
303
  "required": ["role"]
259
304
  },
305
+ {
306
+ "required": ["label"]
307
+ },
260
308
  {
261
309
  "required": ["testId"]
262
310
  },
@@ -276,6 +324,9 @@
276
324
  {
277
325
  "required": ["role"]
278
326
  },
327
+ {
328
+ "required": ["label"]
329
+ },
279
330
  {
280
331
  "required": ["testId"]
281
332
  },
@@ -295,6 +346,9 @@
295
346
  {
296
347
  "required": ["role"]
297
348
  },
349
+ {
350
+ "required": ["label"]
351
+ },
298
352
  {
299
353
  "required": ["testId"]
300
354
  },
@@ -422,8 +476,56 @@
422
476
  "description": "A key, such as Enter or Tab."
423
477
  }
424
478
  }
479
+ },
480
+ {
481
+ "type": "object",
482
+ "required": ["open"],
483
+ "additionalProperties": false,
484
+ "properties": {
485
+ "open": {
486
+ "type": "string",
487
+ "minLength": 1,
488
+ "maxLength": 500,
489
+ "pattern": "^(?:https?://\\S+|(?![A-Za-z][A-Za-z0-9+.-]*:)\\S+)$",
490
+ "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."
491
+ }
492
+ }
425
493
  }
426
494
  ]
495
+ },
496
+ "expectation": {
497
+ "type": "object",
498
+ "required": ["target", "matcher"],
499
+ "additionalProperties": false,
500
+ "description": "What a Check expects of one element, checked with the framework's expect. Needs @testra-studio/kit 0.3.0 or later.",
501
+ "properties": {
502
+ "target": {
503
+ "$ref": "#/$defs/target"
504
+ },
505
+ "matcher": {
506
+ "enum": ["toBeVisible", "toHaveText", "toContainText", "toHaveValue"]
507
+ },
508
+ "value": {
509
+ "type": "string",
510
+ "maxLength": 500,
511
+ "description": "The text or value expected; its {…} tokens are the run's values. Not for toBeVisible."
512
+ }
513
+ },
514
+ "if": {
515
+ "properties": {
516
+ "matcher": {
517
+ "const": "toBeVisible"
518
+ }
519
+ }
520
+ },
521
+ "then": {
522
+ "not": {
523
+ "required": ["value"]
524
+ }
525
+ },
526
+ "else": {
527
+ "required": ["value"]
528
+ }
427
529
  }
428
530
  }
429
531
  }