@enhance-eng/sdk 0.1.0-dev.sha-3f7dd0acb078 → 0.1.158
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/README.md +112 -18
- package/dist/browser/kernel.iife.js +4598 -3208
- package/dist/capture-client.client--zU5zvd3.d.mts +78 -0
- package/dist/capture-client.client-YvUy2nGh.mjs +525 -0
- package/dist/capture-context.lib-BivWcwWc.mjs +40 -0
- package/dist/client.d.mts +2 -0
- package/dist/client.mjs +2 -0
- package/dist/environment.config-B2WQJWaS.mjs +34 -0
- package/dist/environment.config-Dx5WHap5.d.mts +12 -0
- package/dist/index-7uzK6oto.d.mts +656 -0
- package/dist/index.d.mts +9 -36
- package/dist/index.mjs +3 -3
- package/dist/package-VWmCi21a.mjs +4 -0
- package/dist/playwright/index.d.mts +7 -1
- package/dist/playwright/index.mjs +613 -6175
- package/dist/playwright/reporter.d.mts +4 -5
- package/dist/playwright/reporter.mjs +99 -31
- package/dist/stall-watch.lib-C6VmIsz-.mjs +8474 -0
- package/package.json +17 -6
- package/dist/capture-client.client-BDphetFj.mjs +0 -226
- package/dist/capture-files.lib-BA_KBz9W.mjs +0 -406
- package/dist/capture-files.lib-CvX7Ca8M.d.mts +0 -11
- package/dist/environment.config-BgNT6S_H.mjs +0 -14
- package/dist/index-PIb9iIwo.d.mts +0 -257
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Enhance SDK
|
|
2
2
|
|
|
3
|
-
Publish editable customer journeys from tests to
|
|
3
|
+
Publish editable customer journeys from tests to Enhance. Each execution can create its own review canvas; existing integrations can still update a fixed canvas. Captures use the same browser snapshot kernel and editable-screen compiler as the product.
|
|
4
4
|
|
|
5
5
|
Requires Node.js 24 or later. The Playwright entry points require `@playwright/test` 1.62 or later (before 2.0). Install one package:
|
|
6
6
|
|
|
@@ -9,9 +9,38 @@ npm install --save-dev @enhance-eng/sdk
|
|
|
9
9
|
```
|
|
10
10
|
|
|
11
11
|
Development prereleases use the same package: `npm install --save-dev @enhance-eng/sdk@next`.
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
12
|
+
Development versions (`-dev.sha-…`) default to the Enhance development API. Stable versions
|
|
13
|
+
default to production. Both distributions are public and use the same code.
|
|
14
|
+
|
|
15
|
+
Set `ENHANCE_ENVIRONMENT` to choose explicitly; the Node client and every reporter share these settings:
|
|
16
|
+
|
|
17
|
+
| Environment | API | Credentials |
|
|
18
|
+
| --- | --- | --- |
|
|
19
|
+
| `local` | `http://localhost:3000` | A token and canvas from your local API |
|
|
20
|
+
| `development` | `https://api.enhance3.karunalabs.ai` | A development token and canvas |
|
|
21
|
+
| `production` | `https://api.enhancelabs.ai` | A production token and canvas |
|
|
22
|
+
|
|
23
|
+
Use `ENHANCE_API_URL` for a different local port or a custom API. A named environment rejects
|
|
24
|
+
an endpoint from another environment before sending credentials. Omit `ENHANCE_ENVIRONMENT`
|
|
25
|
+
when targeting a custom server. `NODE_ENV`, the URL of the page being captured, and the CI
|
|
26
|
+
runner do not select the destination: tests often run a local page while publishing to a cloud canvas.
|
|
27
|
+
|
|
28
|
+
For local runs, load an ignored environment file before running tests:
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
set -a
|
|
32
|
+
source .env.sdk.local
|
|
33
|
+
set +a
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Its values are `ENHANCE_ENVIRONMENT=local`, `ENHANCE_API_URL=http://localhost:3000` (or the
|
|
37
|
+
worktree API port), and `ENHANCE_TOKEN` from that local instance. In CI, set the environment
|
|
38
|
+
name and its token as job configuration and a secret respectively. Tokens are never inferred
|
|
39
|
+
from another environment or read from CLI credential storage by the SDK.
|
|
40
|
+
|
|
41
|
+
Integrations that already own destination and credential selection, such as the Enhance CLI,
|
|
42
|
+
import `createEnhance` from `@enhance-eng/sdk/client` and pass both `apiUrl` and `token`.
|
|
43
|
+
That entry uses the same publisher without loading SDK environment defaults or ambient credentials.
|
|
15
44
|
|
|
16
45
|
Configure the reporter in `playwright.config.ts`:
|
|
17
46
|
|
|
@@ -22,14 +51,18 @@ export default defineConfig({
|
|
|
22
51
|
reporter: [
|
|
23
52
|
['list'],
|
|
24
53
|
['@enhance-eng/sdk/playwright/reporter', {
|
|
25
|
-
|
|
54
|
+
destination: { organisationId: 'YOUR_TEAM_UUID' }, // {} for your personal space
|
|
26
55
|
source: 'storefront',
|
|
56
|
+
runKey: process.env.CAPTURE_EXECUTION_ID, // Unique execution; shared by its shards
|
|
57
|
+
revision: process.env.CAPTURE_REVISION,
|
|
58
|
+
context: { key: 'pr:142', label: 'PR 142', sequence: Number(process.env.CAPTURE_EXECUTION_NUMBER) },
|
|
59
|
+
compareTo: { reference: 'main' },
|
|
27
60
|
}],
|
|
28
61
|
],
|
|
29
62
|
});
|
|
30
63
|
```
|
|
31
64
|
|
|
32
|
-
Create an agent token in **Settings → Agent tokens** and store it as the `ENHANCE_TOKEN` secret in your CI runner (or environment variable locally). Its owner must
|
|
65
|
+
Create an agent token in **Settings → Agent tokens** in the destination environment and store it as the `ENHANCE_TOKEN` secret in your CI runner (or environment variable locally). Its owner must belong to the destination team. For a fixed canvas, specify `canvas` instead of `destination` and use the UUID from its `/c/<uuid>` URL; its owner must be able to edit that canvas. Credentials stay in the Node process, outside captured pages and artifacts. Reporter options `environment`, `apiUrl`, and `token` override their corresponding environment variables.
|
|
33
66
|
|
|
34
67
|
```ts
|
|
35
68
|
import { test } from '@playwright/test';
|
|
@@ -44,16 +77,17 @@ test('checkout', async ({ page }) => {
|
|
|
44
77
|
});
|
|
45
78
|
```
|
|
46
79
|
|
|
47
|
-
Wait for the state you intend to capture before calling `capture`. The adapter
|
|
80
|
+
Wait for the state you intend to capture before calling `capture`. The adapter waits briefly for the DOM and preview to settle together. A page that keeps moving is captured as it last looked, and a resource that cannot be fetched is left out; the screen is always published so you can see it and fix what is off.
|
|
48
81
|
|
|
49
82
|
## Identity and updates
|
|
50
83
|
|
|
51
|
-
`source`, `journey`, `step` and `variant` identify a frame. Use stable keys; labels may be friendlier. The default variant is the Playwright project name. `order` is optional
|
|
84
|
+
`source`, `journey`, `step` and `variant` identify a frame. Use stable keys; labels may be friendlier. The default variant is the Playwright project name. `order` is optional; when several captures share a position, they are ordered by test file, then by the test's line, then by call order. Capturing the same step twice in one test publishes both, the second as "cart (2)"; a step that several tests capture is published once per test, named "cart · <test title>". Names longer than 160 characters are shortened the same way on every run.
|
|
52
85
|
|
|
53
86
|
```ts
|
|
54
87
|
await enhance.capture(page, {
|
|
55
88
|
journey: 'checkout',
|
|
56
89
|
journeyLabel: 'Customer checkout',
|
|
90
|
+
page: 'Shopping',
|
|
57
91
|
step: 'payment',
|
|
58
92
|
label: 'Choose payment method',
|
|
59
93
|
variant: 'mobile',
|
|
@@ -65,7 +99,9 @@ await enhance.capture(page, {
|
|
|
65
99
|
|
|
66
100
|
Blocked elements are excluded from the editable snapshot and masked in its preview. Capture test accounts and fixtures appropriate for sharing with everyone who can read the destination canvas. The adapter retains resource bytes; it does not upload authentication headers or a live browser session.
|
|
67
101
|
|
|
68
|
-
|
|
102
|
+
Every step of a journey/variant uses the same optional `page`. Journeys with the same page name share that page. Unspecified pages share the default page. Page names, labels and order are layout metadata; they do not change screen identity.
|
|
103
|
+
|
|
104
|
+
The reporter reserves a run before tests capture anything. When the test run ends, it publishes every test's screens from that test's last attempt that captured anything, whether the test passed or failed: a failing test's screens show what went wrong. A problem with one screen never stops the others from publishing. A new run canvas contains the captures from that execution. For a fixed destination canvas, missing steps stay on the canvas and new steps append without overlapping other frames. Updates keep frame identity and human positioning/naming. A frame a person edited or locked is kept as it is, and the new capture is added beside it; later runs update the new frame. A frame a person deleted comes back on the next run; take the capture out of the test to stop it.
|
|
69
105
|
|
|
70
106
|
Each publication is atomic. An identical capture compiled by the same server release leaves the document unchanged. A changed capture retains the previous and current source previews for the frame's **Compare with previous capture** action.
|
|
71
107
|
|
|
@@ -86,26 +122,84 @@ The core Node entry point publishes the same manifest; it has no Playwright depe
|
|
|
86
122
|
```ts
|
|
87
123
|
import { createEnhance } from '@enhance-eng/sdk';
|
|
88
124
|
|
|
89
|
-
const enhance = createEnhance(
|
|
90
|
-
apiUrl: process.env.ENHANCE_API_URL ?? 'https://api.enhancelabs.ai',
|
|
91
|
-
token: process.env.ENHANCE_TOKEN ?? '',
|
|
92
|
-
});
|
|
125
|
+
const enhance = createEnhance(); // Same environment and token settings as the reporter.
|
|
93
126
|
const receipt = await enhance.captures.publishManifest('./saved-capture/manifest.json');
|
|
94
127
|
console.log(receipt.canvasUrl);
|
|
95
128
|
```
|
|
96
129
|
|
|
97
|
-
After a timeout or connection loss, repeat `publishManifest` with the **same manifest**. The server returns the original receipt if the run already committed. Do not create a fresh run to upload an old capture: its canvas baseline is no longer current.
|
|
130
|
+
After a timeout or connection loss, repeat `publishManifest` with the **same manifest**. The server returns the original receipt if the run already committed. Do not create a fresh run to upload an old capture: its canvas baseline is no longer current. A run expires 24 hours after its last upload or seal; expired or cancelled runs require fresh captures. A deploy of Enhance during a test run does not affect it. Every request is retried after a dropped connection, a timeout, a server error or "too many requests", up to three attempts. If publishing takes longer than the wait, the SDK prints the run and canvas it is still publishing to, and does not fail the test run. Recovery uses the same agent token that reserved the run.
|
|
98
131
|
|
|
99
132
|
`run.cancel()` returns `null` when the run is cancelled, or its receipt if publication already committed. It never undoes committed canvas changes.
|
|
100
133
|
|
|
101
134
|
Node producers may call `enhance.captures.begin({ canvas, source, runKey })`, then `run.add({ artifact, blobs })` and `run.publish()`. The artifact schema and checksum rules are exported from the root entry point. Producers supply frozen source, preview and resource bytes; they never map browser elements into canvas primitives.
|
|
102
135
|
|
|
103
|
-
|
|
136
|
+
## Review runs and baselines
|
|
137
|
+
|
|
138
|
+
A `destination` creates one ordinary canvas per `source` and `runKey`. Repeating the reservation with the same token, metadata and participants returns the same run. Give a new execution a new key, including a CI rerun attempt. A `title` is optional. The default title includes the source, context label and execution key so concurrent work remains distinguishable in the existing canvas list.
|
|
139
|
+
|
|
140
|
+
`context.key` groups successive executions of the same change, for example a PR or deployment. `sequence` orders executions within that context; `attempt` orders reruns of that sequence and defaults to zero. Supply the pipeline's increasing execution number, not a PR number for every execution. Older jobs finishing late cannot displace a newer published run. `revision` identifies the version actually captured, including a synthetic merge revision when that is what the tests run.
|
|
141
|
+
|
|
142
|
+
`compareTo: { reference: 'main' }` pins that reference when the run begins. `compareTo: { reference: 'main', revision: baseRevision }` selects a previously promoted capture of that revision. `compareTo: { runId }` selects a particular published run. Baselines must belong to the same destination and source. A missing unversioned reference starts without a before; an explicitly requested revision must exist. Matching uses source, journey, step and variant. Later promotions do not change existing pairs.
|
|
143
|
+
|
|
144
|
+
The canvas Review tab lists changed/new screens and offers all captured screens for flow context. A changed screen opens the existing before/after viewer. The change index compares decoded image pixels, dimensions and pixel ratio; labels, PNG compression, timestamps and compiler changes do not count as visual changes. Unavailable image evidence stays unclassified. There is no pixel threshold or automatic approval.
|
|
145
|
+
|
|
146
|
+
Choose **Approved** or **Changes requested** for the whole canvas. Comments, ordinary frame editing/duplication and MCP work as on any other canvas. Share an alternative with an engineer or agent; the next test execution creates a fresh review. Older comments and alternatives remain on the older canvas.
|
|
147
|
+
|
|
148
|
+
```ts
|
|
149
|
+
const review = await enhance.captures.review(receipt.canvasId);
|
|
150
|
+
if (review?.latest.id !== receipt.runId) throw new Error('A newer run replaced this review');
|
|
151
|
+
if (review.current.verdict !== 'approved') throw new Error('Product review is not approved');
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
Your pipeline decides when to read that verdict and what it gates. For example, a CI job can wait/poll for a decision or a later deployment job can check it. Enhance does not install branch rules or merge/deploy on your behalf. The API is the same for GitHub Actions, another CI provider, and local scripts.
|
|
155
|
+
|
|
156
|
+
After the corresponding version merges or deploys successfully, promote its captured run explicitly:
|
|
157
|
+
|
|
158
|
+
```ts
|
|
159
|
+
// Read and retain this version before the pipeline step that changes the reference.
|
|
160
|
+
const previous = await enhance.captures.reference(receipt.canvasId, 'main');
|
|
161
|
+
// After that merge/deployment succeeds:
|
|
162
|
+
await enhance.captures.promote({
|
|
163
|
+
canvasId: receipt.canvasId,
|
|
164
|
+
name: 'main',
|
|
165
|
+
expectedVersion: previous?.version ?? 0,
|
|
166
|
+
revision: landedRevision,
|
|
167
|
+
});
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
`revision` on promotion records which accepted version this existing capture represents; it does not rewrite the captured revision. A stale `expectedVersion` refuses promotion. Inspect the pipeline's actual merge/deployment ordering before retrying with a newer version. Repeating a successful promotion is idempotent. Approval alone never promotes a baseline. No extra production Playwright run is required to promote existing evidence; if a different combined version needs evidence, schedule another test run in your pipeline.
|
|
171
|
+
|
|
172
|
+
## Shards
|
|
173
|
+
|
|
174
|
+
For native Playwright sharding, the reporter reserves all `shard-1` through `shard-N` participants automatically. Every shard needs the same explicit `runKey` and metadata. Upload each reporter output directory as a CI artifact. In a final job, download the directories and call:
|
|
175
|
+
|
|
176
|
+
```ts
|
|
177
|
+
const receipt = await enhance.captures.publishManifests([
|
|
178
|
+
'./shard-1/manifest.json',
|
|
179
|
+
'./shard-2/manifest.json',
|
|
180
|
+
]);
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
This combines manifests and reads their existing blobs through the same publisher. It publishes the shards it is given, whatever their result; a shard whose manifest is missing contributes nothing, and a shard given twice counts once (the first copy). It refuses manifests from different runs. Retry `publishManifests` with the same paths after a connection loss; it returns the durable receipt without publishing twice. Custom worker systems can reserve `participants` up front and supply the shared `run` descriptor plus the reporter's `participant`.
|
|
184
|
+
|
|
185
|
+
|
|
186
|
+
## What a run reports
|
|
187
|
+
|
|
188
|
+
A run never reports a degraded capture as a whole one. The receipt carries the run's capture issues, each with a code and a message, and the SDK prints one line per issue under the canvas address, each starting with `Enhance:`:
|
|
189
|
+
|
|
190
|
+
```text
|
|
191
|
+
Enhance: https://app.enhancelabs.ai/c/…
|
|
192
|
+
Enhance: file-not-copied: 2 files could not be copied.
|
|
193
|
+
Enhance: capture-left-out: Checkout › Payment: none of its files arrived
|
|
194
|
+
Enhance: file-not-uploaded: https://cdn.example.com/hero.webp: Enhance's storage refused it
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
The codes are `capture-left-out`, `page-not-settled`, `file-not-copied`, `file-missing`, `file-mismatched`, `preview-used`, `preview-uncompared`, `screen-degraded`, `unsupported-surface` and `frame-not-frozen`. A file that the SDK gave up on gets its own line with its address and the reason: it could not be read on this machine, or storage refused it for good. A storage outage is retried; it is never reported as a missing file. When the run's own reservation had expired, the first line names the run that published its captures instead.
|
|
104
198
|
|
|
105
199
|
## Limits
|
|
106
200
|
|
|
107
|
-
|
|
201
|
+
Preview dimensions must match the captured CSS extent at the declared pixel ratio. Journeys, pages, runs and captured content have no new product ceilings. Existing transport upload batches are chunking, not a limit on a run's number of resources.
|
|
108
202
|
|
|
109
|
-
Automatic placement uses axis-aligned outer layout boxes.
|
|
203
|
+
Automatic placement uses axis-aligned outer layout boxes. When a person locked or transformed a journey's row so it cannot take frames, the frames go in a row beside it. Transforms inside captured screens are supported.
|
|
110
204
|
|
|
111
|
-
This release
|
|
205
|
+
This release retains original evidence and uses the shared editable-screen compiler. Existing preview fallback still applies when a screen cannot be compiled. Redlines, pixel heatmaps and diff scores can be added to the comparison UI without replacing the run or canvas model.
|