@unotest/web 0.55.0 → 0.57.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/.claude/skills/write-e2e-test/SKILL.md +44 -7
- package/.claude/skills/write-e2e-test-ground/SKILL.md +20 -5
- package/CHANGELOG.md +250 -3
- package/README.md +7 -6
- package/bin/unotest-web.js +13 -0
- package/dist/config/schema.d.ts +29 -23
- package/dist/config/schema.js +1 -1
- package/dist/driver/index.d.ts +16 -2
- package/dist/driver/index.js +1 -1
- package/dist/dsl/index.d.ts +74 -94
- package/dist/dsl/index.js +1 -1
- package/dist/dsl/v8/scenario-worker.js +1 -1
- package/dist/dsl/web-dsl-language-service.d.ts +30 -3
- package/dist/dsl/web-dsl-language-service.js +1 -1
- package/dist/inspection/page-inject.d.ts +63 -7
- package/dist/inspection/page-inject.js +199 -19
- package/dist/{interfaces-CNvyInrY.d.ts → interfaces-DDp6Chwx.d.ts} +167 -10
- package/dist/{linter-BpaIstU3.d.ts → linter-q4UNIeGI.d.ts} +20 -0
- package/dist/mcp/server.js +1 -1
- package/dist/runner/cli.d.ts +1 -1
- package/dist/runner/cli.js +1 -1
- package/dist/runner/init/chrome-probe.js +1 -1
- package/dist/runner/init.js +1 -1
- package/dist/runner/install-chromium.js +1 -1
- package/dist/runner/prepare-fix.js +1 -1
- package/dist/runner/scaffold-workspace.js +1 -1
- package/dist/runner/serve-fixture.js +1 -1
- package/dist/runner/web-runner-adapter.js +1 -1
- package/dist/scenario-variables-CGexnWK4.d.ts +106 -0
- package/examples/idioms/README.md +16 -0
- package/examples/idioms/animations-list.js +24 -0
- package/examples/idioms/api-call-timeout.js +14 -0
- package/examples/idioms/background-tab.js +24 -0
- package/examples/idioms/clipboard-paste.js +25 -0
- package/examples/idioms/computed-style.js +21 -0
- package/examples/idioms/image-size.js +20 -0
- package/examples/idioms/never-appears.js +20 -0
- package/examples/idioms/never-condition.js +24 -0
- package/examples/idioms/page-code-function.js +18 -0
- package/examples/idioms/select-by-label.js +22 -0
- package/examples/idioms/wait-enabled.js +24 -0
- package/examples/idioms/wait-for-animations.js +16 -0
- package/examples/idioms/wait-until-value.js +32 -0
- package/guides/agent-integration.md +28 -4
- package/guides/dsl-reference.md +896 -45
- package/llms.txt +38 -9
- package/package.json +9 -8
- package/types/unotest-dsl.d.ts +107 -30
- package/types/unotest-lib.d.ts +5 -3
package/dist/dsl/index.d.ts
CHANGED
|
@@ -1,11 +1,12 @@
|
|
|
1
|
-
import { L as LocatorValue, j as DriverPage,
|
|
2
|
-
export {
|
|
1
|
+
import { L as LocatorValue, j as DriverPage, s as DriverDownload, d as ContextOptions, D as DriverContext, b as PageNetworkEntry, W as WebDriver } from '../interfaces-DDp6Chwx.js';
|
|
2
|
+
export { t as LocatorStep, u as appendStep, v as describeLocator, w as isLocatorValue, x as rootedAt } from '../interfaces-DDp6Chwx.js';
|
|
3
3
|
import { Matcher, RegexLiteral, JudgeRequest, JudgeVerdict, VisualFailureRecord, SoftFailureRecord, TeardownStateRecord, TeardownFailureRecord } from '@unotest/protocol';
|
|
4
4
|
import { Browser, SandboxConfig } from '../config/schema.js';
|
|
5
|
-
import {
|
|
5
|
+
import { V as VariableStore, H as HostPolicy } from '../scenario-variables-CGexnWK4.js';
|
|
6
6
|
import { ScenarioEvent, RunResult, ScenarioRunOptions } from '@unotest/dsl/executor';
|
|
7
7
|
export { ExecutionError, ScenarioEvent as ExecutionEvent, ScenarioRunOptions as RunOptions, RunResult } from '@unotest/dsl/executor';
|
|
8
|
-
|
|
8
|
+
import { RuntimeExecState } from '@unotest/core';
|
|
9
|
+
export { L as LintDiagnostic, b as LintOptions, a as LintSeverity, l as lintAst } from '../linter-q4UNIeGI.js';
|
|
9
10
|
import 'zod';
|
|
10
11
|
import '@unotest/dsl';
|
|
11
12
|
|
|
@@ -67,50 +68,6 @@ declare function chainGetByTitle(loc: LocatorValue, text: Matcher, options?: {
|
|
|
67
68
|
exact?: boolean;
|
|
68
69
|
}): LocatorValue;
|
|
69
70
|
|
|
70
|
-
/** Configuration invalid or missing. Surfaces during config load / validation. */
|
|
71
|
-
declare class ConfigError extends UnotestError {
|
|
72
|
-
}
|
|
73
|
-
/** A host the run would reach came from the BASE `.env` while a named
|
|
74
|
-
* environment is active (#199). Silence here is the whole defect: the
|
|
75
|
-
* overlay says "dev", the request goes to the production host the base
|
|
76
|
-
* file names, and nothing in the output says which host was used. The
|
|
77
|
-
* message names the variable, BOTH files, and the two ways out. */
|
|
78
|
-
declare class EnvOverlayHostError extends ConfigError {
|
|
79
|
-
constructor(context: {
|
|
80
|
-
name: string;
|
|
81
|
-
/** Where the name becomes a host, quoted as the author wrote it —
|
|
82
|
-
* `apiCall {base: "API_BASE_CHAT"}`, `goto(APP_URL)`, `baseUrl`. */
|
|
83
|
-
usage: string;
|
|
84
|
-
envName: string;
|
|
85
|
-
/** Project-relative file the value actually came from. */
|
|
86
|
-
baseFile: string;
|
|
87
|
-
/** The overlay that does NOT set it — where it belongs. */
|
|
88
|
-
overlayFile: string;
|
|
89
|
-
});
|
|
90
|
-
}
|
|
91
|
-
|
|
92
|
-
/**
|
|
93
|
-
* What a host-using call site may ask. A narrow port (ISP) so the linter
|
|
94
|
-
* and the DSL runtime depend on the QUESTION, not on the config layer:
|
|
95
|
-
* `rejectAsHost` answers with the refusal message, or undefined when the
|
|
96
|
-
* name is fine to use as a host here.
|
|
97
|
-
*/
|
|
98
|
-
interface HostVariableCheck {
|
|
99
|
-
rejectAsHost(name: string, usage: string): EnvOverlayHostError | undefined;
|
|
100
|
-
}
|
|
101
|
-
/** The policy as the places that switch environments need it: the same
|
|
102
|
-
* question, plus "the same rule, for a different environment". `forEnv`
|
|
103
|
-
* carries the config-derived `shared` list ACROSS, which is why the MCP
|
|
104
|
-
* server and the child it spawns cannot end up with different lists. */
|
|
105
|
-
interface HostPolicy extends HostVariableCheck {
|
|
106
|
-
forEnv(envName?: string): HostPolicy;
|
|
107
|
-
/** The base-URL variable is a host by construction — `APP_BASE_URL`
|
|
108
|
-
* becomes `config.baseUrl`, which every relative `goto` resolves
|
|
109
|
-
* against. Asked without naming it, so no consumer keeps a second
|
|
110
|
-
* literal of the name. */
|
|
111
|
-
rejectBaseUrl(usage: string): EnvOverlayHostError | undefined;
|
|
112
|
-
}
|
|
113
|
-
|
|
114
71
|
interface Logger {
|
|
115
72
|
info(msg: string, ...rest: unknown[]): void;
|
|
116
73
|
warn(msg: string, ...rest: unknown[]): void;
|
|
@@ -180,38 +137,6 @@ declare class SecretRegistry {
|
|
|
180
137
|
private redactNumber;
|
|
181
138
|
}
|
|
182
139
|
|
|
183
|
-
/** Read-only lookup over external scenario variables. */
|
|
184
|
-
interface VariableStore {
|
|
185
|
-
has(name: string): boolean;
|
|
186
|
-
get(name: string): string | undefined;
|
|
187
|
-
/** Host policy for the environment this store resolves against (#199).
|
|
188
|
-
* Optional like `describeSources`: a store built without a project
|
|
189
|
-
* behind it (test fakes, ad-hoc runtimes) carries none and the rule is
|
|
190
|
-
* then off. `withHostPolicy` (config/env-host-guard.ts) is what puts
|
|
191
|
-
* one on a store. */
|
|
192
|
-
hostPolicy?: HostPolicy;
|
|
193
|
-
/** One-line, human/agent-readable summary of WHERE lookups searched
|
|
194
|
-
* (active environment + layer files, missing ones flagged). Optional so
|
|
195
|
-
* test fakes stay two-method; consumed by "variable not found" errors. */
|
|
196
|
-
describeSources?(): string;
|
|
197
|
-
/** Whether `name` holds a credential — from a `.secrets` file, or a
|
|
198
|
-
* secret a box injected. Optional like `describeSources`: a store that
|
|
199
|
-
* cannot tell (test fakes) leaves it out, and a caller that must not
|
|
200
|
-
* hand a secret out then refuses rather than guess. */
|
|
201
|
-
isSecret?(name: string): boolean;
|
|
202
|
-
/** Why `name` is refused although the environment may hold it — the
|
|
203
|
-
* runner's own credential (`withOwnSecretsDenied`,
|
|
204
|
-
* config/own-secrets-deny.ts). Optional like `describeSources`; a
|
|
205
|
-
* caller that reports a missing name asks this first, so the reader
|
|
206
|
-
* learns whose the name is instead of hunting a typo. */
|
|
207
|
-
denial?(name: string): string | undefined;
|
|
208
|
-
/** The file that declares `name` without giving it a value (a `.example`
|
|
209
|
-
* twin), when no layer and no shell has one. Optional like `denial`: a
|
|
210
|
-
* store that cannot tell leaves it out, and the caller then reports the
|
|
211
|
-
* name as undeclared. */
|
|
212
|
-
declaredOnlyIn?(name: string): string | undefined;
|
|
213
|
-
}
|
|
214
|
-
|
|
215
140
|
interface Judge {
|
|
216
141
|
/** Produce a structured verdict. A clean `fail` is a RESULT (returned);
|
|
217
142
|
* infrastructure faults throw JudgeUnavailableError / ConfigError. */
|
|
@@ -392,6 +317,9 @@ interface VisualAssertDeps {
|
|
|
392
317
|
/** The names this run has given, to refuse two that became one file. */
|
|
393
318
|
names: BaselineNames;
|
|
394
319
|
backdrop?: BackdropFilterNotice;
|
|
320
|
+
/** The engine this run plays, named in a verdict: each one has its own
|
|
321
|
+
* baseline once the suite lists several. */
|
|
322
|
+
engine?: Browser;
|
|
395
323
|
}
|
|
396
324
|
|
|
397
325
|
type FrameFormat = "png" | "webp";
|
|
@@ -407,6 +335,10 @@ interface ScreenshotSink {
|
|
|
407
335
|
* in the same sequence as the pictures; the event says `redacted`.
|
|
408
336
|
* Returns the project-relative path it landed at. */
|
|
409
337
|
saveMaskedText(name: string, text: string): Promise<string>;
|
|
338
|
+
/** Persist why a capture did not happen (a capture that ran out of
|
|
339
|
+
* time), in the same sequence, so a green run still shows where its
|
|
340
|
+
* evidence is missing and why. Returns the project-relative path. */
|
|
341
|
+
saveCaptureError(name: string, reason: string): Promise<string>;
|
|
410
342
|
}
|
|
411
343
|
|
|
412
344
|
interface SavedDownload {
|
|
@@ -422,7 +354,14 @@ interface DownloadSink {
|
|
|
422
354
|
save(download: DriverDownload): Promise<SavedDownload>;
|
|
423
355
|
}
|
|
424
356
|
|
|
357
|
+
/** What the browser window looks like: a device preset, an explicit
|
|
358
|
+
* size, or both (the size overrides the preset's). */
|
|
359
|
+
type Display = Pick<ContextOptions, "device" | "viewport">;
|
|
360
|
+
|
|
425
361
|
type ContextFactory = () => Promise<DriverContext>;
|
|
362
|
+
/** How the runner opens one more context with the entry's options — on
|
|
363
|
+
* `display` instead of the entry's window when one is asked for. */
|
|
364
|
+
type ContextOpener = (display?: Display) => Promise<DriverContext>;
|
|
426
365
|
/** How the runner opens a context on a browser profile of its own
|
|
427
366
|
* (`newContext({profile})`). It owns what a directory name means: where a
|
|
428
367
|
* relative one starts, that it exists. */
|
|
@@ -430,7 +369,7 @@ interface ProfileContexts {
|
|
|
430
369
|
/** The directory as the browser will open it: absolute, made if it was
|
|
431
370
|
* missing, symlinks resolved — the form two names of one directory agree on. */
|
|
432
371
|
resolve(dir: string): string;
|
|
433
|
-
open(resolvedDir: string): Promise<DriverContext>;
|
|
372
|
+
open(resolvedDir: string, display?: Display): Promise<DriverContext>;
|
|
434
373
|
/** Whether `resolvedDir` is the profile directory the run's own context
|
|
435
374
|
* sits on (a run on `launch.userDataDir`, or a browser per test). */
|
|
436
375
|
isRunProfile(resolvedDir: string): boolean;
|
|
@@ -438,10 +377,16 @@ interface ProfileContexts {
|
|
|
438
377
|
/** How the runner opens a context in a browser it joins over CDP
|
|
439
378
|
* (`newContext({cdpEndpoint})`): a browser somebody else started, left
|
|
440
379
|
* running when the test ends. */
|
|
441
|
-
type RemoteContextFactory = (endpoint: string) => Promise<DriverContext>;
|
|
380
|
+
type RemoteContextFactory = (endpoint: string, display?: Display) => Promise<DriverContext>;
|
|
442
381
|
interface NewContextTarget {
|
|
443
382
|
profile?: string;
|
|
444
383
|
cdpEndpoint?: string;
|
|
384
|
+
/** Request headers every page of the new context sends — on whichever
|
|
385
|
+
* of the three it opens in, set before the scenario's first goto there. */
|
|
386
|
+
headers?: Readonly<Record<string, string>>;
|
|
387
|
+
/** The window the new context opens on, over the entry's — the scale
|
|
388
|
+
* is fixed when a context opens, so it cannot be set afterwards. */
|
|
389
|
+
display?: Display;
|
|
445
390
|
}
|
|
446
391
|
/** A context that did not close — reported, never swallowed. */
|
|
447
392
|
interface ContextCloseFailure {
|
|
@@ -463,7 +408,7 @@ declare class ContextSet {
|
|
|
463
408
|
/** Called with the new active index on every switch (open or select). */
|
|
464
409
|
private readonly listeners;
|
|
465
410
|
constructor(first: DriverContext | ContextFactory, opts?: {
|
|
466
|
-
open?:
|
|
411
|
+
open?: ContextOpener;
|
|
467
412
|
profiles?: ProfileContexts;
|
|
468
413
|
remote?: RemoteContextFactory;
|
|
469
414
|
max?: number;
|
|
@@ -481,6 +426,7 @@ declare class ContextSet {
|
|
|
481
426
|
* browser profile of its own when `profile` names a directory, in a
|
|
482
427
|
* browser somebody else runs when `cdpEndpoint` names one. */
|
|
483
428
|
open(target?: NewContextTarget): Promise<number>;
|
|
429
|
+
private openOn;
|
|
484
430
|
private openRemote;
|
|
485
431
|
private openProfile;
|
|
486
432
|
/** Context 0 first, then room under the ceiling, then the new one —
|
|
@@ -745,6 +691,8 @@ declare class TerminalSet {
|
|
|
745
691
|
/** The active window, or none — for a failure bundle, which must not
|
|
746
692
|
* fail over a test that never opened a terminal. */
|
|
747
693
|
current(): TerminalSession | undefined;
|
|
694
|
+
/** The index of the active window while it is open, else none. */
|
|
695
|
+
activeIndex(): number | undefined;
|
|
748
696
|
/** A frame of `session` fit to leave the run: its picture, or its
|
|
749
697
|
* masked screen text when a secret is on the screen. */
|
|
750
698
|
frame(session: TerminalSession): Promise<GuardedFrame>;
|
|
@@ -828,8 +776,10 @@ interface McpConnectionEvents {
|
|
|
828
776
|
onClose(): void;
|
|
829
777
|
}
|
|
830
778
|
interface McpConnection {
|
|
831
|
-
/** `tools/call`; resolves with the result as the server sent it.
|
|
832
|
-
|
|
779
|
+
/** `tools/call`; resolves with the result as the server sent it. The
|
|
780
|
+
* request has no deadline of its own: the caller ends it through
|
|
781
|
+
* `signal`, and the abort reason is what the call rejects with. */
|
|
782
|
+
callTool(tool: string, args: Readonly<Record<string, unknown>>, signal: AbortSignal): Promise<Record<string, unknown>>;
|
|
833
783
|
/** The tail of what the server wrote to stderr — a crash says why there. */
|
|
834
784
|
stderrTail(): string;
|
|
835
785
|
close(): Promise<void>;
|
|
@@ -852,10 +802,17 @@ interface JsonFilter {
|
|
|
852
802
|
describe(): string;
|
|
853
803
|
}
|
|
854
804
|
|
|
805
|
+
type McpJournalLevel = 'info' | 'warn';
|
|
855
806
|
/** Where the session reports calls, results and notifications — the
|
|
856
|
-
* run's journal. Must not throw: reporting never fails a step.
|
|
807
|
+
* run's journal. Must not throw: reporting never fails a step. A `warn`
|
|
808
|
+
* record is something the scenario left undone that does not fail it. */
|
|
857
809
|
interface McpJournal {
|
|
858
|
-
record(label: string, text: string): Promise<void>;
|
|
810
|
+
record(label: string, text: string, level?: McpJournalLevel): Promise<void>;
|
|
811
|
+
}
|
|
812
|
+
interface McpResultOptions {
|
|
813
|
+
/** Counted from when the result is asked for, not from the start. */
|
|
814
|
+
timeoutMs: number;
|
|
815
|
+
allowError: boolean;
|
|
859
816
|
}
|
|
860
817
|
interface McpWaitSpec {
|
|
861
818
|
method: string;
|
|
@@ -873,17 +830,28 @@ declare class McpSession {
|
|
|
873
830
|
private last;
|
|
874
831
|
private readonly pending;
|
|
875
832
|
private readonly waiters;
|
|
833
|
+
private readonly calls;
|
|
834
|
+
/** Calls whose result was taken, by id: their tool, for the refusal. */
|
|
835
|
+
private readonly taken;
|
|
836
|
+
private callsStarted;
|
|
876
837
|
private closed;
|
|
877
838
|
private stopping;
|
|
878
839
|
private constructor();
|
|
879
840
|
static start(connector: McpConnector, spec: McpServerSpec, label: string, journal: McpJournal, timeoutMs: number): Promise<McpSession>;
|
|
880
841
|
get isClosed(): boolean;
|
|
881
|
-
|
|
882
|
-
|
|
883
|
-
|
|
884
|
-
|
|
842
|
+
/** mcpCall: the request and its answer in one step. */
|
|
843
|
+
call(tool: string, args: Readonly<Record<string, unknown>>, opts: McpResultOptions): Promise<Record<string, unknown>>;
|
|
844
|
+
/** Sends `tools/call` and returns the id its answer is kept under. */
|
|
845
|
+
startCall(fnName: string, tool: string, args: Readonly<Record<string, unknown>>): Promise<string>;
|
|
846
|
+
/** The answer of a started call, once. No answer within `timeoutMs`
|
|
847
|
+
* cancels the request: there is no polling a call with short waits. */
|
|
848
|
+
result(fnName: string, id: string, opts: McpResultOptions): Promise<Record<string, unknown>>;
|
|
885
849
|
waitNotification(spec: McpWaitSpec): Promise<Record<string, unknown>>;
|
|
886
850
|
stop(): Promise<void>;
|
|
851
|
+
private take;
|
|
852
|
+
/** Calls the scenario started and never took: a warning, not a red
|
|
853
|
+
* step — their answers are dropped with the server. */
|
|
854
|
+
private dropUnclaimed;
|
|
887
855
|
private open;
|
|
888
856
|
private observe;
|
|
889
857
|
private deliver;
|
|
@@ -900,6 +868,15 @@ interface McpHandle {
|
|
|
900
868
|
readonly id: string;
|
|
901
869
|
readonly command: string;
|
|
902
870
|
}
|
|
871
|
+
/** A call mcpCallStart sent, as the scenario holds it; its answer waits in
|
|
872
|
+
* the server's session, behind the id. */
|
|
873
|
+
interface McpCallHandle {
|
|
874
|
+
readonly kind: 'mcpCall';
|
|
875
|
+
/** `<server id>/<call id>`, unique within the test. */
|
|
876
|
+
readonly id: string;
|
|
877
|
+
readonly server: string;
|
|
878
|
+
readonly tool: string;
|
|
879
|
+
}
|
|
903
880
|
interface McpSessionsDeps {
|
|
904
881
|
connector: McpConnector;
|
|
905
882
|
journal: McpJournal;
|
|
@@ -917,6 +894,8 @@ declare class McpSessions {
|
|
|
917
894
|
}): Promise<McpHandle>;
|
|
918
895
|
/** The session behind a handle the scenario passed in. */
|
|
919
896
|
get(fnName: string, handle: unknown): McpSession;
|
|
897
|
+
startCall(fnName: string, handle: unknown, tool: string, args: Readonly<Record<string, unknown>>): Promise<McpCallHandle>;
|
|
898
|
+
result(fnName: string, handle: unknown, opts: McpResultOptions): Promise<Record<string, unknown>>;
|
|
920
899
|
stop(fnName: string, handle: unknown): Promise<void>;
|
|
921
900
|
/** Stops the server if the scenario has not — what mcpStart leaves to
|
|
922
901
|
* the end of the test. */
|
|
@@ -939,7 +918,7 @@ type RuntimeContexts = {
|
|
|
939
918
|
readonly context: DriverContext | ContextFactory;
|
|
940
919
|
/** Opens one more context with the entry's options (`newContext()`).
|
|
941
920
|
* Absent → the runtime cannot add one (an attached debug session). */
|
|
942
|
-
readonly openContext?:
|
|
921
|
+
readonly openContext?: ContextOpener;
|
|
943
922
|
/** Opens a context on a browser profile of its own
|
|
944
923
|
* (`newContext({profile})`). Absent → it cannot be. */
|
|
945
924
|
readonly profiles?: ProfileContexts;
|
|
@@ -1087,8 +1066,9 @@ declare class TestRuntime {
|
|
|
1087
1066
|
get hostPolicy(): HostPolicy | undefined;
|
|
1088
1067
|
getVar(name: string): DslValue;
|
|
1089
1068
|
/** Direct external-variable lookup (`unotest/.env` / `.secrets`), no
|
|
1090
|
-
* scope fallback, no throw.
|
|
1091
|
-
*
|
|
1069
|
+
* scope fallback, no throw. The one place an empty value becomes "not
|
|
1070
|
+
* set on this environment" (#472): the bare name, `env()`, shell()'s
|
|
1071
|
+
* `sandbox.exportSecrets` and `apiCall`'s `{base}` all read through it. */
|
|
1092
1072
|
externalVar(name: string): string | undefined;
|
|
1093
1073
|
/** Whether external variable `name` is a secret; undefined when the
|
|
1094
1074
|
* variable store cannot tell. Used by `env()`, which never hands one out. */
|