Skip to content

docs(ui-capture): journeys (beta), CI checks, features, troubleshooting, SDK reference - #994

Merged
slayerjain merged 1 commit into
mainfrom
docs/ui-capture-journeys-ci-reference
Nov 20, 2026
Merged

slayerjain merged 1 commit into
mainfrom
docs/ui-capture-journeys-ci-reference

Conversation

@slayerjain

Copy link
Copy Markdown
Member

The last batch of the UI Testing docs: journeys (beta), a CI capture check, features and availability,
troubleshooting, and the capture SDK reference. It also completes the overview's "Where did a section go?" table and
corrects two sentences of merged pages.

Pages

Page What it is
ui-capture/journeys What a journey is, how the plan selects journeys to test, the Journeys tab, the plan over REST and MCP, shares of sessions, the flow graph, replay (beta, not runnable yet), pinning
ui-capture/ci A GitHub Actions check that a build records visits that become flows; an app for CI; a UI_READER service-account key
ui-capture/features Every feature, its surface and its status
ui-capture/troubleshooting Symptom, cause and fix, by area
ui-capture/sdk-reference Entry points, KeployCapture, every init and privacy option, error classes, exports, the batch format

Changed: running-keploy/ui-capture (SDK options table and troubleshooting move to the new pages, anchors kept; the
section table now maps every heading of the old guide), ui-capture/errors (lines 26 and 512: the Keploy MCP server's
UI tools answer the REST API's error codes, not KUI_E_ codes), ui-capture/network-and-bodies (line 45: what the SDK
does with a request made before rrweb has loaded, per the README at v3.1.0), ui-capture/agents (one link), the
sidebar and llms-root.txt.

Replay is described as beta and not runnable yet, with no runnable steps, in the errors page's own sentence. Generate
Test is quoted as the dashboard words it.

Sources checked

ui-capture tag v3.1.0 (9bae8002), api-server main (963c0ddb4), enterprise-ui main (fe79d3e5), keploy v3.9.4,
samples-typescript main (6231b4ee). Page by page:

ui-capture/sdk-reference

  • Entry points: uic:packages/sdk/package.json:5-36 (exports, module, unpkg, jsdelivr, types, files), :54-56 (rrweb ^2.1.6);
    uic:packages/sdk/scripts/build-main.mjs:1-27 (which build serves which bundler); README:55-110 (no script-tag build,
    chunks, request-term/strict-attributes package.json), :138-145.
  • KeployCapture: uic:packages/sdk/src/index.ts:187-197 (static only, private constructor), :266-289 (init: same
    instance, supersedes continuous wait, keeps pause), :291-317, :319-361 (stop, ENDED_FLUSH_WAIT_MS :102), :362-385
    (pause/resume), :387-389 (getSessionId), :392-394 (getInstance), :395-417 (getCaptureIdentity);
    uic:packages/sdk/src/identity.ts:34-61, :72-80; README:206-218; recorder.ts:1805; errors.md (init resolves on refusal);
    network-and-bodies.md (stop waits 1 s).
  • CaptureConfig: uic:packages/sdk/src/types.ts:45-318; defaults index.ts:209, :228-230, :443; recorder.ts:1368, :1525,
    :2119; README:186-204.
  • PrivacyConfig: types.ts:444-574; privacy.ts:3214-3221 (six headers), :4597-4608 (defaultPrivacyConfig).
  • Errors: uic:packages/sdk/src/errors.ts:76-113 (codes, remedy, entry), :166-232 (SDK_ERRORS), :233-297 (SDK_WARNINGS),
    :450-461 (codeForStatus), :483-505 (parseServerError), :575-633 (evidence types), :635-662 (CaptureError),
    :674-886 (subclasses), :887-894 (AnyCaptureError).
  • Other exports: index.ts:5-74; session-id.ts:22-40.
  • Batch: types.ts:340-420 (SessionEvent, NetworkEvent, SessionMetadata), :577-600 (TransportPayload); transport.ts:414,
    :1162; README:1710-1745.
  • Versions: errors.md:43 (3.0.1 note); capture-sdk-3-1-0-release-notes.md section 7.

ui-capture/ci

  • Capabilities: api:pkg/models/roles.go:52-58, :82-99 (UI_READER, RunnerRoles, app-only); api:pkg/models/permissions.go:607-614;
    api:pkg/http/apiv1/service_account_operation_gate.go:142-159 (UI ops for service accounts), :46-50 (createApp/deleteApp
    refused); api:pkg/http/apiv1/uicapture_journeys.go:196-200 (refresh needs testgen:run); api:pkg/graph/service_accounts.go:125-139,
    :278-285 (Free plan: MOCK_READER only); api:pkg/graph/schema.graphqls:3225-3247 (admin, recent sign-in).
  • Dashboard path: eui:components/app-sidebar.tsx:367-373 (Account Settings), :599-601 (Account), :660-669 (Service Accounts,
    admins only); eui:components/service-accounts/ServiceAccountsTable.tsx:135-148, :221-231, :283-290 (access opens after
    create); ServiceAccountFormDialog.tsx:133, :149, :191; eui:components/rbac/access-drawer/AccessDrawer.tsx:494, :535;
    GrantAccessForm.tsx:109-120, :156, :170-172, :398, :436, :474, :556, :653; ServiceAccountRolePicker.tsx:10;
    ServiceAccountKeysSheet.tsx:110-120, :179; CreateServiceAccountKeyPanel.tsx:37-43, :63, :114, :132, :154;
    eui:components/api-keys/TokenRevealPanel.tsx:87; eui:services/queries/serviceAccounts.ts:17-19;
    eui:components/auth/ReauthenticationDialog.tsx:213; api:pkg/models/role_bindings.go:19, :112 (grant expiry).
  • Keys at build time: install-sdk.md (VITE_, NEXT_PUBLIC_); api:pkg/http/apiv1/uiingest.go:304-305 (app from the key).
  • One app per environment: ingest-keys.md#one-app-per-environment; api:pkg/models/uicapture_journey_plan.go:167.
  • Workflow: samples:ui-capture-react-shop/package.json (scripts, engines), scripts/demo-visits.mjs (SHOP_URL, print line),
    scripts/visits.mjs:118-162 (prepare, leave, complete), src/scripted-visits.ts; api:pkg/service/uicapture/capture_status.go:109-111
    (FLOWS_READY on any flow); api:pkg/platform/mongo/uicapture_ingest.go:1364-1372 (recentSessions newest by start, limit);
    api:pkg/http/apiv1/uicapture_agent.go:377-438 (capture-status view: id, sdkSessionId, status), :441-483 (flows:
    sessionId); api:pkg/platform/mongo/uicapture.go:378-396 (flows sorted created_at desc); api:pkg/service/uicapture/session_sweep.go:40-42 (30 min idle, every minute).
    Run as written against staging: see "The CI workflow, run as written" below.

ui-capture/journeys

  • What a journey is: api:pkg/service/uicapture/journeys/summary.go:24-36, :43-104 (landing, flows in order, page once);
    api:pkg/models/uicapture_journeys.go:44-46 (16 pages, 100 flows); api:pkg/uicapture/canonkey/canonkey.go:78-89,
    :273-289, :459-477 (page pattern); plan.go:104-125 (took = prefix), :545-562 (journeys = paths sessions ended at),
    :180-191 (stable ID); api:pkg/platform/mongo/uicapture_journeys.go:57-70 (PROCESSED, started in window, newest first);
    api:pkg/models/uicapture_journey_plan.go:167-169 (30 days, 50,000); plan.go:143-147 (sessionsOnNoPage).
  • Selection: plan.go:564-574 (rank), :576-635 (greedy, 80%, 20, gain, prefix replaced), :68-69, :456-503 (weights incl.
    entries), :547-561 + :316-327 (representative, exclusions), :29-41; summary.go:106-116 (error = >=400 or 0).
  • Journeys tab: eui:components/ui-testing/JourneysTab.tsx:39-60, :94-123, :125-152, :226-233, :320-340, :358-394,
    :396-497, :499-560; ShareFigure.tsx:14-20, :54-66.
  • REST/MCP: api:pkg/http/apiv1/uicapture_journeys.go:26, :88-110, :151-186, :189-223, :122-141; uicapture_journey_plan.go:177-178,
    :193, :203-230; api:pkg/http/apiv1/openapi.yaml:2625-2632.
  • Impact: plan.go:756-783; uicapture_journeys.go:226-249; rest-api.md#journey-impact; api:pkg/mcp/spec_sync.go:242-249.
  • Flow graph: rest-api.md#flow-graph; eui:services/ui-capture.ts:142-147, :494-497; eui:app/ui-testing/page.tsx:481.
  • Replay: README:8-11, :36-42; ent:cmd/enterprise/cli/ui.go:1-9 (not in a release build); errors.md:512 (same sentence);
    eui:app/ui-testing/[flowId]/page.tsx:555-566, :619 (Generate Test, its words); api:pkg/service/uicapture/uicapture.go:1161-1255
    (PENDING, no results, flow TEST_GENERATED); eui:app/ui-testing/page.tsx:1184-1187 (Test Runs tab);
    api:pkg/http/apiv1/uicapture_test_runs.go:312-316 (pending next); api:pkg/models/uicapture.go:35-110 (verdicts and
    meanings); eui:components/ui-testing/StatusBadge.tsx:73-110 (labels).
  • Pinning: plan.go:75, :637-690; no pin control in eui (grep: no pinUIJourney/refreshUIJourneyPlan use) or in openapi.yaml.

ui-capture/features

  • Each row: the page it links (each checked against its own cites in batches 1-4 and above); status: eui:constants/navItems.ts:160-171
    and eui:components/app-sidebar.tsx:514-517 (Beta); ent:cmd/enterprise/cli/ui.go:1-9 (keploy ui not in release);
    eui:services/ui-capture.ts:142-147, :428, :496, :546, :594 (panels not served); eui:app/ui-testing/[flowId]/page.tsx:307-329;
    api:pkg/models/uicapture.go:421-422 (no retention decision); uicapture_journey_plan.go:193 (plans 14 days); G6 (no pin,
    accept, report, email, share: eui has no control; openapi has no route); roles.go:52-58.

ui-capture/troubleshooting

  • Setup: api:pkg/http/apiv1/uiingest.go:35-54; errors.md (each code); uiingest_auth.go:39-46 (30 s);
    eui:services/queries/ui-capture.ts:301-303 + ReauthenticationDialog.tsx:213-262 (Confirm it's you); csp-and-workers.md.
  • Sessions: capture_status.go:110-121 (NO_SESSIONS); uiingest.go:304-305 (app from key); ingest-keys.md (keyPrefix);
    README:203, :605-614 (signals), :186-204 (sampleRate); index.ts:188, :277 (one capture per page); uiingest.go:307-309 +
    errors.ts:450-461 (409 -> KUI_E_SESSION_CONFLICT); samples:ui-capture-react-shop/src/scripted-visits.ts (stop, then
    complete); session_sweep.go:40-42 (30 min); README:381-396 (continuous).
  • Flows: capture_status.go:109-133 (states, texts); api:pkg/service/uicapture/flowengine/extract.go:440-466 +
    dedup.go:214-216 (one-step Navigate flow); eui:components/ui-testing/CaptureSetupCard.tsx:131-134 (NO_FLOWS card text);
    spa-navigation.md#before-310; README:420-427 (first requests).
  • Bodies: network-and-bodies.md (each marker, README:1383-1708).
  • Build/strict: errors.md; bundlers.md#parcel-2 (batch 2 box run uicb2-parcelci1); privacy.md#what-strict-records.
  • Agents: mcp-tools.md#the-server; api:pkg/http/mcp.go:35 (90 days); ent:cmd/enterprise/cli/mcp_install.go:976-1000 (cached
    token reused), :930-931 (--rotate); agents.md#waiting-and-polling; rest-api.md#delete-an-app; agents.md#errors-an-agent-should-handle.
  • Dashboard: eui:services/ui-capture.ts:142-147, :428, :496; [flowId]/page.tsx:320-329, :555-566;
    api:pkg/service/uicapture/uicapture.go:1257-1260 (TEST_GENERATED); StatusBadge.tsx:83; JourneysTab.tsx:320-340.

running-keploy/ui-capture (landing)

  • SDK options summary: sdk-reference cites above. Section table: old headings from docs 5dc0620 running-keploy/ui-capture.md.

ui-capture/errors.md (lines 26, 512)

  • The Keploy MCP server's UI tools answer the REST API's errors: api:pkg/mcp/spec_sync.go:26-186 (tools generated from the
    OpenAPI operations), mcp-tools.md#call-a-tool (a staging answer: RESOURCE_NOT_FOUND), agents.md#errors-an-agent-should-handle.
    KUI_E_ codes come from the keploy ui tree (ent:cmd/enterprise/cli/ui.go:1-9, uic:packages/contract/src/tools.ts:1-40).

ui-capture/network-and-bodies.md:45

  • README:420-427 ("Until the import resolves, fetch and XMLHttpRequest are still the browser's own: a request the page
    makes in that window is not recorded at all").

The CI workflow, run as written

The YAML block on ui-capture/ci was extracted from the page and run step by step on a box against staging, with a
disposable app created and deleted on every path (the hosts set to staging's, Node 22.23.5, the sample at main):

  • Positive: npm ci, npx playwright install --with-deps chromium, npm run build with the key from the job's
    environment, five scripted visits each completed, then the check: its first poll found four sessions PROCESSED and
    one COMPLETED, the second all five PROCESSED, with 4, 4, 2, 2 and
    3 flows. All steps passed.
  • Negative: the key revoked, the visit step fails (the SDK reports KUI_E_INGEST_KEY_REJECTED; completing the session
    is refused with 401).
  • Reads used a personal access token: a service account cannot be created without an interactive sign-in. What a
    UI_READER key may read is cited from the operation gate.
  • The job's if, which skips fork and Dependabot pull requests (they get no Actions secrets), is GitHub's to evaluate:
    the run executed every run: step, which it does not change.

No screenshots are new: the journeys page reuses the two Journeys-tab images from the dashboard walkthrough.

Checks run on a box

On this commit, the repository's CI steps in a node:22-bookworm container: prettier 2.8.8 on every changed .md
(ok), the asset budget (ok: no new image; the two reused images resolve), yarn install --frozen-lockfile (lock ok),
yarn build of main and of this branch (0 warning lines on either, none new), verify-linkedin-tag, verify-schema,
verify-lastmod, verify-moved-urls and verify-ui-capture-sdk-links (49 error sections, 5 refused verbs, 4 README
links): all ok. Every heading id of the new pages and every kept anchor of the overview is in the built HTML, and
llms.txt and the sitemap list the five pages.

…ng, SDK reference

The last pages of the UI Testing section:

- ui-capture/journeys: what a journey is, how the plan selects journeys to
  test, the Journeys tab, the plan over REST and MCP, shares of sessions,
  the flow graph, and replay as beta with its runner not in a release
  build; Generate Test in the dashboard's own words; pinning not
  available.
- ui-capture/ci: a GitHub Actions check that a build records visits that
  become flows, with an app for CI and a UI_READER service-account key.
  It waits on the run's own sessions, since FLOWS_READY holds as soon as
  an app has any flow. The workflow was run as written against staging.
- ui-capture/features: every feature, its surface and its status.
- ui-capture/troubleshooting: symptoms, causes and fixes, by area.
- ui-capture/sdk-reference: entry points, KeployCapture, every init and
  privacy option, the error classes, other exports, the batch format.

The overview's SDK options table moves to the SDK reference and its
troubleshooting to the new page; "Where did a section go?" now maps every
heading of the old guide. errors.md no longer says the Keploy MCP
server's UI tools name failures with KUI_E_ codes (they answer the REST
API's codes), and network-and-bodies.md says what the SDK does with a
request made before rrweb has loaded. Sidebar and llms-root list the new
pages.

Signed-off-by: slayerjain <shubhamkjain@outlook.com>
@slayerjain
slayerjain merged commit f5bb878 into main Nov 20, 2026
6 checks passed
@slayerjain
slayerjain deleted the docs/ui-capture-journeys-ci-reference branch November 20, 2026 10:03
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