Skip to content

docs(ui-capture): install guide per framework, SPAs, bundlers, CSP and workers - #992

Merged
slayerjain merged 1 commit into
mainfrom
docs/ui-capture-install-bundlers
Nov 20, 2026
Merged

slayerjain merged 1 commit into
mainfrom
docs/ui-capture-install-bundlers

Conversation

@slayerjain

Copy link
Copy Markdown
Member

Docs batch 2 of the UI Testing section (PLAN pages 3.3, 3.10, 3.11, 3.12), for @keploy/capture-sdk 3.1.0 (npm latest).

Pages

Page URL
Install the SDK (Quickstarts) /docs/ui-capture/install-sdk/: replaces the client redirect the 3.0.1 npm README's "Installing the SDK" link hit
Single-page apps and navigation (Guides) /docs/ui-capture/spa-navigation/
Bundlers and frameworks (Guides) /docs/ui-capture/bundlers/
Content-Security-Policy and workers (Guides) /docs/ui-capture/csp-and-workers/

Also: the /ui-capture/install-sdk/ redirect is removed from docusaurus.config.js (the URL stays in verify-ui-capture-sdk-links.js's README_LINKS and now resolves to the page); the sidebar gets the install page under Quickstarts and a Guides category; the overview's install section and the dashboard quickstart's next step link the new pages; llms.txt lists the install page. No anchor or image path changes. No screenshots are new; the SPA page reuses ui-capture-flows.webp.

Cites (every statement was checked against these)

Sources: ui-capture tag v3.1.0 (9bae8002; README = packages/sdk/README.md, byte-identical to the published 3.1.0 tarball's), enterprise-ui main 4a5d8c5d, api-server main 7d97ad0db, samples-typescript main 6231b4e (#116).

Line numbers: README at v3.1.0; samples at 6231b4e.

Page Checked against
ui-capture/install-sdk README:55-112 (install, deps, builds, no script-tag build), 147-158 (no bundler), 165-218 (init, required options, X-API-Key, statics, second init), 188-204 (options), 420-449 (rrweb gate, offline), 465-504 (modes), 506-524 (strict keeps data-testid), 605-614 + 203 (DNT/GPC), 655-703 (credential names, body redaction), 1914-2069 (onError, codes, retries); sdk src/index.ts:162-186 (signals), :276-292 (singleton); samples ui-capture-react-shop/src/keploy.ts:16-60, src/main.tsx:1-2, .env.example, src/vite-env.d.ts, ui-capture-next-shop/instrumentation-client.ts:1-3, lib/keploy.ts:20-21,59-65, .env.example, README.md:31-33,119-124, ui-capture-html-shop/pages/index.html:8-13, app/keploy.js:21-26, server.mjs:27-31, README.md:59-85, package.json; each sample's test/shop.spec.mjs:130-141 (route cause, first-request print); api pkg/http/apiv1/uiingest.go:304-305 (app from the key), uiingest_auth.go:139-141,276 (PAT 403), uicapture_agent.go:196-202 (snippet without privacyMode), pkg/service/uicapture/journeys/plan.go:103-109 (shares of all sessions); eui components/ui-testing/CaptureSetupCard.tsx:58-66 (card snippet); docs ui-capture/errors.md (handle section, capture-declined, pacing)
ui-capture/spa-navigation README:220-379 (page changes, cause, userInitiated, initiator, Navigation API, hash, SvelteKit, wrap-all-or-none), 381-396 (continuous, stop()), 1792-1799 (KUI_E_NAVIGATION_UNWRAPPED); eui app/ui-testing/page.tsx:549-569 (one flow per route, the note); docs release notes §15, errors.md#kui-e-navigation-unwrapped; samples test/shop.spec.mjs:130-131
ui-capture/bundlers README:55-163 (module field, subpath package.jsons, Parcel buffer, worker setups, CDN, no bundler), 1690-1704 (64 KiB cut), 1844-1859 (KUI_E_BODY_WORKER_UNAVAILABLE); sdk package.json:5-80 (exports, module, alias), src/body-worker-start.ts, scripts/build-main.mjs; published 3.1.0 dist/body-worker-start.js (CommonJS: import.meta replaced by {}, so no worker); packages/e2e/package-managers/sdk-bundlers.spec.ts:44-48,128-151,160-371,376,498-513 (the ten cells, versions, babel over node_modules, ES2019 check, request body) and .woodpecker/ci.yml:744-750 (run in CI); docs release notes "Size"
ui-capture/csp-and-workers README:72-91, 113-163, 420-449, 1818-1859, 1940-1941, 2056-2069; sdk src/transport.ts:1444,1928 (uploads by fetch), :1817-1840 (re-queue drops newest), src/body-jobs.ts:95-108 (worker start chunk), src/module-of.ts; docs errors.md (dom-recorder, strict-attributes, request-term, body-worker sections), sessions-and-sampling.md#batching-and-outages
Redirect docusaurus.config.js client-redirects; scripts/verify-ui-capture-sdk-links.js README_LINKS; the 3.0.1 README links /ui-capture/install-sdk/ (ui-capture v3.0.1:packages/sdk/README.md:472); nothing else links it (docs, eui, api-server, SDK 3.1.0, samples)

How the examples were verified

All box runs are Linux amd64 lane containers, nothing on a laptop; no Keploy key is used (each shop posts to its own fake ingest).

  • Sample code (React + Vite, Next.js App Router, plain HTML): every block is copied from samples-typescript main 6231b4e (reformatted only by Prettier 2.8.8; the import map is under prettier-ignore, byte-identical to pages/index.html). Box run: each sample's npm ci, build and npm test (Playwright, Chromium, SDK 3.1.0): 2/2 passed each. The same tests run in each sample's GitHub workflow.
  • CSP policies (csp-and-workers): the React shop's Vite build and the plain HTML shop, served through a proxy adding the header, visited in Chromium (a Playwright spec collecting every page load's securitypolicyviolation events and console lines). The documented policies: no violation, no CSP console line, the body worker ran, bodies recorded, a GraphQL request recorded with its term. worker-src 'none': KUI_E_BODY_WORKER_UNAVAILABLE with "part":"worker", visit still recorded. connect-src 'self': a CSP error per upload, no onError, nothing received. HTML without the import map's hash: an inline-script violation (Chromium's message names the hash) and KUI_E_DOM_RECORDER_UNAVAILABLE. React 3/3, HTML 4/4.
  • esbuild (bundlers): the page's two commands, esbuild 0.28.2 + SDK 3.1.0: rrweb, body redaction, GraphQL and strict chunks emitted; worker copied beside the bundle. That the worker then runs is the SDK's own CI cell (sdk-bundlers.spec.ts).
  • Parcel 2.16.4 (bundlers): one image, fresh directory per case, only CI differing: with CI=1 the build fails with the quoted message; with CI unset Parcel installs buffer itself as a dev dependency; with npm install buffer the build succeeds and emits the worker.
  • Vite and Next.js file names quoted on the pages come from the samples' builds in the same run (dist/assets/*, .next/static/media/body-worker.<hash>.js with Turbopack).

Build

Box job (node:22-bookworm), as keploy/docs CI does: Prettier 2.8.8 --check on changed .md/.js: ok; asset budget: ok; yarn install --frozen-lockfile + lock check: ok; yarn build of origin/main and of this change: 0 warnings each, none added (onBrokenLinks and onBrokenAnchors throw); verify-linkedin-tag, verify-schema, verify-lastmod, verify-moved-urls, verify-ui-capture-sdk-links (49 error sections, 5 refused verbs, 4 README links): ok; /ui-capture/install-sdk/ builds as a page, not a redirect; every new heading anchor present; rendered text matches the Markdown.

Found while writing (product, not docs)

  • The SDK README (3.1.0, "When the server rejects a batch") lists "a key for another app" as a terminal rejection. The ingest server takes the app from the key (api-server uiingest.go:304), so such a key is accepted and records into its own app, with no error. The page says so; the README sentence should change.
  • The README's "Parcel 2 needs the buffer package installed" holds when Parcel's auto-install is off (CI set); without CI, Parcel 2.16 installs it itself.

…d workers

Four new pages in the UI Testing section, for SDK 3.1.0:

- ui-capture/install-sdk: install @keploy/capture-sdk, call init once
  and early, and wire it into a React and Vite app, a Next.js App Router
  app or plain HTML pages, each from the UI capture sample shops; the
  privacy modes, the ingest key in configuration, visitors who send Do
  Not Track or Global Privacy Control, onError, and how to check that
  recordings arrive.
- ui-capture/spa-navigation: what counts as a page change, what a route
  change records (cause, userInitiated, initiator), hash routers,
  routers that keep their own pushState, KUI_E_NAVIGATION_UNWRAPPED, and
  one flow per route.
- ui-capture/bundlers: the bundlers the SDK's tests build it with, where
  there is no body worker, and what Vite, Next.js, webpack 5, webpack 4,
  Parcel 2, esbuild, a page with no bundler and a CDN each need.
- ui-capture/csp-and-workers: what the SDK loads and posts, the
  script-src, worker-src and connect-src it needs, an import map's
  hash, what happens when each is blocked, and service workers and
  offline starts.

/ui-capture/install-sdk/, which the 3.0.1 npm README links, was a
client redirect to the overview's install section; it is now the
install page, and its redirect is removed. The sidebar lists the install
page under Quickstarts and the three others under Guides. The overview's
install section, the dashboard quickstart and the walkthrough link the
new pages, and llms.txt lists the install page.

Signed-off-by: slayerjain <shubhamkjain@outlook.com>
@slayerjain
slayerjain force-pushed the docs/ui-capture-install-bundlers branch from 6f25d84 to 364a6fe Compare November 20, 2026 08:50
@slayerjain
slayerjain merged commit e760ebe into main Nov 20, 2026
6 checks passed
@slayerjain
slayerjain deleted the docs/ui-capture-install-bundlers branch November 20, 2026 08:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant