@testra-studio/kit 0.0.0-stage → 0.2.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/dist/studio.js ADDED
@@ -0,0 +1,93 @@
1
+ /**
2
+ * Running on what e2e Studio gives a run: one of its browsers, or a device
3
+ * it leased.
4
+ *
5
+ * A web run the Studio starts gets the browser it hosts in
6
+ * `E2E_STUDIO_CDP`: connected to it, the run can be watched live in the
7
+ * Studio. `studioBrowser()` is the web engine's options for that:
8
+ *
9
+ * engine: web({ ...studioBrowser() })
10
+ *
11
+ * A mobile run the Studio starts gets its device as JSON in
12
+ * `E2E_STUDIO_DEVICE`: a phone, emulator or simulator on a tester's machine,
13
+ * which runs the Studio's device host. The run drives it through the
14
+ * Studio, which relays agent-device's requests to that machine; nothing of
15
+ * the device is on the machine the run is on, not even adb.
16
+ *
17
+ * engine: mobile({ platform: 'android', device: studioLease() ? studioDevice() : process.env.ANDROID_SERIAL })
18
+ */
19
+ /** Where the Studio puts the address of the browser a web run drives. */
20
+ export const STUDIO_BROWSER_ENV = 'E2E_STUDIO_CDP';
21
+ /**
22
+ * The web engine's options for a run the Studio started: connect to the
23
+ * browser it hosts, so the run can be watched live there. None for any
24
+ * other run, which launches a browser of its own.
25
+ */
26
+ export function studioBrowser(env = process.env) {
27
+ const endpoint = env[STUDIO_BROWSER_ENV];
28
+ return endpoint ? { connect: { cdpEndpoint: () => endpoint } } : {};
29
+ }
30
+ /** Where the Studio puts the lease, unless the project's `mobile.leaseEnv` says otherwise. */
31
+ export const STUDIO_DEVICE_ENV = 'E2E_STUDIO_DEVICE';
32
+ /** The run's lease, or `undefined` when the Studio did not start it on a device host. */
33
+ export function studioLease(env = process.env) {
34
+ const raw = env[STUDIO_DEVICE_ENV];
35
+ if (!raw)
36
+ return undefined;
37
+ const lease = JSON.parse(raw);
38
+ if (typeof lease.id !== 'string' ||
39
+ typeof lease.deviceId !== 'string' ||
40
+ typeof lease.daemon?.baseUrl !== 'string' ||
41
+ typeof lease.daemon.authToken !== 'string') {
42
+ throw new Error(`${STUDIO_DEVICE_ENV} is not a Testra Studio device lease`);
43
+ }
44
+ return lease;
45
+ }
46
+ /**
47
+ * The mobile engine's `device` for a run on a Studio device: the one device
48
+ * the Studio leased the run, driven through the Studio. The Studio frees it
49
+ * when the run ends, so `release` has nothing to do.
50
+ */
51
+ export function studioDevice() {
52
+ return {
53
+ name: 'Testra Studio',
54
+ async acquire(request) {
55
+ const lease = studioLease(request.env);
56
+ if (!lease) {
57
+ throw new Error(`no device lease in ${STUDIO_DEVICE_ENV}: studioDevice() is for runs Testra Studio starts`);
58
+ }
59
+ if (lease.platform !== request.platform) {
60
+ throw new Error(`the Studio leased an ${lease.platform} device to a ${request.platform} target`);
61
+ }
62
+ if (request.slots > 1) {
63
+ throw new Error('Testra Studio leases one device per run; set workers: 1');
64
+ }
65
+ if (lease.agentDevice && lease.agentDevice !== request.agentDeviceVersion) {
66
+ request.log(`device host ${lease.hostName} runs agent-device ${lease.agentDevice} and this run ${request.agentDeviceVersion}; if commands misbehave, bring the one behind up to date`);
67
+ }
68
+ request.log(`${lease.device} (${lease.deviceId}) on ${lease.hostName}`);
69
+ return { id: lease.id, deviceId: lease.deviceId, daemon: lease.daemon };
70
+ },
71
+ async release() { },
72
+ };
73
+ }
74
+ /**
75
+ * Runs `adb shell <args>` on a Studio-leased Android device, on the device
76
+ * host's machine. Resolves with its output; rejects when it exits non-zero.
77
+ */
78
+ export async function studioAdbShell(lease, args) {
79
+ if (!lease.adb)
80
+ throw new Error(`${lease.device} is no Android device; adb runs on Android devices only`);
81
+ const response = await fetch(lease.adb, {
82
+ method: 'POST',
83
+ headers: { authorization: `Bearer ${lease.daemon.authToken}`, 'content-type': 'application/json' },
84
+ body: JSON.stringify({ args: ['shell', ...args] }),
85
+ });
86
+ if (!response.ok)
87
+ throw new Error(`adb shell through Testra Studio: ${response.status} ${await response.text()}`);
88
+ const result = (await response.json());
89
+ if (result.code !== 0) {
90
+ throw Object.assign(new Error(`adb shell ${args.join(' ')} exited ${result.code}: ${result.stderr.trim()}`), result);
91
+ }
92
+ return result.stdout;
93
+ }
package/package.json CHANGED
@@ -1,6 +1,48 @@
1
1
  {
2
2
  "name": "@testra-studio/kit",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0",
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
+ "type": "module",
6
+ "license": "MIT",
7
+ "files": [
8
+ "dist",
9
+ "schemas",
10
+ "README.md",
11
+ "CHANGELOG.md",
12
+ "LICENSE"
13
+ ],
14
+ "exports": {
15
+ ".": {
16
+ "types": "./dist/index.d.ts",
17
+ "default": "./dist/index.js"
18
+ },
19
+ "./schemas/*": "./schemas/*",
20
+ "./package.json": "./package.json"
21
+ },
22
+ "scripts": {
23
+ "build": "rm -rf dist && tsc -p tsconfig.build.json",
24
+ "test": "node --disable-warning=ExperimentalWarning --test \"test/**/*.test.ts\"",
25
+ "prepack": "npm run build"
26
+ },
27
+ "peerDependencies": {
28
+ "@e2e-dev/mobile": "^0.12.4",
29
+ "e2e": "^0.21.3"
30
+ },
31
+ "peerDependenciesMeta": {
32
+ "@e2e-dev/mobile": {
33
+ "optional": true
34
+ }
35
+ },
36
+ "devDependencies": {
37
+ "@e2e-dev/mobile": "0.12.4"
38
+ },
39
+ "publishConfig": {
40
+ "access": "public"
41
+ },
42
+ "keywords": [
43
+ "e2e",
44
+ "testing",
45
+ "e2e-studio",
46
+ "plain-english-tests"
47
+ ]
48
+ }
@@ -0,0 +1,87 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://testra-studio/schemas/basic-data.items.schema.json",
4
+ "title": "The kinds of basic data",
5
+ "description": "basic-data.items.json, in a folder of instance files: every kind of basic data (existing records tests work with, each a code and a name), and where an instance lists each, for the Studio to pick and check values. Addresses take {serverUrl} and the instance file's other values, such as {realm}.",
6
+ "type": "object",
7
+ "required": ["items"],
8
+ "properties": {
9
+ "$schema": { "type": "string" },
10
+ "$comment": { "type": "string" },
11
+ "source": {
12
+ "type": "object",
13
+ "description": "Where instances list their records: an OData service. Without it, values are typed in.",
14
+ "required": ["odata"],
15
+ "additionalProperties": false,
16
+ "properties": {
17
+ "odata": { "$ref": "#/$defs/address", "description": "The OData service the lookups' entity sets are under." },
18
+ "signIn": {
19
+ "type": "object",
20
+ "description": "An OpenID Connect password grant, for a bearer token.",
21
+ "required": ["tokenUrl", "clientId"],
22
+ "additionalProperties": false,
23
+ "properties": {
24
+ "tokenUrl": { "$ref": "#/$defs/address" },
25
+ "clientId": { "type": "string", "minLength": 1 },
26
+ "clientIdFrom": {
27
+ "$ref": "#/$defs/variable",
28
+ "description": "A credential that, when kept for the instance, is the client id instead."
29
+ },
30
+ "scope": { "type": "string", "default": "openid" },
31
+ "realmFrom": {
32
+ "$ref": "#/$defs/address",
33
+ "description": "An address that, asked without a token, names {realm} in its WWW-Authenticate header, as Keycloak does; used when the instance's file gives no realm."
34
+ }
35
+ }
36
+ },
37
+ "credentials": {
38
+ "type": "array",
39
+ "description": "The credentials to sign in with, by the names the Studio keeps them under for an instance; the first pair kept is used.",
40
+ "items": {
41
+ "type": "object",
42
+ "required": ["username", "password"],
43
+ "additionalProperties": false,
44
+ "properties": { "username": { "$ref": "#/$defs/variable" }, "password": { "$ref": "#/$defs/variable" } }
45
+ }
46
+ }
47
+ }
48
+ },
49
+ "items": {
50
+ "type": "object",
51
+ "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
52
+ "additionalProperties": {
53
+ "type": "object",
54
+ "required": ["label"],
55
+ "additionalProperties": false,
56
+ "properties": {
57
+ "label": { "type": "string", "minLength": 1 },
58
+ "help": { "type": "string" },
59
+ "lookup": {
60
+ "type": "object",
61
+ "required": ["set", "code", "name"],
62
+ "additionalProperties": false,
63
+ "properties": {
64
+ "set": {
65
+ "type": "string",
66
+ "pattern": "^[A-Za-z0-9_][A-Za-z0-9_./-]*$",
67
+ "description": "The entity set under the service: Customers, or Orders.svc/Customers."
68
+ },
69
+ "code": { "$ref": "#/$defs/name" },
70
+ "name": { "$ref": "#/$defs/name" },
71
+ "filter": {
72
+ "type": "string",
73
+ "maxLength": 1000,
74
+ "description": "An OData filter; {site.code} is another item's value."
75
+ }
76
+ }
77
+ }
78
+ }
79
+ }
80
+ }
81
+ },
82
+ "$defs": {
83
+ "address": { "type": "string", "pattern": "^(https?://|\\{serverUrl\\})\\S*$" },
84
+ "variable": { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]*$" },
85
+ "name": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }
86
+ }
87
+ }
@@ -0,0 +1,31 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://testra-studio/schemas/instance.schema.json",
4
+ "title": "An instance",
5
+ "description": "One file a parameter's options are read from, such as environments/<name>.json. The Studio reads the values below; any others are the project's own, such as the attributes its config names (a track) and the values its basic data's addresses take (a realm).",
6
+ "type": "object",
7
+ "properties": {
8
+ "$schema": { "type": "string" },
9
+ "serverUrl": {
10
+ "type": "string",
11
+ "pattern": "^https?://\\S+$",
12
+ "description": "The instance as the Studio's machine reaches it: where recordings start, and what Check and basic data lookups ask."
13
+ },
14
+ "deviceServerUrl": {
15
+ "type": "string",
16
+ "pattern": "^https?://\\S+$",
17
+ "description": "The instance as a device or emulator reaches it, when that differs."
18
+ },
19
+ "basicData": {
20
+ "type": "object",
21
+ "description": "The instance's own basic data, over the shared basic-data.json; the items are basic-data.items.json's.",
22
+ "additionalProperties": {
23
+ "type": "object",
24
+ "required": ["code", "name"],
25
+ "additionalProperties": false,
26
+ "properties": { "code": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 } }
27
+ }
28
+ }
29
+ },
30
+ "additionalProperties": true
31
+ }
@@ -0,0 +1,429 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://testra-studio/schemas/steps.schema.json",
4
+ "title": "A plain-English test",
5
+ "description": "A test's steps, in <name>.steps.json beside the <name>.e2e.ts that runs them. An AI agent carries out each \"do\", judges each \"check\" against the screen, and waits for each \"waitUntil\"; \"block\" and \"verify\" call the project's building blocks and checks (e2e-studio.blocks.json). In a sentence, {work1.description} is a value an earlier block returned, and {basic.site.code} the instance's basic data. A Do step recorded in e2e Studio keeps its \"actions\", done on the exact elements, with its sentence as the fallback.",
6
+ "type": "object",
7
+ "required": ["title", "steps"],
8
+ "additionalProperties": false,
9
+ "properties": {
10
+ "$schema": {
11
+ "type": "string"
12
+ },
13
+ "title": {
14
+ "type": "string",
15
+ "minLength": 1,
16
+ "description": "What the test proves, as a sentence."
17
+ },
18
+ "requires": {
19
+ "type": "array",
20
+ "items": {
21
+ "type": "string"
22
+ },
23
+ "description": "Features the system under test must have; the project's runner skips the test without them."
24
+ },
25
+ "steps": {
26
+ "type": "array",
27
+ "minItems": 1,
28
+ "items": {
29
+ "$ref": "#/$defs/step"
30
+ }
31
+ }
32
+ },
33
+ "$defs": {
34
+ "sentence": {
35
+ "type": "string",
36
+ "minLength": 1,
37
+ "maxLength": 500,
38
+ "pattern": "^[^\\n]*$"
39
+ },
40
+ "when": {
41
+ "type": "string",
42
+ "pattern": "^!?[A-Za-z_][A-Za-z0-9_]*$",
43
+ "description": "Only with this feature, or only without it (\"!feature\")."
44
+ },
45
+ "fields": {
46
+ "type": "object",
47
+ "additionalProperties": {
48
+ "type": "string"
49
+ },
50
+ "description": "The call's fields by name; a field that takes an earlier block's result is \"{work1}\"."
51
+ },
52
+ "step": {
53
+ "oneOf": [
54
+ {
55
+ "type": "object",
56
+ "required": ["do"],
57
+ "additionalProperties": false,
58
+ "properties": {
59
+ "do": {
60
+ "$ref": "#/$defs/sentence"
61
+ },
62
+ "when": {
63
+ "$ref": "#/$defs/when"
64
+ },
65
+ "actions": {
66
+ "type": "array",
67
+ "minItems": 1,
68
+ "maxItems": 30,
69
+ "items": {
70
+ "$ref": "#/$defs/action"
71
+ },
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
+ }
75
+ },
76
+ {
77
+ "type": "object",
78
+ "required": ["check"],
79
+ "additionalProperties": false,
80
+ "properties": {
81
+ "check": {
82
+ "$ref": "#/$defs/sentence"
83
+ },
84
+ "when": {
85
+ "$ref": "#/$defs/when"
86
+ }
87
+ }
88
+ },
89
+ {
90
+ "type": "object",
91
+ "required": ["waitUntil"],
92
+ "additionalProperties": false,
93
+ "properties": {
94
+ "waitUntil": {
95
+ "$ref": "#/$defs/sentence"
96
+ },
97
+ "when": {
98
+ "$ref": "#/$defs/when"
99
+ }
100
+ }
101
+ },
102
+ {
103
+ "type": "object",
104
+ "required": ["block"],
105
+ "additionalProperties": false,
106
+ "properties": {
107
+ "block": {
108
+ "type": "string",
109
+ "description": "A building block's id."
110
+ },
111
+ "as": {
112
+ "type": "string",
113
+ "pattern": "^[a-z][A-Za-z0-9]*$",
114
+ "description": "What later steps call its result: work1."
115
+ },
116
+ "with": {
117
+ "$ref": "#/$defs/fields"
118
+ },
119
+ "when": {
120
+ "$ref": "#/$defs/when"
121
+ }
122
+ }
123
+ },
124
+ {
125
+ "type": "object",
126
+ "required": ["verify"],
127
+ "additionalProperties": false,
128
+ "properties": {
129
+ "verify": {
130
+ "type": "string",
131
+ "description": "A check's id."
132
+ },
133
+ "with": {
134
+ "$ref": "#/$defs/fields"
135
+ },
136
+ "when": {
137
+ "$ref": "#/$defs/when"
138
+ }
139
+ }
140
+ }
141
+ ]
142
+ },
143
+ "target": {
144
+ "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.",
146
+ "additionalProperties": false,
147
+ "properties": {
148
+ "role": {
149
+ "type": "string",
150
+ "pattern": "^[a-z]+$"
151
+ },
152
+ "name": {
153
+ "type": "string",
154
+ "minLength": 1
155
+ },
156
+ "nameStarts": {
157
+ "type": "string",
158
+ "minLength": 1
159
+ },
160
+ "testId": {
161
+ "type": "string",
162
+ "minLength": 1
163
+ },
164
+ "placeholder": {
165
+ "type": "string",
166
+ "minLength": 1
167
+ },
168
+ "id": {
169
+ "type": "string",
170
+ "minLength": 1
171
+ },
172
+ "text": {
173
+ "type": "string",
174
+ "minLength": 1
175
+ },
176
+ "dialog": {
177
+ "type": "string",
178
+ "minLength": 1
179
+ },
180
+ "row": {
181
+ "type": "string",
182
+ "minLength": 1
183
+ },
184
+ "frame": {
185
+ "type": "string",
186
+ "minLength": 1
187
+ }
188
+ },
189
+ "oneOf": [
190
+ {
191
+ "required": ["role", "name"],
192
+ "not": {
193
+ "anyOf": [
194
+ {
195
+ "required": ["nameStarts"]
196
+ },
197
+ {
198
+ "required": ["testId"]
199
+ },
200
+ {
201
+ "required": ["placeholder"]
202
+ },
203
+ {
204
+ "required": ["id"]
205
+ },
206
+ {
207
+ "required": ["text"]
208
+ }
209
+ ]
210
+ }
211
+ },
212
+ {
213
+ "required": ["role", "nameStarts"],
214
+ "not": {
215
+ "anyOf": [
216
+ {
217
+ "required": ["name"]
218
+ },
219
+ {
220
+ "required": ["testId"]
221
+ },
222
+ {
223
+ "required": ["placeholder"]
224
+ },
225
+ {
226
+ "required": ["id"]
227
+ },
228
+ {
229
+ "required": ["text"]
230
+ }
231
+ ]
232
+ }
233
+ },
234
+ {
235
+ "required": ["testId"],
236
+ "not": {
237
+ "anyOf": [
238
+ {
239
+ "required": ["role"]
240
+ },
241
+ {
242
+ "required": ["placeholder"]
243
+ },
244
+ {
245
+ "required": ["id"]
246
+ },
247
+ {
248
+ "required": ["text"]
249
+ }
250
+ ]
251
+ }
252
+ },
253
+ {
254
+ "required": ["placeholder"],
255
+ "not": {
256
+ "anyOf": [
257
+ {
258
+ "required": ["role"]
259
+ },
260
+ {
261
+ "required": ["testId"]
262
+ },
263
+ {
264
+ "required": ["id"]
265
+ },
266
+ {
267
+ "required": ["text"]
268
+ }
269
+ ]
270
+ }
271
+ },
272
+ {
273
+ "required": ["id"],
274
+ "not": {
275
+ "anyOf": [
276
+ {
277
+ "required": ["role"]
278
+ },
279
+ {
280
+ "required": ["testId"]
281
+ },
282
+ {
283
+ "required": ["placeholder"]
284
+ },
285
+ {
286
+ "required": ["text"]
287
+ }
288
+ ]
289
+ }
290
+ },
291
+ {
292
+ "required": ["text"],
293
+ "not": {
294
+ "anyOf": [
295
+ {
296
+ "required": ["role"]
297
+ },
298
+ {
299
+ "required": ["testId"]
300
+ },
301
+ {
302
+ "required": ["placeholder"]
303
+ },
304
+ {
305
+ "required": ["id"]
306
+ }
307
+ ]
308
+ }
309
+ }
310
+ ]
311
+ },
312
+ "action": {
313
+ "description": "One thing a recorded Do step did, on the exact element.",
314
+ "oneOf": [
315
+ {
316
+ "type": "object",
317
+ "required": ["tap"],
318
+ "additionalProperties": false,
319
+ "properties": {
320
+ "tap": {
321
+ "$ref": "#/$defs/target"
322
+ }
323
+ }
324
+ },
325
+ {
326
+ "type": "object",
327
+ "required": ["doubleTap"],
328
+ "additionalProperties": false,
329
+ "properties": {
330
+ "doubleTap": {
331
+ "$ref": "#/$defs/target"
332
+ }
333
+ }
334
+ },
335
+ {
336
+ "type": "object",
337
+ "required": ["fill", "value"],
338
+ "additionalProperties": false,
339
+ "properties": {
340
+ "fill": {
341
+ "$ref": "#/$defs/target"
342
+ },
343
+ "value": {
344
+ "type": "string",
345
+ "maxLength": 500
346
+ }
347
+ }
348
+ },
349
+ {
350
+ "type": "object",
351
+ "required": ["type", "value"],
352
+ "additionalProperties": false,
353
+ "properties": {
354
+ "type": {
355
+ "$ref": "#/$defs/target"
356
+ },
357
+ "value": {
358
+ "type": "string",
359
+ "maxLength": 500,
360
+ "minLength": 1
361
+ }
362
+ }
363
+ },
364
+ {
365
+ "type": "object",
366
+ "required": ["select", "value"],
367
+ "additionalProperties": false,
368
+ "properties": {
369
+ "select": {
370
+ "$ref": "#/$defs/target"
371
+ },
372
+ "value": {
373
+ "type": "string",
374
+ "maxLength": 500,
375
+ "minLength": 1
376
+ }
377
+ }
378
+ },
379
+ {
380
+ "type": "object",
381
+ "required": ["check"],
382
+ "additionalProperties": false,
383
+ "properties": {
384
+ "check": {
385
+ "$ref": "#/$defs/target"
386
+ }
387
+ }
388
+ },
389
+ {
390
+ "type": "object",
391
+ "required": ["uncheck"],
392
+ "additionalProperties": false,
393
+ "properties": {
394
+ "uncheck": {
395
+ "$ref": "#/$defs/target"
396
+ }
397
+ }
398
+ },
399
+ {
400
+ "type": "object",
401
+ "required": ["press", "key"],
402
+ "additionalProperties": false,
403
+ "properties": {
404
+ "press": {
405
+ "$ref": "#/$defs/target"
406
+ },
407
+ "key": {
408
+ "type": "string",
409
+ "pattern": "^[A-Za-z0-9+]{1,40}$",
410
+ "description": "A key, such as Enter or Tab."
411
+ }
412
+ }
413
+ },
414
+ {
415
+ "type": "object",
416
+ "required": ["key"],
417
+ "additionalProperties": false,
418
+ "properties": {
419
+ "key": {
420
+ "type": "string",
421
+ "pattern": "^[A-Za-z0-9+]{1,40}$",
422
+ "description": "A key, such as Enter or Tab."
423
+ }
424
+ }
425
+ }
426
+ ]
427
+ }
428
+ }
429
+ }