dsh-agent-team-ui-testing 0.0.0-stage → 0.1.2

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.
Files changed (92) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +327 -2
  3. package/annotation-capture.js +111 -0
  4. package/banner.png +0 -0
  5. package/banner_zh.png +0 -0
  6. package/browser-safety.js +293 -0
  7. package/capture-p0.js +910 -0
  8. package/client.js +11302 -0
  9. package/context-menu.js +134 -0
  10. package/cordis.patch.yml +3 -0
  11. package/core/clock.js +88 -0
  12. package/core/config-store.js +566 -0
  13. package/core/config.js +892 -0
  14. package/core/contracts.js +240 -0
  15. package/core/errors.js +156 -0
  16. package/core/evidence.js +141 -0
  17. package/core/geometry.js +217 -0
  18. package/core/identity.js +180 -0
  19. package/core/index.js +24 -0
  20. package/core/p0.js +1101 -0
  21. package/core/readiness.js +175 -0
  22. package/core/registry.js +239 -0
  23. package/core/tab-access.js +1350 -0
  24. package/docs/adapters.md +160 -0
  25. package/docs/architecture.md +146 -0
  26. package/docs/capability-tiers.md +80 -0
  27. package/docs/capture-p0.md +90 -0
  28. package/docs/diagnose-reason-codes.md +157 -0
  29. package/docs/element-picker.md +143 -0
  30. package/docs/getting-started.md +136 -0
  31. package/docs/index.md +36 -0
  32. package/docs/multi-tab.md +162 -0
  33. package/docs/network-p0.md +117 -0
  34. package/docs/panel-context-menu.md +41 -0
  35. package/docs/t2-structured-gui.md +68 -0
  36. package/docs/t3-vision.md +84 -0
  37. package/docs/t4-dynamic-behavior.md +135 -0
  38. package/docs/tools.md +174 -0
  39. package/docs/verification.md +131 -0
  40. package/docs/viewport-control.md +94 -0
  41. package/dynamic-t4.js +5699 -0
  42. package/frame-push.js +508 -0
  43. package/frame-source.js +162 -0
  44. package/icon.png +0 -0
  45. package/index.js +23028 -0
  46. package/integration/cross-environment.js +1535 -0
  47. package/integration/diagnose.js +945 -0
  48. package/integration/tab-principal.js +493 -0
  49. package/locale/en.json +6 -0
  50. package/locale/zh.json +6 -0
  51. package/network-p0.js +4264 -0
  52. package/package.json +19 -4
  53. package/select-control.js +298 -0
  54. package/skills/ui-testing-common/SKILL.md +54 -0
  55. package/skills/ui-testing-fake/SKILL.md +43 -0
  56. package/skills/ui-testing-web/SKILL.md +520 -0
  57. package/skills/ui-testing-web/manifests/declared-capabilities.json +903 -0
  58. package/skills/ui-testing-web/references/contracts/capability.md +68 -0
  59. package/skills/ui-testing-web/references/contracts/evidence.md +41 -0
  60. package/skills/ui-testing-web/references/contracts/operation.md +44 -0
  61. package/skills/ui-testing-web/references/core/dynamic-visual.md +123 -0
  62. package/skills/ui-testing-web/references/core/fallback.md +83 -0
  63. package/skills/ui-testing-web/references/core/network-and-state.md +114 -0
  64. package/skills/ui-testing-web/references/core/page-identity.md +91 -0
  65. package/skills/ui-testing-web/references/core/report-template.md +144 -0
  66. package/skills/ui-testing-web/references/core/reporting.md +92 -0
  67. package/skills/ui-testing-web/references/core/safety.md +12 -0
  68. package/skills/ui-testing-web/references/core/selection.md +26 -0
  69. package/skills/ui-testing-web/references/core/tool-routing-and-limits.md +198 -0
  70. package/skills/ui-testing-web/references/core/verdict-examples.md +96 -0
  71. package/skills/ui-testing-web/references/core/verdict-gate.md +105 -0
  72. package/skills/ui-testing-web/references/core/verification.md +19 -0
  73. package/skills/ui-testing-web/references/core/workflow.md +16 -0
  74. package/skills/ui-testing-web/references/platforms/index.md +19 -0
  75. package/skills/ui-testing-web/references/platforms/web.md +17 -0
  76. package/skills/ui-testing-web/references/scenarios/annotations.md +104 -0
  77. package/skills/ui-testing-web/references/scenarios/functional.md +205 -0
  78. package/skills/ui-testing-web/references/scenarios/visual-motion.md +170 -0
  79. package/skills/ui-testing-web/references/tiers/t1-programmatic.md +25 -0
  80. package/skills/ui-testing-web/references/tiers/t2-structured.md +61 -0
  81. package/skills/ui-testing-web/references/tiers/t3-static-visual.md +45 -0
  82. package/skills/ui-testing-web/references/tiers/t4-dynamic-visual.md +58 -0
  83. package/skills/ui-testing-web/templates/capability-note.md +23 -0
  84. package/skills/ui-testing-web/templates/platform.md +30 -0
  85. package/skills/ui-testing-web/templates/regression-case.md +15 -0
  86. package/skills/ui-testing-web/templates/scenario.md +13 -0
  87. package/targets/fake/adapter.js +1163 -0
  88. package/targets/fake/fixtures.js +177 -0
  89. package/targets/web/adapter.js +1231 -0
  90. package/targets/web/provider.js +415 -0
  91. package/vision-baseline.js +1254 -0
  92. package/vision-t3.js +2657 -0
@@ -0,0 +1,415 @@
1
+ /**
2
+ * Web P0Provider: platform side of the neutral P0 families A-E.
3
+ *
4
+ * The provider owns no protocol. It validates arguments, calls the injected `p0Dispatch`, and
5
+ * normalizes whatever the platform returns through the neutral factories in `core/p0.js`. That
6
+ * keeps CDP/DOM/screencast details out of `core/` while giving T1-T4 one stable data model.
7
+ *
8
+ * `p0Dispatch` may be:
9
+ * - a function: `p0Dispatch(family, method, { args, session, snapshot, signal })` (canonical), or
10
+ * - a per-family map `{ A: { screenshot }, B: { events } }` / `{ A: fn }` (test seam).
11
+ * A family the dispatch cannot serve is reported `unsupported`; it is never faked.
12
+ */
13
+
14
+ import {
15
+ AdapterError,
16
+ CONTRACT_VERSION,
17
+ ERROR_CODES,
18
+ createEvidenceEnvelope,
19
+ } from '../../core/index.js';
20
+ import {
21
+ P0_AVAILABILITY,
22
+ P0_EVIDENCE_FIELDS,
23
+ P0_FAMILIES,
24
+ P0_SUPPORT,
25
+ createAnnotationDoc,
26
+ createDisplaySpace,
27
+ createFrame,
28
+ createLease,
29
+ createNetworkEvent,
30
+ createTargetIdentity,
31
+ } from '../../core/p0.js';
32
+
33
+ /** Method inventory per P0 family; mirrors M0 §3 and the shipped provider surface. */
34
+ export const WEB_P0_METHODS = Object.freeze({
35
+ // `capture`/`product` are the page-capture entry points the tool layer uses (scale/region and
36
+ // the composited PNG product); they stay platform-shaped and skip neutral normalization.
37
+ A: Object.freeze(['screenshot', 'capture', 'product', 'validateImage', 'readFrame']),
38
+ B: Object.freeze(['start', 'stop', 'status', 'reset', 'events', 'detail', 'control', 'trace', 'evidence', 'subscribe']),
39
+ C: Object.freeze(['read', 'transform', 'set']),
40
+ D: Object.freeze(['annotationRead', 'annotationWrite']),
41
+ // P0-E owns target model projection and leases only; bind/close belong to the TargetAdapter.
42
+ E: Object.freeze(['list', 'leaseAcquire', 'leaseRelease', 'leaseStatus']),
43
+ });
44
+
45
+ /** Family -> gating capability id (web catalog). */
46
+ const FAMILY_CAPABILITY = Object.freeze({
47
+ A: 'web.p0.capture',
48
+ B: 'web.p0.network',
49
+ C: 'web.p0.display',
50
+ D: 'web.p0.canvas',
51
+ E: 'web.p0.targets',
52
+ });
53
+
54
+ /** Capability ids owned by this provider; the adapter catalog is the authority. */
55
+ export const WEB_P0_CAPABILITIES = Object.freeze(Object.values(FAMILY_CAPABILITY));
56
+
57
+ const KNOWN_ERROR_CODES = new Set(Object.values(ERROR_CODES));
58
+
59
+ const FAMILY_KEYS = Object.freeze(Object.values(P0_FAMILIES));
60
+
61
+ function isPlainObject(value) {
62
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
63
+ }
64
+
65
+ function nullableString(value) {
66
+ return typeof value === 'string' && value.length > 0 ? value : null;
67
+ }
68
+
69
+ function capabilityListOf(snapshot) {
70
+ const list = snapshot?.capabilities;
71
+ return Array.isArray(list) ? list.filter((id) => typeof id === 'string') : null;
72
+ }
73
+
74
+ function configRevisionOf(snapshot) {
75
+ const revision = snapshot?.revision ?? snapshot?.configRevision;
76
+ return Number.isInteger(revision) ? revision : null;
77
+ }
78
+
79
+ function toAdapterError(error, { operation }) {
80
+ if (error instanceof AdapterError) return error;
81
+ const code = typeof error?.code === 'string' && KNOWN_ERROR_CODES.has(error.code)
82
+ ? error.code
83
+ : ERROR_CODES.INTERNAL;
84
+ const message = error instanceof Error && error.message
85
+ ? error.message
86
+ : typeof error === 'string' && error.length > 0
87
+ ? error
88
+ : 'web p0 provider operation failed';
89
+ const details = { operation };
90
+ if (isPlainObject(error?.details)) Object.assign(details, error.details);
91
+ if (error instanceof Error) details.causeName = error.name;
92
+ return new AdapterError(code, message, {
93
+ details,
94
+ cause: error instanceof Error ? error : undefined,
95
+ });
96
+ }
97
+
98
+ function requireStringArg(args, field, operation) {
99
+ if (typeof args[field] !== 'string' || args[field].length === 0) {
100
+ throw new AdapterError(ERROR_CODES.INVALID_ARGUMENT, `${operation} requires '${field}'`, {
101
+ details: { operation, field },
102
+ });
103
+ }
104
+ }
105
+
106
+ /**
107
+ * Argument checks stay deliberately shallow: the provider guarantees the neutral shape, not the
108
+ * platform payload. Anything the platform needs to reject must surface as a platform error.
109
+ */
110
+ function validateArgs(family, method, args) {
111
+ const operation = `${family}.${method}`;
112
+ if (!isPlainObject(args)) {
113
+ throw new AdapterError(ERROR_CODES.INVALID_ARGUMENT, `${operation} args must be a plain object`, {
114
+ details: { operation, field: 'args', type: Array.isArray(args) ? 'array' : typeof args },
115
+ });
116
+ }
117
+ if (operation === 'B.detail' && args.requestId === undefined && args.seq === undefined) {
118
+ throw new AdapterError(ERROR_CODES.INVALID_ARGUMENT, 'B.detail requires requestId or seq', {
119
+ details: { operation, fields: ['requestId', 'seq'] },
120
+ });
121
+ }
122
+ if (operation === 'E.leaseAcquire') {
123
+ requireStringArg(args, 'targetId', operation);
124
+ }
125
+ if (operation === 'E.leaseRelease' || operation === 'E.leaseStatus') {
126
+ requireStringArg(args, 'leaseId', operation);
127
+ }
128
+ }
129
+
130
+ function listFrom(raw, key) {
131
+ if (Array.isArray(raw)) return raw;
132
+ if (isPlainObject(raw) && Array.isArray(raw[key])) return raw[key];
133
+ return [];
134
+ }
135
+
136
+ /** Normalize a platform result through the neutral factories; never invent missing values. */
137
+ function normalizeP0Value(family, method, raw) {
138
+ const operation = `${family}.${method}`;
139
+ switch (operation) {
140
+ case 'A.screenshot':
141
+ case 'A.readFrame':
142
+ return createFrame(isPlainObject(raw) ? raw : {});
143
+ case 'A.capture':
144
+ case 'A.product':
145
+ // Platform-shaped payloads: the tool contract owns their fields, so the provider must not
146
+ // re-shape them into a neutral frame.
147
+ return raw ?? null;
148
+ case 'A.validateImage':
149
+ if (isPlainObject(raw)) return raw;
150
+ throw new AdapterError(ERROR_CODES.INTERNAL, 'A.validateImage returned a non-object result', {
151
+ details: { operation },
152
+ });
153
+ case 'B.events': {
154
+ const events = listFrom(raw, 'events').map((event) => createNetworkEvent(isPlainObject(event) ? event : {}));
155
+ return isPlainObject(raw) && Array.isArray(raw.events) ? { ...raw, events } : events;
156
+ }
157
+ case 'B.detail':
158
+ return createNetworkEvent(isPlainObject(raw) ? raw : {});
159
+ case 'B.start':
160
+ case 'B.stop':
161
+ case 'B.status':
162
+ case 'B.reset':
163
+ case 'B.control':
164
+ case 'B.trace':
165
+ case 'B.evidence':
166
+ case 'B.subscribe':
167
+ case 'C.set':
168
+ return raw ?? null;
169
+ case 'C.read':
170
+ case 'C.transform':
171
+ return createDisplaySpace(isPlainObject(raw) ? raw : {});
172
+ case 'D.annotationRead':
173
+ case 'D.annotationWrite':
174
+ return createAnnotationDoc(isPlainObject(raw) ? raw : {});
175
+ case 'E.list': {
176
+ const targets = listFrom(raw, 'targets').map((target) => createTargetIdentity(isPlainObject(target) ? target : {}));
177
+ return isPlainObject(raw) && Array.isArray(raw.targets) ? { ...raw, targets } : targets;
178
+ }
179
+ case 'E.leaseAcquire':
180
+ return createLease(isPlainObject(raw) ? raw : {});
181
+ case 'E.leaseRelease':
182
+ return raw ?? null;
183
+ case 'E.leaseStatus': {
184
+ if (!isPlainObject(raw)) return raw ?? null;
185
+ return typeof raw.leaseId === 'string' || typeof raw.targetId === 'string'
186
+ ? createLease(raw)
187
+ : raw;
188
+ }
189
+ default:
190
+ return raw ?? null;
191
+ }
192
+ }
193
+
194
+ /**
195
+ * Create the web P0Provider.
196
+ *
197
+ * @param {object} [options]
198
+ * @param {Function|object} [options.p0Dispatch] Injected platform dispatch. Missing -> all five
199
+ * families report `support: 'unsupported'`.
200
+ * @param {object} [options.log]
201
+ * @param {() => number} [options.now]
202
+ */
203
+ export function createWebP0Provider({ p0Dispatch, log, now = Date.now } = {}) {
204
+ const manifest = {
205
+ contractVersion: CONTRACT_VERSION,
206
+ id: 'web.p0',
207
+ class: 'p0',
208
+ environment: 'web',
209
+ families: [...FAMILY_KEYS],
210
+ capabilities: [...WEB_P0_CAPABILITIES],
211
+ };
212
+
213
+ let disposed = false;
214
+
215
+ function assertNotDisposed() {
216
+ if (disposed) {
217
+ throw new AdapterError(ERROR_CODES.ADAPTER_DISABLED, 'web p0 provider is disposed', {
218
+ details: { providerId: manifest.id },
219
+ });
220
+ }
221
+ }
222
+
223
+ function familySupport(family) {
224
+ if (typeof p0Dispatch === 'function') {
225
+ const declared = Array.isArray(p0Dispatch.families) ? p0Dispatch.families : null;
226
+ return declared === null || declared.includes(family)
227
+ ? P0_SUPPORT.SUPPORTED
228
+ : P0_SUPPORT.UNSUPPORTED;
229
+ }
230
+ if (isPlainObject(p0Dispatch)) {
231
+ const handler = p0Dispatch[family];
232
+ if (typeof handler === 'function') return P0_SUPPORT.SUPPORTED;
233
+ if (isPlainObject(handler) && WEB_P0_METHODS[family].some((method) => typeof handler[method] === 'function')) {
234
+ return P0_SUPPORT.SUPPORTED;
235
+ }
236
+ }
237
+ return P0_SUPPORT.UNSUPPORTED;
238
+ }
239
+
240
+ function methodSupported(family, method) {
241
+ if (typeof p0Dispatch === 'function') return familySupport(family) === P0_SUPPORT.SUPPORTED;
242
+ const handler = p0Dispatch?.[family];
243
+ if (typeof handler === 'function') return true;
244
+ return isPlainObject(handler) && typeof handler[method] === 'function';
245
+ }
246
+
247
+ function callP0(family, method, payload) {
248
+ if (typeof p0Dispatch === 'function') return p0Dispatch(family, method, payload);
249
+ const handler = p0Dispatch[family];
250
+ if (typeof handler === 'function') return handler(method, payload);
251
+ return handler[method](payload);
252
+ }
253
+
254
+ async function invokeFamilyMethod(family, method, { args = {}, session, snapshot, signal, context = null, raw = false } = {}) {
255
+ assertNotDisposed();
256
+ const operation = `${family}.${method}`;
257
+ if (familySupport(family) === P0_SUPPORT.UNSUPPORTED || !methodSupported(family, method)) {
258
+ throw new AdapterError(
259
+ ERROR_CODES.CAPABILITY_UNSUPPORTED,
260
+ `web p0 family ${family} does not provide '${method}'`,
261
+ { details: { operation, family, method } },
262
+ );
263
+ }
264
+ validateArgs(family, method, args);
265
+ if (!isPlainObject(session)) {
266
+ throw new AdapterError(ERROR_CODES.TARGET_NOT_BOUND, `${operation} requires a target session`, {
267
+ details: { operation },
268
+ });
269
+ }
270
+ if (session.closed === true) {
271
+ throw new AdapterError(ERROR_CODES.TARGET_GONE, `web session ${String(session.sessionId)} is closed`, {
272
+ details: { operation, sessionId: session.sessionId ?? null },
273
+ });
274
+ }
275
+ const capabilities = capabilityListOf(snapshot);
276
+ if (capabilities !== null && !capabilities.includes(FAMILY_CAPABILITY[family])) {
277
+ throw new AdapterError(
278
+ ERROR_CODES.ADAPTER_DISABLED,
279
+ `capability '${FAMILY_CAPABILITY[family]}' is not enabled for '${operation}'`,
280
+ { details: { operation, capability: FAMILY_CAPABILITY[family] } },
281
+ );
282
+ }
283
+
284
+ let platformResult;
285
+ try {
286
+ // `context` carries the invocation-scoped handles the platform dispatch needs (the page
287
+ // runtime, the calling exec, the action meta). Dropping it made the production dispatch
288
+ // unusable: it could only ever answer PROVIDER_UNAVAILABLE (A01).
289
+ platformResult = await callP0(family, method, {
290
+ args,
291
+ session,
292
+ snapshot,
293
+ signal,
294
+ context,
295
+ // Routing facts for the composition root (§4.2): the P0 call must run on the selected
296
+ // provider's runtime. `null` for a snapshot that predates the provider field.
297
+ provider: typeof snapshot?.provider === 'string' ? snapshot.provider : null,
298
+ executionAdapterId: typeof snapshot?.executionAdapterId === 'string'
299
+ ? snapshot.executionAdapterId
300
+ : null,
301
+ });
302
+ } catch (error) {
303
+ throw toAdapterError(error, { operation });
304
+ }
305
+
306
+ // `raw: true` keeps the platform payload (used by the tool layer, whose public result shape
307
+ // is its own contract); the neutral model is the default for the neutral surface.
308
+ const value = raw === true ? (platformResult ?? null) : normalizeP0Value(family, method, platformResult);
309
+ const evidence = createEvidenceEnvelope({
310
+ scope: session.scopeId ?? null,
311
+ session: session.sessionId ?? null,
312
+ target: session.target?.targetId ?? null,
313
+ generation: Number.isInteger(session.generation) ? session.generation : null,
314
+ configRevision: configRevisionOf(snapshot) ?? (Number.isInteger(session.configRevision) ? session.configRevision : null),
315
+ operation,
316
+ source: 'web.p0',
317
+ capturedAt: typeof now === 'function' ? now() : Date.now(),
318
+ });
319
+ if (typeof evidence === 'object' && evidence !== null) {
320
+ for (const field of P0_EVIDENCE_FIELDS) {
321
+ if (!Object.hasOwn(evidence, field)) {
322
+ throw new AdapterError(ERROR_CODES.EVIDENCE_INCOMPLETE, `evidence is missing '${field}'`, {
323
+ details: { operation, missing: field },
324
+ });
325
+ }
326
+ }
327
+ }
328
+
329
+ log?.debug?.('web.p0.invoke', { operation });
330
+ return { value, evidence };
331
+ }
332
+
333
+ function buildFamilySurface(family) {
334
+ const surface = {};
335
+ for (const method of WEB_P0_METHODS[family]) {
336
+ surface[method] = (input = {}) => invokeFamilyMethod(family, method, input);
337
+ }
338
+ return Object.freeze(surface);
339
+ }
340
+
341
+ return {
342
+ manifest,
343
+
344
+ familyStatus({ session, snapshot } = {}) {
345
+ const capabilities = capabilityListOf(snapshot);
346
+ const out = {};
347
+ for (const family of FAMILY_KEYS) {
348
+ const support = familySupport(family);
349
+ if (support === P0_SUPPORT.UNSUPPORTED) {
350
+ out[family] = {
351
+ support,
352
+ availability: P0_AVAILABILITY.UNAVAILABLE,
353
+ reason: 'provider-missing',
354
+ capability: FAMILY_CAPABILITY[family],
355
+ };
356
+ continue;
357
+ }
358
+ if (!isPlainObject(session)) {
359
+ out[family] = {
360
+ support,
361
+ availability: P0_AVAILABILITY.NOT_PROBED,
362
+ reason: 'no-session',
363
+ capability: FAMILY_CAPABILITY[family],
364
+ };
365
+ continue;
366
+ }
367
+ if (session.closed === true) {
368
+ out[family] = {
369
+ support,
370
+ availability: P0_AVAILABILITY.UNAVAILABLE,
371
+ reason: 'target-gone',
372
+ capability: FAMILY_CAPABILITY[family],
373
+ };
374
+ continue;
375
+ }
376
+ if (capabilities === null) {
377
+ out[family] = {
378
+ support,
379
+ availability: P0_AVAILABILITY.NOT_PROBED,
380
+ reason: 'capability-unknown',
381
+ capability: FAMILY_CAPABILITY[family],
382
+ };
383
+ continue;
384
+ }
385
+ if (!capabilities.includes(FAMILY_CAPABILITY[family])) {
386
+ out[family] = {
387
+ support,
388
+ availability: P0_AVAILABILITY.UNAVAILABLE,
389
+ reason: 'capability-disabled',
390
+ capability: FAMILY_CAPABILITY[family],
391
+ };
392
+ continue;
393
+ }
394
+ out[family] = {
395
+ support,
396
+ availability: P0_AVAILABILITY.AVAILABLE,
397
+ reason: null,
398
+ capability: FAMILY_CAPABILITY[family],
399
+ };
400
+ }
401
+ return out;
402
+ },
403
+
404
+ capture: buildFamilySurface('A'),
405
+ network: buildFamilySurface('B'),
406
+ display: buildFamilySurface('C'),
407
+ canvas: buildFamilySurface('D'),
408
+ targets: buildFamilySurface('E'),
409
+
410
+ async dispose() {
411
+ if (disposed) return;
412
+ disposed = true;
413
+ },
414
+ };
415
+ }