@testra-studio/kit 0.4.0 → 0.5.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,40 @@ 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.5.0
9
+
10
+ - A step may work on a page by the names the app's own model gives its
11
+ fields and commands, through the project's own controls (`PageControls`):
12
+ `{ "set": { "page": "/orders/new", "field": "SiteId" }, "value":
13
+ "S-01" }` gives a field its value the way its control takes one, and
14
+ `{ "run": { "page": "/orders/new", "command": "save" }, "answer":
15
+ ["Save anyway"] }` runs a command, pressing the first of `answer`'s
16
+ buttons that what it opens shows. Both wait until they are done, as the
17
+ project's controls know how.
18
+ - An element may be a page's field: `{ "page": "/orders/new",
19
+ "field": "OrderNo" }`, in an expectation or an action.
20
+ - The names are checked when a steps file loads, where the project knows
21
+ its pages then: a field or a command the page does not have fails the
22
+ listing, by file and step. A project that learns its pages as a run starts
23
+ (`PageControls.prepare`, called before the first step with the pages the
24
+ test names) has them checked then, before anything is done on the screen.
25
+ - The steps schema has all three.
26
+
27
+ What a project does: nothing, to keep running its steps files as they are.
28
+ To use these, pass `pages` (a `PageControls`: `problem`, `field`, `set` and
29
+ `run`, and `prepare` when its pages are read as a run starts) in the options of `loadPlainTest()` and `runSteps()` in its
30
+ `support/plain.ts`. Without it, a steps file that names a page's field or
31
+ command is refused when it loads.
32
+
33
+ ## 0.4.1
34
+
35
+ - A recorded Tab on a combobox waits until its list has closed before the
36
+ next action: a lookup checks its value with the app after Tab, and a Save
37
+ pressed meanwhile was lost. One still open after 10 s is warned of, and
38
+ the run goes on.
39
+
40
+ What a project does: nothing.
41
+
8
42
  ## 0.4.0
9
43
 
10
44
  - A Do step with actions may say what shows when it is done, in a Check's
@@ -23,7 +57,7 @@ What a project does: nothing. Steps files without these run as they did.
23
57
  ## 0.3.0
24
58
 
25
59
  - 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
60
+ `{ "open": "orders/list" }`, a path of the app or an http(s) URL
27
61
  on it (never another scheme). `runSteps()` opens it with the `app` fixture.
28
62
  - An element may be found by its label: `{ "label": "Status" }`, as
29
63
  `getByLabel` finds a field.
package/README.md CHANGED
@@ -96,7 +96,7 @@ is structured, never code: a role with its name (or `nameStarts`), else a
96
96
  and `row` it is in.
97
97
 
98
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`).
99
+ fixture: `{ "open": "orders/list" }` (kit 0.3.0, as is `label`).
100
100
 
101
101
  ### Exact checks
102
102
 
@@ -126,13 +126,13 @@ step does not start on a page still busy, as a lookup resolving after Tab:
126
126
 
127
127
  ```json
128
128
  {
129
- "do": "Set WO Site to {basic.site.code}",
129
+ "do": "Set Site to {basic.site.code}",
130
130
  "actions": [
131
- { "fill": { "role": "combobox", "name": "WO Site" }, "value": "{basic.site.code}" },
132
- { "press": { "role": "combobox", "name": "WO Site" }, "key": "Tab" }
131
+ { "fill": { "role": "combobox", "name": "Site" }, "value": "{basic.site.code}" },
132
+ { "press": { "role": "combobox", "name": "Site" }, "key": "Tab" }
133
133
  ],
134
134
  "expect": [
135
- { "target": { "role": "combobox", "name": "WO Site" }, "matcher": "toHaveValue",
135
+ { "target": { "role": "combobox", "name": "Site" }, "matcher": "toHaveValue",
136
136
  "value": "{basic.site.code} - {basic.site.name}" }
137
137
  ]
138
138
  }
@@ -146,6 +146,54 @@ An element may say which of several matching ones it is, from 0 (kit 0.4.0):
146
146
  matches several when the step runs, is the first of them, and the run
147
147
  warns.
148
148
 
149
+ ### A page by its own names
150
+
151
+ Where the app's pages have names of their own for what is on them (an app
152
+ built from metadata has, for each field and command), a step may work on a
153
+ page by those names, through the project's own controls (kit 0.5.0):
154
+
155
+ ```json
156
+ {
157
+ "do": "Make an order on {basic.site.code}",
158
+ "actions": [
159
+ { "run": { "page": "/orders/new", "command": "new" } },
160
+ { "set": { "page": "/orders/new", "field": "SiteId" }, "value": "{basic.site.code}" },
161
+ { "run": { "page": "/orders/new", "command": "save" }, "answer": ["Save anyway", "OK"] }
162
+ ],
163
+ "expect": [
164
+ { "target": { "page": "/orders/new", "field": "OrderNo" }, "matcher": "toBeVisible" }
165
+ ]
166
+ }
167
+ ```
168
+
169
+ - `set` gives a field its value the way its control takes one (a lookup, a
170
+ switch, a text), and waits until it holds it.
171
+ - `run` runs a command and waits until it is done: one of the page's
172
+ commands by the name its model gives it, or whatever else the project's
173
+ controls run by a name of their own, such as opening the page (`open`) or
174
+ one of its own buttons (`save`). `answer` lists the
175
+ buttons to press in what the command opens meanwhile (a confirmation, a
176
+ check the app makes before it saves): the first of them it shows.
177
+ - `{ "page": …, "field": … }` is an element like any other: an expectation
178
+ reads it, and an action may be done on it. It stands alone, without a
179
+ dialog, a row or a frame.
180
+
181
+ The kit holds only the names. The project says what they mean, with
182
+ `pages` in the options its `support/plain.ts` passes to `loadPlainTest()`
183
+ and `runSteps()`, a `PageControls`:
184
+
185
+ | | |
186
+ | --- | --- |
187
+ | `prepare(pages)` | Optional. Gets ready the pages a test names, before its first step: a project that reads its pages' models as a run starts, from a service that knows the app as the instance has it, reads them here |
188
+ | `problem(part)` | Why a page has no such field or command, or nothing, also when the project cannot say yet. Asked when a steps file loads, so a name a page lacks fails the listing, by file and step, where the project knows its pages then; and again as a run starts, after `prepare`, so it fails the test before its first step |
189
+ | `field(field, fixtures)` | The field's element: the one that holds its value |
190
+ | `set(field, value, fixtures)` | Gives the field the value, and waits until it holds it |
191
+ | `run(command, { answer }, fixtures)` | Runs the command, and waits until it is done |
192
+
193
+ A control that fails hands the step to the agent, from its sentence, as a
194
+ recorded action that finds no element does. Without `pages`, a steps file
195
+ that names a page's field or command is refused when it loads.
196
+
149
197
  ## Basic data
150
198
 
151
199
  `readBasicData({ dir, instance, fromEnv })` takes each item, listed in
package/dist/actions.d.ts CHANGED
@@ -11,6 +11,17 @@
11
11
  * An action may also open a page by its address in the app (`open`), and a
12
12
  * Check may carry exact expectations on elements (`CheckExpectation`), which
13
13
  * a run checks with the framework's `expect` instead of asking the agent.
14
+ *
15
+ * Where the app's pages have names of their own for what is on them (an app
16
+ * built from metadata has, for every field and command), an action may work
17
+ * on a page by those names, through the project's own controls
18
+ * (`PageControls`, kit 0.5.0): a field is given its value the way its
19
+ * control takes one (`set`), a command is run (`run`), and an expectation
20
+ * reads a field.
21
+ *
22
+ * { "do": "Set the site and save", "actions": [
23
+ * { "set": { "page": "/orders/new", "field": "SiteId" }, "value": "{basic.site.code}" },
24
+ * { "run": { "page": "/orders/new", "command": "save" }, "answer": ["Save anyway"] } ] }
14
25
  */
15
26
  /** An element, as the web engine finds it: one way, inside its frame, dialog and row. */
16
27
  export interface StepTarget {
@@ -30,6 +41,66 @@ export interface StepTarget {
30
41
  readonly frame?: string;
31
42
  /** Which of several matching elements, from 0: as `.first()` (0) or `.nth(n)` found it. Kit 0.4.0. */
32
43
  readonly nth?: number;
44
+ /**
45
+ * A field of one of the app's pages, by the names the app's own model
46
+ * gives them: the page's address, and the field's name on it. The
47
+ * project's controls find it (`PageControls`); it stands alone, without
48
+ * the other ways or a dialog, row or frame. Kit 0.5.0.
49
+ */
50
+ readonly page?: string;
51
+ readonly field?: string;
52
+ }
53
+ /** A field of a page, by the app's own names for them. */
54
+ export interface FieldRef {
55
+ readonly page: string;
56
+ readonly field: string;
57
+ }
58
+ /** A command of a page, by the app's own names for them: one of its toolbar's, or its own New or Save. */
59
+ export interface CommandRef {
60
+ readonly page: string;
61
+ readonly command: string;
62
+ }
63
+ /** What a project's controls work on a page with: the fixtures a run's steps have. */
64
+ export interface ControlFixtures {
65
+ readonly screen: ScreenLike;
66
+ readonly browser?: BrowserLike | undefined;
67
+ readonly app?: AppLike | undefined;
68
+ readonly expect?: ExpectLike | undefined;
69
+ }
70
+ /**
71
+ * The app's pages, as the project works on them by the names its own model
72
+ * gives their fields and commands. The project knows the model and how each
73
+ * kind of control is used (a lookup, a switch, a command in a menu); the kit
74
+ * only hands it the names a step holds. Kit 0.5.0.
75
+ */
76
+ export interface PageControls {
77
+ /**
78
+ * Gets ready the pages a test names, before its first step: a project
79
+ * that reads its pages' models from elsewhere as a run starts (a service
80
+ * that knows the app as the instance has it) reads them here. Failing, it
81
+ * fails the test before any step runs.
82
+ */
83
+ prepare?(pages: readonly string[]): Promise<void>;
84
+ /**
85
+ * Why a page has no such field or command, or nothing when it has, or when
86
+ * the project cannot say yet. Asked when a steps file is loaded, so a name
87
+ * a page does not have fails the listing, by file and step, where the
88
+ * project knows its pages then; and again as a run starts, once `prepare`
89
+ * is done, so it fails the test before its first step.
90
+ */
91
+ problem(part: FieldRef | CommandRef): string | undefined;
92
+ /** A field's element: the one that holds its value, which an action is done on and an expectation reads. */
93
+ field(field: FieldRef, fixtures: ControlFixtures): LocatorLike;
94
+ /** Gives a field a value the way its control takes one, and waits until it holds it. */
95
+ set(field: FieldRef, value: string, fixtures: ControlFixtures): Promise<void>;
96
+ /**
97
+ * Runs a command and waits until it is done, pressing the first of
98
+ * `answer`'s buttons that whatever it opens meanwhile shows (a
99
+ * confirmation, a check the app makes before it saves).
100
+ */
101
+ run(command: CommandRef, options: {
102
+ readonly answer?: readonly string[];
103
+ }, fixtures: ControlFixtures): Promise<void>;
33
104
  }
34
105
  export type StepAction = {
35
106
  readonly tap: StepTarget;
@@ -57,6 +128,16 @@ export type StepAction = {
57
128
  /** 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
129
  | {
59
130
  readonly open: string;
131
+ }
132
+ /** Gives a page's field a value, the way its control takes one. Kit 0.5.0. */
133
+ | {
134
+ readonly set: StepTarget;
135
+ readonly value: string;
136
+ }
137
+ /** Runs a page's command, answering what it asks. Kit 0.5.0. */
138
+ | {
139
+ readonly run: CommandRef;
140
+ readonly answer?: readonly string[];
60
141
  };
61
142
  /** The app, as a test gets it: for an `open` action. */
62
143
  export interface AppLike {
@@ -123,12 +204,30 @@ export interface BrowserLike {
123
204
  export declare function actionProblem(value: unknown): string | undefined;
124
205
  /** The values an action types, fills or chooses, for its `{…}` tokens. */
125
206
  export declare function actionValue(action: StepAction): string | undefined;
126
- /** The web engine's locator for a target, inside its frame, dialog and row; the `nth` of them when it says. */
127
- export declare function locate(target: StepTarget, screen: ScreenLike, browser: BrowserLike | undefined): LocatorLike;
207
+ /** A target that names a page's field, as the project's controls take it; nothing for any other. */
208
+ export declare function fieldOf(target: StepTarget): FieldRef | undefined;
209
+ /** The names of the app's pages an action works by: its field's, or its command's; nothing for any other action. */
210
+ export declare function partOf(action: StepAction): FieldRef | CommandRef | undefined;
211
+ /**
212
+ * The web engine's locator for a target, inside its frame, dialog and row;
213
+ * the `nth` of them when it says. A page's field is the project's controls'
214
+ * to find.
215
+ */
216
+ export declare function locate(target: StepTarget, screen: ScreenLike, browser: BrowserLike | undefined, pages?: PageControls): LocatorLike;
128
217
  /** How long one recorded action waits for its element before the step falls back to its sentence. */
129
218
  export declare const ACTION_TIMEOUT = 15000;
130
- /** Does one recorded action, its value with the run's values in place of `{…}` (`value`). */
131
- export declare function perform(action: StepAction, screen: ScreenLike, browser: BrowserLike | undefined, value: (text: string) => string, app?: AppLike): Promise<void>;
219
+ /** How long a combobox left with Tab is waited for to check its value, before the run goes on and says so. */
220
+ export declare const LOOKUP_TIMEOUT = 10000;
221
+ /**
222
+ * Does one recorded action, its value with the run's values in place of `{…}` (`value`).
223
+ *
224
+ * A combobox left with Tab checks its value with the app (a lookup: its list
225
+ * stays open until the value is found), and what is pressed meanwhile may be
226
+ * lost, as a Save is. So with the framework's `expect`, Tab on a combobox
227
+ * waits until its list has closed; one still open after `LOOKUP_TIMEOUT` is
228
+ * said, and the run goes on. Kit 0.4.1.
229
+ */
230
+ export declare function perform(action: StepAction, screen: ScreenLike, browser: BrowserLike | undefined, value: (text: string) => string, app?: AppLike, expect?: ExpectLike, pages?: PageControls): Promise<void>;
132
231
  /** The matchers an expectation may use, as the framework's `expect` names them. */
133
232
  export declare const MATCHERS: readonly ['toBeVisible', 'toHaveText', 'toContainText', 'toHaveValue'];
134
233
  /**
@@ -161,6 +260,12 @@ export type ExpectLike = (locator: LocatorLike) => {
161
260
  toHaveValue(value: string, options?: {
162
261
  timeout?: number;
163
262
  }): Promise<unknown>;
263
+ /** Where the framework has it: what says a combobox left with Tab has closed its list. Kit 0.4.1. */
264
+ readonly not?: {
265
+ toBeExpanded?(options?: {
266
+ timeout?: number;
267
+ }): Promise<unknown>;
268
+ };
164
269
  };
165
270
  /** Why `value` is no expectation, or nothing when it is one. */
166
271
  export declare function expectationProblem(value: unknown): string | undefined;
@@ -172,4 +277,4 @@ export declare const EXPECT_TIMEOUT = 15000;
172
277
  * Do step's missing element does. The element showing something else fails,
173
278
  * with the framework's message: that is what the test is there to catch.
174
279
  */
175
- export declare function expectOn(expectation: CheckExpectation, screen: ScreenLike, browser: BrowserLike | undefined, value: (text: string) => string, expect: ExpectLike): Promise<'held' | 'missing'>;
280
+ export declare function expectOn(expectation: CheckExpectation, screen: ScreenLike, browser: BrowserLike | undefined, value: (text: string) => string, expect: ExpectLike, pages?: PageControls): Promise<'held' | 'missing'>;
package/dist/actions.js CHANGED
@@ -11,6 +11,17 @@
11
11
  * An action may also open a page by its address in the app (`open`), and a
12
12
  * Check may carry exact expectations on elements (`CheckExpectation`), which
13
13
  * a run checks with the framework's `expect` instead of asking the agent.
14
+ *
15
+ * Where the app's pages have names of their own for what is on them (an app
16
+ * built from metadata has, for every field and command), an action may work
17
+ * on a page by those names, through the project's own controls
18
+ * (`PageControls`, kit 0.5.0): a field is given its value the way its
19
+ * control takes one (`set`), a command is run (`run`), and an expectation
20
+ * reads a field.
21
+ *
22
+ * { "do": "Set the site and save", "actions": [
23
+ * { "set": { "page": "/orders/new", "field": "SiteId" }, "value": "{basic.site.code}" },
24
+ * { "run": { "page": "/orders/new", "command": "save" }, "answer": ["Save anyway"] } ] }
14
25
  */
15
26
  const TARGET_KEYS = [
16
27
  'role',
@@ -25,8 +36,17 @@ const TARGET_KEYS = [
25
36
  'row',
26
37
  'frame',
27
38
  'nth',
39
+ 'page',
40
+ 'field',
28
41
  ];
29
- const WITH_VALUE = ['fill', 'type', 'select'];
42
+ /** A page's address, as the app names it (`/settings/billing`, `page/Orders/Form`): up to 200 characters, no spaces. */
43
+ const PAGE_NAME = /^\S{1,200}$/;
44
+ /**
45
+ * A field's or a command's name: one line of up to 200 characters. Whether a page has it is the project's
46
+ * controls' to say, which can then say what a name that is the screen's label is called in the model.
47
+ */
48
+ const PART_NAME = /^\S(?:[^\r\n]{0,198}\S)?$/;
49
+ const WITH_VALUE = ['fill', 'type', 'select', 'set'];
30
50
  const ON_TARGET = ['tap', 'doubleTap', 'check', 'uncheck'];
31
51
  /** An address an `open` action takes: an http(s) URL, or a path of the app that names no other scheme (`javascript:`, `file:`). */
32
52
  const ADDRESS = /^(?:https?:\/\/\S+|(?![A-Za-z][A-Za-z0-9+.-]*:)\S+)$/;
@@ -43,6 +63,8 @@ export function actionProblem(value) {
43
63
  }
44
64
  return undefined;
45
65
  }
66
+ if ('run' in value)
67
+ return runProblem(value);
46
68
  const keys = Object.keys(value);
47
69
  const kind = keys.find((k) => [...ON_TARGET, ...WITH_VALUE, 'press'].includes(k)) ?? (keys.includes('key') ? 'key' : '');
48
70
  const allowed = WITH_VALUE.includes(kind)
@@ -51,7 +73,7 @@ export function actionProblem(value) {
51
73
  ? ['press', 'key']
52
74
  : [kind];
53
75
  if (!kind)
54
- return `${JSON.stringify(value)} is no action: tap, doubleTap, fill, type, select, check, uncheck, press, key or open`;
76
+ return `${JSON.stringify(value)} is no action: tap, doubleTap, fill, type, select, check, uncheck, press, key, open, set or run`;
55
77
  const extra = keys.filter((k) => !allowed.includes(k));
56
78
  if (extra.length)
57
79
  return `${kind}: unknown key ${extra.join(', ')}`;
@@ -63,8 +85,34 @@ export function actionProblem(value) {
63
85
  }
64
86
  if (kind === 'key')
65
87
  return undefined;
88
+ if (kind === 'set' && !(isObject(value.set) && 'page' in value.set)) {
89
+ return 'set gives a page\'s field a value: { "set": { "page": "<its address>", "field": "<its name>" }, "value": "…" }';
90
+ }
66
91
  return targetProblem(value[kind]);
67
92
  }
93
+ function runProblem(value) {
94
+ const extra = Object.keys(value).filter((k) => !['run', 'answer'].includes(k));
95
+ if (extra.length)
96
+ return `run: unknown key ${extra.join(', ')}`;
97
+ const command = value.run;
98
+ if (!isObject(command) ||
99
+ Object.keys(command).some((k) => !['page', 'command'].includes(k)) ||
100
+ typeof command.page !== 'string' ||
101
+ typeof command.command !== 'string' ||
102
+ !PAGE_NAME.test(command.page) ||
103
+ !PART_NAME.test(command.command)) {
104
+ return 'run names a page\'s command: { "run": { "page": "<its address>", "command": "<its name>" } }';
105
+ }
106
+ const answer = value.answer;
107
+ if (answer !== undefined &&
108
+ !(Array.isArray(answer) &&
109
+ answer.length >= 1 &&
110
+ answer.length <= 5 &&
111
+ answer.every((a) => typeof a === 'string' && a.trim() && a.length <= 100))) {
112
+ return '"answer" lists from 1 to 5 buttons to press in what the command opens, by their names';
113
+ }
114
+ return undefined;
115
+ }
68
116
  function targetProblem(target) {
69
117
  if (!isObject(target))
70
118
  return 'an element is an object such as { "role": "button", "name": "Save" }';
@@ -77,6 +125,13 @@ function targetProblem(target) {
77
125
  }
78
126
  if (Object.values(found).some((v) => typeof v !== 'string' || !v))
79
127
  return "an element's values are text";
128
+ if (target.page !== undefined || target.field !== undefined) {
129
+ const others = Object.keys(target).filter((k) => k !== 'page' && k !== 'field');
130
+ if (others.length || !PAGE_NAME.test(String(target.page ?? '')) || !PART_NAME.test(String(target.field ?? ''))) {
131
+ return 'a field of a page is named by the two alone: { "page": "<its address>", "field": "<its name>" }';
132
+ }
133
+ return undefined;
134
+ }
80
135
  const ways = [
81
136
  target.role !== undefined && (target.name !== undefined) !== (target.nameStarts !== undefined),
82
137
  target.label !== undefined,
@@ -94,8 +149,35 @@ function targetProblem(target) {
94
149
  export function actionValue(action) {
95
150
  return 'value' in action ? action.value : undefined;
96
151
  }
97
- /** The web engine's locator for a target, inside its frame, dialog and row; the `nth` of them when it says. */
98
- export function locate(target, screen, browser) {
152
+ /** A target that names a page's field, as the project's controls take it; nothing for any other. */
153
+ export function fieldOf(target) {
154
+ return target.page !== undefined && target.field !== undefined
155
+ ? { page: target.page, field: target.field }
156
+ : undefined;
157
+ }
158
+ /** The names of the app's pages an action works by: its field's, or its command's; nothing for any other action. */
159
+ export function partOf(action) {
160
+ if ('run' in action)
161
+ return action.run;
162
+ if ('open' in action)
163
+ return undefined;
164
+ const target = Object.entries(action).find(([key]) => key !== 'value' && key !== 'key')?.[1];
165
+ return typeof target === 'object' && target !== null ? fieldOf(target) : undefined;
166
+ }
167
+ function controls(pages, what) {
168
+ if (!pages)
169
+ throw new Error(`${what} needs the project's page controls, which its plain.ts did not pass (pages)`);
170
+ return pages;
171
+ }
172
+ /**
173
+ * The web engine's locator for a target, inside its frame, dialog and row;
174
+ * the `nth` of them when it says. A page's field is the project's controls'
175
+ * to find.
176
+ */
177
+ export function locate(target, screen, browser, pages) {
178
+ const field = fieldOf(target);
179
+ if (field)
180
+ return controls(pages, describe(target)).field(field, { screen, browser });
99
181
  const all = matching(target, screen, browser);
100
182
  return target.nth === undefined
101
183
  ? all
@@ -103,12 +185,15 @@ export function locate(target, screen, browser) {
103
185
  }
104
186
  /**
105
187
  * 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,
188
+ * matches several now (an app may show a second New in a panel that opened,
107
189
  * say), the first is taken, as a hand-written test's `.first()` does, and the
108
190
  * run says so: the step's own expectations catch it when that was wrong.
109
191
  */
110
- async function element(target, screen, browser) {
111
- const found = locate(target, screen, browser);
192
+ async function element(target, screen, browser, pages) {
193
+ const found = locate(target, screen, browser, pages);
194
+ // A page's field is one element, by its name.
195
+ if (fieldOf(target))
196
+ return found;
112
197
  if (target.nth !== undefined || !found.count || !found.first)
113
198
  return found;
114
199
  const count = await found.count();
@@ -120,6 +205,8 @@ async function element(target, screen, browser) {
120
205
  /** A target as a run's warning names it: `button "New"`. */
121
206
  function describe(target) {
122
207
  const { role, name, nameStarts, label, testId, placeholder, id, text, dialog } = target;
208
+ if (target.page !== undefined)
209
+ return `the field ${target.field} of ${target.page}`;
123
210
  const what = role
124
211
  ? `${role} ${JSON.stringify(name ?? `${nameStarts}…`)}`
125
212
  : label !== undefined
@@ -159,10 +246,31 @@ function matching(target, screen, browser) {
159
246
  const AMBIGUOUS = /LOCATOR_AMBIGUOUS|matched \d+ (?:nodes|elements), expected exactly one/;
160
247
  /** How long one recorded action waits for its element before the step falls back to its sentence. */
161
248
  export const ACTION_TIMEOUT = 15_000;
162
- /** Does one recorded action, its value with the run's values in place of `{…}` (`value`). */
163
- export async function perform(action, screen, browser, value, app) {
249
+ /** How long a combobox left with Tab is waited for to check its value, before the run goes on and says so. */
250
+ export const LOOKUP_TIMEOUT = 10_000;
251
+ /**
252
+ * Does one recorded action, its value with the run's values in place of `{…}` (`value`).
253
+ *
254
+ * A combobox left with Tab checks its value with the app (a lookup: its list
255
+ * stays open until the value is found), and what is pressed meanwhile may be
256
+ * lost, as a Save is. So with the framework's `expect`, Tab on a combobox
257
+ * waits until its list has closed; one still open after `LOOKUP_TIMEOUT` is
258
+ * said, and the run goes on. Kit 0.4.1.
259
+ */
260
+ export async function perform(action, screen, browser, value, app, expect, pages) {
164
261
  if ('open' in action)
165
262
  return void (await need(app, 'opening a page', 'app').open(action.open));
263
+ // By the app's own names: the project's controls do it, waiting for what its kind of control needs.
264
+ const fixtures = { screen, browser, app, expect };
265
+ if ('run' in action) {
266
+ return controls(pages, `the command ${action.run.command} of ${action.run.page}`).run(action.run, action.answer ? { answer: action.answer } : {}, fixtures);
267
+ }
268
+ if ('set' in action) {
269
+ const field = fieldOf(action.set);
270
+ if (!field)
271
+ throw new Error("set gives a page's field a value: it needs the page and the field");
272
+ return controls(pages, describe(action.set)).set(field, value(action.value), fixtures);
273
+ }
166
274
  const timeout = { timeout: ACTION_TIMEOUT };
167
275
  /**
168
276
  * Does `act` on the target's element. One more of it may show between
@@ -170,13 +278,16 @@ export async function perform(action, screen, browser, value, app) {
170
278
  * on the first, as when there were several to begin with.
171
279
  */
172
280
  const on = async (target, act) => {
173
- const found = await element(target, screen, browser);
281
+ const found = await element(target, screen, browser, pages);
174
282
  try {
175
283
  await act(found);
176
284
  }
177
285
  catch (error) {
178
- const all = locate(target, screen, browser);
179
- if (target.nth !== undefined || !all.first || !AMBIGUOUS.test(String(error?.message ?? error))) {
286
+ const all = locate(target, screen, browser, pages);
287
+ if (fieldOf(target) ||
288
+ target.nth !== undefined ||
289
+ !all.first ||
290
+ !AMBIGUOUS.test(String(error?.message ?? error))) {
180
291
  throw error;
181
292
  }
182
293
  console.warn(`${describe(target)} matched several elements as it was done; the first is used`);
@@ -197,10 +308,26 @@ export async function perform(action, screen, browser, value, app) {
197
308
  return on(action.check, (e) => e.check(timeout));
198
309
  if ('uncheck' in action)
199
310
  return on(action.uncheck, (e) => e.uncheck(timeout));
200
- if ('press' in action)
201
- return on(action.press, (e) => e.press(action.key, timeout));
311
+ if ('press' in action) {
312
+ await on(action.press, (e) => e.press(action.key, timeout));
313
+ if (action.key === 'Tab' && action.press.role === 'combobox')
314
+ await closed(action.press, screen, browser, expect);
315
+ return;
316
+ }
202
317
  await need(browser, 'a key on whatever has focus').keyboard.press(action.key);
203
318
  }
319
+ /** Waits until a combobox left with Tab has closed its list: its value is checked. Never fails the action. */
320
+ async function closed(target, screen, browser, expect) {
321
+ if (!expect)
322
+ return;
323
+ try {
324
+ const found = await element(target, screen, browser);
325
+ await expect(found).not?.toBeExpanded?.({ timeout: LOOKUP_TIMEOUT });
326
+ }
327
+ catch {
328
+ console.warn(`${describe(target)} still has its list open ${LOOKUP_TIMEOUT / 1000} s after Tab; the run goes on without waiting for it`);
329
+ }
330
+ }
204
331
  function need(value, what, fixture = 'browser') {
205
332
  if (value === undefined)
206
333
  throw new Error(`${what} needs the ${fixture} fixture, which the runner did not pass`);
@@ -237,17 +364,18 @@ export const EXPECT_TIMEOUT = 15_000;
237
364
  * Do step's missing element does. The element showing something else fails,
238
365
  * with the framework's message: that is what the test is there to catch.
239
366
  */
240
- export async function expectOn(expectation, screen, browser, value, expect) {
367
+ export async function expectOn(expectation, screen, browser, value, expect, pages) {
241
368
  const timeout = { timeout: EXPECT_TIMEOUT };
242
- const found = locate(expectation.target, screen, browser);
369
+ const found = locate(expectation.target, screen, browser, pages);
370
+ const one = fieldOf(expectation.target) || expectation.target.nth !== undefined || !found.first;
243
371
  try {
244
- await expect(found.first && expectation.target.nth === undefined ? found.first() : found).toBeVisible(timeout);
372
+ await expect(one ? found : found.first()).toBeVisible(timeout);
245
373
  }
246
374
  catch {
247
375
  return 'missing';
248
376
  }
249
377
  // 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);
378
+ const shown = await element(expectation.target, screen, browser, pages);
251
379
  if (expectation.matcher === 'toBeVisible')
252
380
  return 'held';
253
381
  await expect(shown)[expectation.matcher](value(expectation.value), timeout);
@@ -17,7 +17,7 @@
17
17
  *
18
18
  * e2e Studio edits the same files on its Settings page, item by item.
19
19
  */
20
- /** A record as a lookup shows it: `M-CMB - MASS Colombo`. */
20
+ /** A record as a field that searches shows it, by its code and name: `S-01 - Main Site`. */
21
21
  export interface CodeAndName {
22
22
  readonly code: string;
23
23
  readonly name: string;
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 AppLike, type BrowserLike, type CheckExpectation, EXPECT_TIMEOUT, type ExpectLike, type LocatorLike, locate, MATCHERS, type ScreenLike, type StepAction, type StepTarget, } from './actions.ts';
12
+ export { ACTION_TIMEOUT, type AppLike, type BrowserLike, type CheckExpectation, type CommandRef, type ControlFixtures, EXPECT_TIMEOUT, type ExpectLike, type FieldRef, fieldOf, type LocatorLike, locate, MATCHERS, type PageControls, partOf, 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, EXPECT_TIMEOUT, locate, MATCHERS, } from './actions.js';
12
+ export { ACTION_TIMEOUT, EXPECT_TIMEOUT, fieldOf, locate, MATCHERS, partOf, } 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
@@ -6,15 +6,15 @@
6
6
  *
7
7
  * ```json
8
8
  * {
9
- * "title": "a transferred task shows in My Work",
9
+ * "title": "a confirmed order shows in Orders",
10
10
  * "requires": ["someFeature"],
11
11
  * "steps": [
12
- * { "block": "work-order-with-task", "as": "work1", "with": { "description": "Pump leaking" } },
13
- * { "block": "send-to-mobile", "with": { "work": "{work1}" } },
14
- * { "do": "Search for {work1.description}" },
12
+ * { "block": "order-with-line", "as": "order1", "with": { "description": "Two pumps" } },
13
+ * { "block": "confirm-order", "with": { "order": "{order1}" } },
14
+ * { "do": "Search for {order1.description}" },
15
15
  * { "waitUntil": "The list has finished loading" },
16
- * { "check": "Assignment {work1.reference} is listed at {basic.site.name}", "when": "!someFeature" },
17
- * { "verify": "work-assignment-state", "with": { "work": "{work1}", "state": "Assigned" } }
16
+ * { "check": "Order {order1.reference} is listed at {basic.site.name}", "when": "!someFeature" },
17
+ * { "verify": "order-state", "with": { "order": "{order1}", "state": "Confirmed" } }
18
18
  * ]
19
19
  * }
20
20
  * ```
@@ -51,7 +51,7 @@
51
51
  * }
52
52
  * ```
53
53
  */
54
- import { type AppLike, type BrowserLike, type CheckExpectation, type ExpectLike, type ScreenLike, type StepAction } from './actions.ts';
54
+ import { type AppLike, type BrowserLike, type CheckExpectation, type ExpectLike, type PageControls, 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?: {
@@ -89,6 +89,13 @@ export interface PlainOptions {
89
89
  };
90
90
  /** The instance's basic data, by item and field, for `{basic.<item>.<field>}`; see `readBasicData`. */
91
91
  readonly basicData?: () => Readonly<Record<string, object>>;
92
+ /**
93
+ * The app's pages, as the project's own controls work on them: what a
94
+ * step's `set` and `run` actions are done with, and what finds a field an
95
+ * expectation reads, by the names the app's model gives them. Without
96
+ * them, a steps file may use neither. Kit 0.5.0.
97
+ */
98
+ readonly pages?: PageControls;
92
99
  }
93
100
  /** A step's own condition: run it only with `feature`, or only without it. */
94
101
  export interface Condition {
package/dist/plain.js CHANGED
@@ -6,15 +6,15 @@
6
6
  *
7
7
  * ```json
8
8
  * {
9
- * "title": "a transferred task shows in My Work",
9
+ * "title": "a confirmed order shows in Orders",
10
10
  * "requires": ["someFeature"],
11
11
  * "steps": [
12
- * { "block": "work-order-with-task", "as": "work1", "with": { "description": "Pump leaking" } },
13
- * { "block": "send-to-mobile", "with": { "work": "{work1}" } },
14
- * { "do": "Search for {work1.description}" },
12
+ * { "block": "order-with-line", "as": "order1", "with": { "description": "Two pumps" } },
13
+ * { "block": "confirm-order", "with": { "order": "{order1}" } },
14
+ * { "do": "Search for {order1.description}" },
15
15
  * { "waitUntil": "The list has finished loading" },
16
- * { "check": "Assignment {work1.reference} is listed at {basic.site.name}", "when": "!someFeature" },
17
- * { "verify": "work-assignment-state", "with": { "work": "{work1}", "state": "Assigned" } }
16
+ * { "check": "Order {order1.reference} is listed at {basic.site.name}", "when": "!someFeature" },
17
+ * { "verify": "order-state", "with": { "order": "{order1}", "state": "Confirmed" } }
18
18
  * ]
19
19
  * }
20
20
  * ```
@@ -63,7 +63,7 @@ import { existsSync, readFileSync } from 'node:fs';
63
63
  import path from 'node:path';
64
64
  import { fileURLToPath, pathToFileURL } from 'node:url';
65
65
  import { expect as e2eExpect, unique } from 'e2e';
66
- import { actionProblem, actionValue, expectationProblem, expectOn, perform, } from './actions.js';
66
+ import { actionProblem, actionValue, expectationProblem, expectOn, fieldOf, partOf, 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';
@@ -140,6 +140,17 @@ export function parsePlainTest(json, context, options = {}) {
140
140
  }
141
141
  }
142
142
  };
143
+ /** A page's field or command a step names: the project's controls say whether the page has it. */
144
+ const checkPart = (where, part) => {
145
+ if (!part)
146
+ return;
147
+ if (!options.pages) {
148
+ throw fail(where, "works on a page by its own names, which needs the project's page controls (pages)");
149
+ }
150
+ const problem = options.pages.problem(part);
151
+ if (problem)
152
+ throw fail(where, problem);
153
+ };
143
154
  const parsed = steps.map((raw, index) => {
144
155
  const where = ` step ${index + 1}`;
145
156
  if (!isObject(raw))
@@ -176,6 +187,7 @@ export function parsePlainTest(json, context, options = {}) {
176
187
  const problem = actionProblem(action);
177
188
  if (problem)
178
189
  throw fail(`${where} action ${at + 1}`, problem);
190
+ checkPart(`${where} action ${at + 1}`, partOf(action));
179
191
  const typed = actionValue(action);
180
192
  if (typed)
181
193
  checkTokens(`${where} action ${at + 1}`, typed, false);
@@ -192,6 +204,7 @@ export function parsePlainTest(json, context, options = {}) {
192
204
  const problem = expectationProblem(expectation);
193
205
  if (problem)
194
206
  throw fail(`${where} expectation ${at + 1}`, problem);
207
+ checkPart(`${where} expectation ${at + 1}`, fieldOf(expectation.target));
195
208
  const shown = expectation.value;
196
209
  if (shown)
197
210
  checkTokens(`${where} expectation ${at + 1}`, shown, false);
@@ -293,6 +306,7 @@ export async function runSteps(fixtures, test, options = {}) {
293
306
  return value === undefined ? result : result?.[value];
294
307
  };
295
308
  const text = (sentence) => sentence.replace(TOKEN, (token, name, value, field) => String(lookUp(token, name, value, field) ?? ''));
309
+ await preparePages(test, options, has);
296
310
  for (const [index, step] of test.steps.entries()) {
297
311
  if (step.when && has(step.when.feature) !== step.when.present)
298
312
  continue;
@@ -333,7 +347,7 @@ export async function runSteps(fixtures, test, options = {}) {
333
347
  let done = false;
334
348
  try {
335
349
  for (const action of step.actions)
336
- await perform(action, screen, browser, text, app);
350
+ await perform(action, screen, browser, text, app, expect, options.pages);
337
351
  done = true;
338
352
  }
339
353
  catch (error) {
@@ -345,7 +359,7 @@ export async function runSteps(fixtures, test, options = {}) {
345
359
  for (const expectation of step.expect) {
346
360
  let settled;
347
361
  try {
348
- settled = await expectOn(expectation, screen, browser, text, expect);
362
+ settled = await expectOn(expectation, screen, browser, text, expect, options.pages);
349
363
  }
350
364
  catch (error) {
351
365
  const why = error instanceof Error ? error.message : String(error);
@@ -372,7 +386,7 @@ export async function runSteps(fixtures, test, options = {}) {
372
386
  let missing = false;
373
387
  for (const expectation of step.expect) {
374
388
  try {
375
- missing = (await expectOn(expectation, screen, browser, text, expect)) === 'missing';
389
+ missing = (await expectOn(expectation, screen, browser, text, expect, options.pages)) === 'missing';
376
390
  }
377
391
  catch (error) {
378
392
  const why = error instanceof Error ? error.message : String(error);
@@ -392,13 +406,52 @@ export async function runSteps(fixtures, test, options = {}) {
392
406
  }
393
407
  }
394
408
  }
409
+ /**
410
+ * Before the first step: the project gets ready the pages the steps that
411
+ * will run name (`PageControls.prepare`), and every field and command they
412
+ * name is checked against them once more, now that the project knows its
413
+ * pages as this run has them. A name a page does not have fails the test
414
+ * here, by file and step, with nothing done on the screen.
415
+ */
416
+ async function preparePages(test, options, has) {
417
+ const named = [];
418
+ for (const [index, step] of test.steps.entries()) {
419
+ if (!('text' in step))
420
+ continue;
421
+ if (step.when && has(step.when.feature) !== step.when.present)
422
+ continue;
423
+ for (const [at, action] of (step.actions ?? []).entries()) {
424
+ const part = partOf(action);
425
+ if (part)
426
+ named.push({ where: `step ${index + 1} action ${at + 1}`, part });
427
+ }
428
+ for (const [at, expectation] of (step.expect ?? []).entries()) {
429
+ const part = fieldOf(expectation.target);
430
+ if (part)
431
+ named.push({ where: `step ${index + 1} expectation ${at + 1}`, part });
432
+ }
433
+ }
434
+ if (named.length === 0 || !options.pages)
435
+ return;
436
+ try {
437
+ await options.pages.prepare?.([...new Set(named.map((n) => n.part.page))]);
438
+ }
439
+ catch (error) {
440
+ throw new Error(`${test.file}: ${error instanceof Error ? error.message : error}`, { cause: error });
441
+ }
442
+ for (const { where, part } of named) {
443
+ const problem = options.pages.problem(part);
444
+ if (problem)
445
+ throw new Error(`${test.file} ${where}: ${problem}`);
446
+ }
447
+ }
395
448
  /**
396
449
  * A `do` step's params: the values its sentence names, and every block result
397
450
  * so far besides, since the screen the step ends on may show any of them. The
398
451
  * replay cache swaps a `unique()` value for the run's own, so block results
399
452
  * go in as `unique()`; basic data, the same on every run, as is. A result the
400
453
  * sentence leaves out is left out too when it sits inside another value (a
401
- * work order number inside its reference): the cache records no step whose
454
+ * an order's number inside its reference): the cache records no step whose
402
455
  * `unique()` value sits inside another param.
403
456
  */
404
457
  function actParams(named, results) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@testra-studio/kit",
3
- "version": "0.4.0",
3
+ "version": "0.5.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",
@@ -163,7 +163,7 @@
163
163
  },
164
164
  "target": {
165
165
  "type": "object",
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).",
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); or a field of one of the app's pages, by the names the app's own model gives them, which the project's controls find (kit 0.5.0): its page and its field alone.",
167
167
  "additionalProperties": false,
168
168
  "properties": {
169
169
  "role": {
@@ -216,6 +216,16 @@
216
216
  "minimum": 0,
217
217
  "maximum": 99,
218
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."
219
+ },
220
+ "page": {
221
+ "type": "string",
222
+ "pattern": "^\\S{1,200}$",
223
+ "description": "The page's address in the app, as the app's own model names it. With \"field\", and nothing else. Needs @testra-studio/kit 0.5.0 or later."
224
+ },
225
+ "field": {
226
+ "type": "string",
227
+ "pattern": "^\\S(?:[^\\r\\n]{0,198}\\S)?$",
228
+ "description": "The field's name on that page, as the app's own model names it."
219
229
  }
220
230
  },
221
231
  "oneOf": [
@@ -240,6 +250,12 @@
240
250
  },
241
251
  {
242
252
  "required": ["text"]
253
+ },
254
+ {
255
+ "required": ["page"]
256
+ },
257
+ {
258
+ "required": ["field"]
243
259
  }
244
260
  ]
245
261
  }
@@ -265,6 +281,12 @@
265
281
  },
266
282
  {
267
283
  "required": ["text"]
284
+ },
285
+ {
286
+ "required": ["page"]
287
+ },
288
+ {
289
+ "required": ["field"]
268
290
  }
269
291
  ]
270
292
  }
@@ -287,6 +309,12 @@
287
309
  },
288
310
  {
289
311
  "required": ["text"]
312
+ },
313
+ {
314
+ "required": ["page"]
315
+ },
316
+ {
317
+ "required": ["field"]
290
318
  }
291
319
  ]
292
320
  }
@@ -309,6 +337,12 @@
309
337
  },
310
338
  {
311
339
  "required": ["text"]
340
+ },
341
+ {
342
+ "required": ["page"]
343
+ },
344
+ {
345
+ "required": ["field"]
312
346
  }
313
347
  ]
314
348
  }
@@ -331,6 +365,12 @@
331
365
  },
332
366
  {
333
367
  "required": ["text"]
368
+ },
369
+ {
370
+ "required": ["page"]
371
+ },
372
+ {
373
+ "required": ["field"]
334
374
  }
335
375
  ]
336
376
  }
@@ -353,6 +393,12 @@
353
393
  },
354
394
  {
355
395
  "required": ["text"]
396
+ },
397
+ {
398
+ "required": ["page"]
399
+ },
400
+ {
401
+ "required": ["field"]
356
402
  }
357
403
  ]
358
404
  }
@@ -375,9 +421,19 @@
375
421
  },
376
422
  {
377
423
  "required": ["id"]
424
+ },
425
+ {
426
+ "required": ["page"]
427
+ },
428
+ {
429
+ "required": ["field"]
378
430
  }
379
431
  ]
380
432
  }
433
+ },
434
+ {
435
+ "required": ["page", "field"],
436
+ "maxProperties": 2
381
437
  }
382
438
  ]
383
439
  },
@@ -508,6 +564,64 @@
508
564
  "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
565
  }
510
566
  }
567
+ },
568
+ {
569
+ "type": "object",
570
+ "required": ["set", "value"],
571
+ "additionalProperties": false,
572
+ "description": "Gives a page's field a value the way its control takes one, through the project's controls, which wait until it holds it. Needs @testra-studio/kit 0.5.0 or later.",
573
+ "properties": {
574
+ "set": {
575
+ "allOf": [
576
+ {
577
+ "$ref": "#/$defs/target"
578
+ },
579
+ {
580
+ "required": ["page", "field"]
581
+ }
582
+ ]
583
+ },
584
+ "value": {
585
+ "type": "string",
586
+ "maxLength": 500
587
+ }
588
+ }
589
+ },
590
+ {
591
+ "type": "object",
592
+ "required": ["run"],
593
+ "additionalProperties": false,
594
+ "description": "Runs a page's command through the project's controls, which wait until it is done. Needs @testra-studio/kit 0.5.0 or later.",
595
+ "properties": {
596
+ "run": {
597
+ "type": "object",
598
+ "required": ["page", "command"],
599
+ "additionalProperties": false,
600
+ "properties": {
601
+ "page": {
602
+ "type": "string",
603
+ "pattern": "^\\S{1,200}$",
604
+ "description": "The page's address in the app."
605
+ },
606
+ "command": {
607
+ "type": "string",
608
+ "pattern": "^\\S(?:[^\\r\\n]{0,198}\\S)?$",
609
+ "description": "The command's name on that page, as the app's own model names it."
610
+ }
611
+ }
612
+ },
613
+ "answer": {
614
+ "type": "array",
615
+ "minItems": 1,
616
+ "maxItems": 5,
617
+ "items": {
618
+ "type": "string",
619
+ "minLength": 1,
620
+ "maxLength": 100
621
+ },
622
+ "description": "The buttons to press in what the command opens before it is done (a confirmation, a check the app makes before it saves), by their names: the first of them it shows is pressed."
623
+ }
624
+ }
511
625
  }
512
626
  ]
513
627
  },