diff --git a/content/llms-root.txt b/content/llms-root.txt index 9a38b80e0..792e9058e 100644 --- a/content/llms-root.txt +++ b/content/llms-root.txt @@ -66,6 +66,11 @@ Keploy (founded 2021) is a CNCF Landscape project and API testing platform with - [UI Testing REST API](https://keploy.io/docs/ui-capture/rest-api/): Each /client/v1 UI capture operation: ingest keys, capture status, flows, flow graph, journeys, impact, test runs - [UI Testing MCP tools](https://keploy.io/docs/ui-capture/mcp-tools/): The Keploy MCP server's UI capture tools, their inputs and scopes, and how to call them - [UI Testing CLI](https://keploy.io/docs/ui-capture/cli/): keploy login and keploy mcp-install for agents; keploy ui is not in a release build yet +- [Journeys and replay (beta)](https://keploy.io/docs/ui-capture/journeys/): What a journey is, how Keploy selects journeys to test, the journey plan over REST and MCP, shares of sessions; replay is beta and its runner is not in a release build yet +- [Check UI capture in CI](https://keploy.io/docs/ui-capture/ci/): A GitHub Actions check that a build records visits that become flows, with a read-only UI_READER service-account key +- [UI Testing features and availability](https://keploy.io/docs/ui-capture/features/): Every UI Testing feature, its surface (SDK, dashboard, REST, MCP, CLI) and whether it works today +- [UI capture troubleshooting](https://keploy.io/docs/ui-capture/troubleshooting/): Symptoms, causes and fixes: nothing arriving, wrong app, flows not ready, cut bodies, build errors, agents, dashboard +- [Capture SDK reference](https://keploy.io/docs/ui-capture/sdk-reference/): @keploy/capture-sdk entry points, KeployCapture methods, every init and privacy option, error classes, batch format - [UI Capture errors and warnings](https://keploy.io/docs/ui-capture/errors/): Every KUI_E_ code the capture SDK reports, with its cause and fix - [Capture SDK 3.1.0 release notes](https://keploy.io/docs/ui-capture/capture-sdk-3-1-0-release-notes/): What changed in @keploy/capture-sdk 3.1.0 diff --git a/versioned_docs/version-4.0.0/running-keploy/ui-capture.md b/versioned_docs/version-4.0.0/running-keploy/ui-capture.md index b66754729..cdbb17560 100644 --- a/versioned_docs/version-4.0.0/running-keploy/ui-capture.md +++ b/versioned_docs/version-4.0.0/running-keploy/ui-capture.md @@ -59,7 +59,7 @@ Each flow is the sequence of steps a user took on one page, with the network cal | Journeys, and the share of sessions that took each | Beta | Dashboard **Journeys** tab; REST and MCP (`uiJourneys`, `uiJourneyImpact`) | | Replaying journeys as Playwright tests, with mocks | Beta, not runnable yet | The runner is not in a release build yet. | -The SDK only records: generating and running tests is Keploy's side, not the SDK's. A flow's page in the dashboard has a **Generate Test** button. Today it creates a test run that waits for a runner, and in the dashboard's own words: "No runner ships in this release, so the run stays pending until one does." +[Features and availability](../ui-capture/features.md) lists every feature, where you use it and its status. The SDK only records: generating and running tests is Keploy's side, not the SDK's. A flow's page in the dashboard has a **Generate Test** button. Today it creates a test run that waits for a runner, and in the dashboard's own words: "No runner ships in this release, so the run stays pending until one does." ## Set up UI capture @@ -112,27 +112,7 @@ Use the `endpoint` the setup card or the API gives you. It is `https://api.keplo ### SDK options {#sdk-options} -`endpoint` and `apiKey` are the only required options. The others, with the value the SDK uses when you leave them out: - -| Option | Default | What it does | -| --------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `privacyMode` | `"balanced"` | `"balanced"` masks every typed value. `"strict"`, for public sites, also masks all visible text, records no request or response body and replaces every query value in a URL. `"off"` masks only password and hidden fields. | -| `sampleRate` | `1` | Fraction of captures recorded, rolled when `init` starts one: `0.1` records one in ten. | -| `networkCapture` | `true` | Records `fetch` and `XMLHttpRequest` calls. `false` records the page only. | -| `maxSessionDuration` | `600000` | Milliseconds after which a session ends on its own (10 minutes). A later `init` starts a new one. | -| `continuous` | `false` | Keeps capturing for the life of the page, one session at a time: a session that ends is followed by a new one at the visitor's next click, tap or key press. | -| `batchSize` | `50` | Events per request, at most 5,000. | -| `batchInterval` | `5000` | Milliseconds between sends. | -| `maxQueueSize` | `5000` | Events held in memory while waiting to send; past this, the oldest are dropped. | -| `maxBodySize` | `524288` | How much of a request or response body is recorded (512 KB). | -| `maskSelectors` | none | CSS selectors whose text is masked. | -| `unmaskSelectors` | none | CSS selectors whose text is kept in the clear, overriding `maskSelectors` and `"strict"`. It cannot unmask an input value. | -| `privacy` | none | Finer controls: `blockSelectors`, `maskNetworkBodies`, `sensitiveHeaders`, `piiPatterns`, `secretRoutes`, `keepRoutes`, and the two selector lists above. | -| `sessionIdGenerator` | none | Your own session id instead of the SDK's UUID, to correlate with your own systems. | -| `honorPrivacySignals` | `true` | Records nothing for a browser that sends Do Not Track or Global Privacy Control, and reports [`KUI_E_CAPTURE_DECLINED`](../ui-capture/errors.md#kui-e-capture-declined). | -| `onError` | none | Called once when a terminal condition ends the capture. See [UI Capture errors and warnings](../ui-capture/errors.md). | - -The [package's README on npm](https://www.npmjs.com/package/@keploy/capture-sdk) describes each option in full. +`endpoint` and `apiKey` are the only required options. Every other option has a default: `privacyMode: "balanced"`, `sampleRate: 1`, sessions of at most 10 minutes, and Do Not Track and Global Privacy Control honoured. [SDK options and API](../ui-capture/sdk-reference.md#captureconfig) lists each option with its type and default, the `KeployCapture` methods, and the errors `onError` receives. ## Privacy at a glance {#what-the-sdk-records-and-what-it-masks} @@ -161,31 +141,29 @@ The dashboard shows a flow's recorded URLs and calls to people on your team who ## Troubleshooting {#troubleshooting} -An SDK error or warning names a `KUI_E_` code, and [UI Capture errors and warnings](../ui-capture/errors.md) explains each one: what happened, why, and how to fix it. - -**The browser console shows `403` with "this API key is not a UI ingest key".** -The SDK was given a personal access token or another kind of key. Create an ingest key for the app, in the dashboard or with `POST /client/v1/apps//ui/ingest-keys`, and use it as `apiKey`. - -**`capture-status` stays at `NO_SESSIONS`.** -Check the browser's network tab for requests to `/ui/v1/ingest`. If there are none, check that `init` runs in the browser, and that the browser does not send Do Not Track or Global Privacy Control ([`KUI_E_CAPTURE_DECLINED`](../ui-capture/errors.md#kui-e-capture-declined) in the console). A `401` or `403` means the key is not an ingest key, or has been revoked. - -**Sessions arrive in a different app.** -An ingest key records into the app it was created for. Create a key for this app and use it as `apiKey`. - -**Sessions arrive but no flows appear.** -A visit becomes flows 30 minutes after its last activity, or at once when it is completed with `POST /ui/v1/sessions//complete`. `capture-status` shows `RECORDING` until then. A page opened and left untouched still makes a one-step flow, such as `Navigate on /about`. +[Troubleshooting](../ui-capture/troubleshooting.md) lists what goes wrong most often, each with its cause and fix: nothing arriving, sessions in another app, visits that have not become flows, cut bodies, build errors, and what agents and the dashboard run into. An SDK error or warning names a `KUI_E_` code, and [UI Capture errors and warnings](../ui-capture/errors.md) explains each one: what happened, why, and how to fix it. ## Where did a section go? {#where-did-a-section-go} -Parts of this page moved to pages of their own: - -| Section | Now in | -| ----------------------------- | --------------------------------------------------------------------------------- | -| Create an ingest key | [REST API: Create an ingest key](../ui-capture/rest-api.md#create-an-ingest-key) | -| Check that capture is working | [REST API: Capture status](../ui-capture/rest-api.md#capture-status) | -| Read the flows | [REST API: List flows](../ui-capture/rest-api.md#list-flows) | -| Manage ingest keys | [REST API: List ingest keys](../ui-capture/rest-api.md#list-ingest-keys) | -| What an agent sees | [Operate UI capture from an AI agent](../ui-capture/agents.md#what-an-agent-sees) | +This page used to be the whole UI capture guide. Each of the old guide's sections, and where it is now: + +| Section of the old guide | Now in | +| ---------------------------------------- | ---------------------------------------------------------------------------------------------------- | +| How UI Capture works | [How UI capture works](#how-ui-capture-works), on this page | +| Before you begin | [Dashboard quickstart: Before you begin](../ui-capture/quickstart-dashboard.md#before-you-begin) | +| Set up UI Capture in the dashboard | [Dashboard quickstart](../ui-capture/quickstart-dashboard.md) | +| Install the SDK | [Install the SDK](../ui-capture/install-sdk.md) | +| SDK options | [SDK options and API: CaptureConfig](../ui-capture/sdk-reference.md#captureconfig) | +| What the SDK records, and what it masks | [Privacy and masking](../ui-capture/privacy.md) | +| Set up UI Capture with the REST API | [REST API](../ui-capture/rest-api.md) | +| Create an ingest key | [REST API: Create an ingest key](../ui-capture/rest-api.md#create-an-ingest-key) | +| Check that capture is working | [REST API: Capture status](../ui-capture/rest-api.md#capture-status) | +| Read the flows | [REST API: List flows](../ui-capture/rest-api.md#list-flows) | +| Manage ingest keys | [REST API: List ingest keys](../ui-capture/rest-api.md#list-ingest-keys) | +| Set up UI Capture from an AI agent (MCP) | [AI agent quickstart](../ui-capture/quickstart-agent.md) and [MCP tools](../ui-capture/mcp-tools.md) | +| What an agent sees | [Operate UI capture from an AI agent](../ui-capture/agents.md#what-an-agent-sees) | +| Limitations | [Limitations](#limitations), on this page, and [Limits and sizes](../ui-capture/limits.md) | +| Troubleshooting | [Troubleshooting](../ui-capture/troubleshooting.md) | ## Related @@ -194,3 +172,4 @@ Parts of this page moved to pages of their own: - [UI Capture errors and warnings](../ui-capture/errors.md) - [@keploy/capture-sdk 3.1.0 release notes](../ui-capture/capture-sdk-3-1-0-release-notes.md) - [AI agent quickstart](../ui-capture/quickstart-agent.md) +- [Troubleshooting](../ui-capture/troubleshooting.md) diff --git a/versioned_docs/version-4.0.0/ui-capture/agents.md b/versioned_docs/version-4.0.0/ui-capture/agents.md index 26fcda1ae..4e7b8e3bc 100644 --- a/versioned_docs/version-4.0.0/ui-capture/agents.md +++ b/versioned_docs/version-4.0.0/ui-capture/agents.md @@ -116,7 +116,7 @@ The dashboard shows more to people on your team who can view the app: a flow's r - **Generate or run tests.** No tool or REST route creates, claims or completes a UI test run. A run today comes only from a flow page's **Generate Test** in the dashboard, and it stays pending: the runner that replays journeys as Playwright tests, `keploy ui run`, is not in a release build yet. - **Pin a journey** into the plan, or accept a change. -- **Run tests in CI.** No service-account role runs UI tests. A CI job can check capture status and read the plan with a `UI_READER` key, on a paid plan. +- **Run tests in CI.** No service-account role runs UI tests. A CI job can check capture status and read the plan with a `UI_READER` key, on a paid plan: see [Check capture in CI](./ci.md). ## Related diff --git a/versioned_docs/version-4.0.0/ui-capture/ci.md b/versioned_docs/version-4.0.0/ui-capture/ci.md new file mode 100644 index 000000000..0cbd90bb3 --- /dev/null +++ b/versioned_docs/version-4.0.0/ui-capture/ci.md @@ -0,0 +1,174 @@ +--- +id: ci +title: "Check UI capture in CI" +sidebar_label: Check capture in CI +description: Check from a CI job that a build of your web app still records visits that become flows, with an app of its own for CI and a read-only service-account key. +tags: + - UI testing + - UI capture + - CI +keywords: + - UI capture CI + - GitHub Actions + - capture status + - service account + - UI_READER + - ingest key +--- + +import ProductTier from '@site/src/components/ProductTier'; + + + +A CI job can check that a build of your web app still records: it serves the build, drives a few visits in a headless browser, ends each one at once, and waits until Keploy has turned every visit into flows. This page sets that up for GitHub Actions with the [React sample shop](https://github.com/keploy/samples-typescript/tree/main/ui-capture-react-shop), and says what to change for your own app. + +## What CI can do today {#what-ci-can-do-today} + +- **Record visits to a build.** The build carries an ingest key, a scripted browser visits it, and each visit is ended at once with `POST /ui/v1/sessions//complete`, so its flows follow within a minute or two instead of after 30 idle minutes. +- **Read what was recorded.** Capture status, flows, the flow graph and the journey plan are read with an API key: a service-account key bound to the `UI_READER` role on the app, or a personal access token with the `read` scope. +- **Not replay journeys as tests.** Replaying journeys as Playwright tests is in beta, and the `keploy ui` commands, its runner `keploy ui run` among them, are not in a release build yet. No service-account role runs UI tests: `UI_READER` only reads. + +## Keys at build time {#keys-at-build-time} + +The check uses two keys, and they go to different places: + +- **The ingest key goes into the build.** The SDK reads it in the browser, so it is built into the page: as `VITE_KEPLOY_INGEST_KEY` in the React shop, `NEXT_PUBLIC_KEPLOY_INGEST_KEY` in the Next.js shop. An ingest key can only post recordings into its app, so it is safe in a page, but whatever page sends it records into that app. Build what CI visits with the key of the app you keep for CI, never with production's. +- **The read key stays in the CI job.** It reads the app's capture status and flows, so keep it in your CI's secrets and never put it in a build. + +## Keep CI visits out of production journeys {#keep-ci-visits-out-of-production-journeys} + +Give CI an app of its own, such as `storefront-web-ci`. An app's journeys are built from every session it receives in the last 30 days, so scripted visits that record into your production app weigh on its journeys' shares as much as real visitors do. [One app per environment](./ingest-keys.md#one-app-per-environment) explains why. + +Create the app with `POST /client/v1/apps` (see [Create an app](./rest-api.md#create-an-app)), then its ingest key, in the dashboard or with the API: see [Create one](./ingest-keys.md#create-one). A key created in the dashboard does not expire; one created with the API can (`ttlDays`). + +## Create the service account {#create-the-service-account} + +A service account is an identity for a pipeline: it belongs to the organization, not a person, starts with no access, and signs in only with its own keys. Bound to the `UI_READER` role on one app, its key reads that app's capture status, flows, flow graph, journeys, impact and test runs. It cannot create or delete apps, list, mint or revoke ingest keys, or recompute the journey plan. + +You need to be an organization admin, and your organization needs a paid plan: on the Free plan a service account can hold only `MOCK_READER`. Keploy asks you to sign in again first when your sign-in is not recent (**Confirm it's you**). + +1. Click your avatar at the bottom of the sidebar, then **Account Settings**. Under **Account**, click **Service Accounts**. +2. Click **New service account**, give it a **Name**, such as `ui-capture-ci`, and click **Create service account**. Its access opens next. +3. Click **Grant access**, or the **Grant permissions** tab. Under **Where does it apply**, keep **App**, and under **Apps** pick the app you keep for CI. Under **What they can do**, tick **UI_READER**. Under **For how long**, the grant lasts 90 days unless you pick another length or **No expiry**. Click **Grant access**. +4. Back on the **Service Accounts** list, click **Keys** on the account's row, then **New key**. Give it a **Key name**, such as `GitHub Actions`, pick its **Expiration**, from 30 to 365 days (90 by default; a service-account key always expires), and click **Create key**. +5. Copy the key: it is shown only once. Click **I've copied my token**. + +Add the key to your repository as a secret, `KEPLOY_UI_READER_KEY` below. When the grant or the key expires, the key no longer reads the app: create a new key, or grant the role again, before then. + +A personal access token with the `read` scope reads the same data, with its owner's access to the app. + +## A capture check for each pull request {#a-capture-check-for-each-pull-request} + +This workflow builds the React sample shop with the CI app's ingest key, serves the build, runs the shop's five scripted visits, and waits until every visit has become flows. It is written for a copy of the [samples repository](https://github.com/keploy/samples-typescript), where the shop is the folder `ui-capture-react-shop`; in your own repository, set `working-directory` and `cache-dependency-path` to your app's folder. It needs, in the repository's settings: + +- the variable `KEPLOY_CI_APP_ID`: the CI app's ID; +- the secret `KEPLOY_CI_INGEST_KEY`: the CI app's ingest key; +- the secret `KEPLOY_UI_READER_KEY`: the service-account key from above. + +```yaml title=".github/workflows/ui-capture-check.yml" +name: UI capture check + +on: + pull_request: + +# recentSessions lists an app's ten newest sessions: one check at a time. +concurrency: + group: ui-capture-check + cancel-in-progress: false + +jobs: + capture-check: + # Fork and Dependabot pull requests get no Actions secrets: skip them. + if: github.event.pull_request.head.repo.full_name == github.repository && github.actor != 'dependabot[bot]' + runs-on: ubuntu-latest + timeout-minutes: 30 + defaults: + run: + shell: bash + working-directory: ui-capture-react-shop + env: + KEPLOY_API: https://api.keploy.io + KEPLOY_APP_ID: ${{ vars.KEPLOY_CI_APP_ID }} + KEPLOY_API_KEY: ${{ secrets.KEPLOY_UI_READER_KEY }} + VITE_KEPLOY_INGEST_ENDPOINT: https://api.keploy.io/ui/v1/ingest + VITE_KEPLOY_INGEST_KEY: ${{ secrets.KEPLOY_CI_INGEST_KEY }} + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-node@v4 + with: + node-version: 22 + cache: npm + cache-dependency-path: ui-capture-react-shop/package-lock.json + + - name: Install + run: npm ci + + - name: Install Chromium for Playwright + run: npx playwright install --with-deps chromium + + - name: Build with the CI app's ingest key + run: npm run build + + - name: Record five visits, each completed at once + run: | + npm run preview & + timeout 60 bash -c 'until curl -fs http://localhost:4173 >/dev/null; do sleep 1; done' + npm run -s demo:visits | tee visits.log + + - name: Check that every visit became flows + run: | + ui="$KEPLOY_API/client/v1/apps/$KEPLOY_APP_ID/ui" + auth="Authorization: Bearer $KEPLOY_API_KEY" + ids=$(sed -n 's/^visit .* -- session \(.*\) completed$/\1/p' visits.log) + [ -n "$ids" ] || { echo "::error::no visit was recorded"; exit 1; } + for attempt in $(seq 15); do + status=$(curl -fsS "$ui/capture-status" -H "$auth") + waiting=0 + for id in $ids; do + state=$(jq -r --arg id "$id" '.data.recentSessions[] | select(.sdkSessionId == $id) | .status' <<<"$status") + echo "session $id: ${state:-not listed yet}" + case "$state" in + PROCESSED) ;; + FAILED) echo "::error::session $id could not be turned into flows"; exit 1 ;; + *) waiting=1 ;; + esac + done + [ "$waiting" = 0 ] && break + [ "$attempt" = 15 ] && { echo "::error::the visits had no flows after 15 minutes"; exit 1; } + sleep 60 + done + flows=$(curl -fsS "$ui/flows?limit=200" -H "$auth") + for id in $ids; do + sid=$(jq -r --arg id "$id" '.data.recentSessions[] | select(.sdkSessionId == $id) | .id' <<<"$status") + count=$(jq --arg sid "$sid" '[.data[] | select(.sessionId == $sid)] | length' <<<"$flows") + echo "session $id: $count flows" + [ "$count" -gt 0 ] || { echo "::error::session $id made no flow"; exit 1; } + done +``` + +What each part does: + +- **`npm run build`** builds the shop with the two `VITE_KEPLOY_` variables from the job's environment, so the page records into the CI app. +- **`npm run -s demo:visits`** drives five visits through the served build in a headless Chromium. Each visit waits until the capture is recording, ends it with `KeployCapture.stop()`, and completes its session with the ingest key, then prints its session id: `visit 1/5: / > /products > /cart > /checkout -- session completed`. A visit that cannot be completed, such as one whose key was revoked, fails the step. +- **The check** reads [capture status](./rest-api.md#capture-status) once a minute, as often as Keploy extracts flows, until each of this run's sessions, found by its `sdkSessionId` in `recentSessions`, is `PROCESSED`. A `FAILED` session fails the check at once. Then it [lists the flows](./rest-api.md#list-flows), newest first, and checks that each session made at least one: a flow's `sessionId` is the session's `id`. + +The check waits on the run's own sessions, not on the app's `state`. `state` is `FLOWS_READY` as soon as the app has any flow, so on an app that earlier runs recorded into, it says nothing about this run. + +### For your own app {#for-your-own-app} + +Replace the build, serve and visit steps with your own. Your scripted visit has to end its capture and complete its session, and print the session id the check reads. The sample shop shows how: a Playwright init script sets `window.keployScriptedVisit` before the page loads ([`scripts/visits.mjs`](https://github.com/keploy/samples-typescript/blob/main/ui-capture-react-shop/scripts/visits.mjs)), and the shop's own [`src/scripted-visits.ts`](https://github.com/keploy/samples-typescript/blob/main/ui-capture-react-shop/src/scripted-visits.ts) then lets the script call `KeployCapture.stop()` and read `KeployCapture.getSessionId()`. The script completes the session with `POST /ui/v1/sessions//complete` and the ingest key in `X-API-Key`. Ordinary visitors' pages never set that flag, so the hook does nothing for them. + +To visit a preview deploy instead of a build the job serves, point the visits at it: the shop's script takes the address in `SHOP_URL`. That deploy has to be built with the CI app's ingest key too. + +## What the check proves {#what-the-check-proves} + +A green check means the build starts the capture SDK, its ingest key and endpoint are right, and its visits reach Keploy and become flows. It does not compare the flows with earlier ones, and it does not test your app's behaviour: that is what [replay](./journeys.md#replay-beta) is for. If the check fails, [Troubleshooting](./troubleshooting.md) lists the usual causes. + +## Related + +- [Ingest keys and environments](./ingest-keys.md) +- [REST API](./rest-api.md) +- [Sessions and sampling](./sessions-and-sampling.md#end-a-visit-at-once) +- [Operate UI capture from an AI agent](./agents.md) +- [Troubleshooting](./troubleshooting.md) diff --git a/versioned_docs/version-4.0.0/ui-capture/errors.md b/versioned_docs/version-4.0.0/ui-capture/errors.md index 22949f889..4058a976b 100644 --- a/versioned_docs/version-4.0.0/ui-capture/errors.md +++ b/versioned_docs/version-4.0.0/ui-capture/errors.md @@ -23,7 +23,7 @@ keywords: Keploy UI Capture names every error and warning it reports with a `KUI_E_` code, and links each code to its section on this page. Each section says what happened, the exit code, why it happened, and how to fix it, naming only commands that exist. It is written to be acted on by a person or by an AI agent. - **The capture SDK** (`@keploy/capture-sdk`) passes its errors to `onError` and writes its warnings to the console; its exported `SDK_WARNINGS` lists the warnings. An error's `remedy.docs`, and a warning's `SDK_WARNINGS` entry, link here. See [Handle SDK errors and warnings](#handle-sdk-errors-and-warnings) and the table below. -- **The Keploy UI tools**, the `keploy ui` commands, the replay engine and the tools an AI agent calls, return their errors with a `remedy` whose `docs` links here, and exit with the code's exit code. See [Handle errors from the Keploy UI tools](#handle-errors-from-the-keploy-ui-tools), which lists their codes. +- **The Keploy UI tools**, the `keploy ui` commands and the replay engine, return their errors with a `remedy` whose `docs` links here, and exit with the code's exit code. See [Handle errors from the Keploy UI tools](#handle-errors-from-the-keploy-ui-tools), which lists their codes. To set up UI Capture, see [Capture real user flows from your web app](../running-keploy/ui-capture.md). @@ -509,7 +509,7 @@ Then reload the page. The SDK does not retry a load that failed while the page w ## Handle errors from the Keploy UI tools -The `keploy ui` commands, the replay engine that `keploy ui run` drives, and the UI Capture tools an AI agent calls name every failure with a `KUI_E_` code too. Replaying journeys as Playwright tests is in beta, and the `keploy ui` commands, its runner `keploy ui run` among them, are not in a release build yet. A tool error carries: +The `keploy ui` commands and the replay engine that `keploy ui run` drives name every failure with a `KUI_E_` code too. The UI capture tools of the Keploy MCP server are not among them: they answer with the REST API's error codes, such as `INSUFFICIENT_SCOPE`, which [Errors an agent should handle](./agents.md#errors-an-agent-should-handle) lists. Replaying journeys as Playwright tests is in beta, and the `keploy ui` commands, its runner `keploy ui run` among them, are not in a release build yet. A tool error carries: - `code`: the code. Branch on `code` and on the exit code, never on the message. - `severity`: `fatal`, `error` or `warning`. diff --git a/versioned_docs/version-4.0.0/ui-capture/features.md b/versioned_docs/version-4.0.0/ui-capture/features.md new file mode 100644 index 000000000..a929ab2a6 --- /dev/null +++ b/versioned_docs/version-4.0.0/ui-capture/features.md @@ -0,0 +1,97 @@ +--- +id: features +title: "UI Testing features and availability" +sidebar_label: Features and availability +description: Every Keploy UI Testing feature, where you use it (SDK, dashboard, REST API, MCP or CLI), whether it works today, and the page that covers it. +tags: + - UI testing + - UI capture + - reference +keywords: + - UI testing features + - UI capture + - capture SDK + - journeys + - replay beta + - Keploy MCP +--- + +import ProductTier from '@site/src/components/ProductTier'; + + + +What Keploy UI Testing does today, where you use each feature, and the page that explains it. The surfaces are the capture SDK (`@keploy/capture-sdk` 3.1.0, in your web app), the Keploy dashboard (**UI Testing → UI Flows**), the [REST API](./rest-api.md), the Keploy [MCP server](./mcp-tools.md), and the [`keploy` CLI](./cli.md). + +The status of each feature is one of these: + +- **Beta**: works today. The whole of UI Testing is in beta, and the dashboard says so. +- **Beta, not runnable yet**: part of [replay](./journeys.md#replay-beta), which is in beta, and whose runner, `keploy ui run`, is not in a release build yet. You can see it, but no test runs. +- **Available**: a part of Keploy that UI Testing uses but that is not UI Testing's own, such as the apps API. +- **Not available**: not in the product yet. + +## Recording + +| Feature | Surface | Status | Page | +| ----------------------------------------------------------------------------------------- | ------- | ------ | --------------------------------------------------------------------------------- | +| Record each visit: the page, through rrweb, and every `fetch` and `XMLHttpRequest` call | SDK | Beta | [Install the SDK](./install-sdk.md) | +| Mask personal data in the browser: three privacy modes, mask, unmask and block selectors | SDK | Beta | [Privacy and masking](./privacy.md) | +| Honour Do Not Track and Global Privacy Control | SDK | Beta | [Visitors' privacy signals](./privacy.md#visitors-privacy-signals) | +| Keep credentials in your app's URLs out of the recording (`secretRoutes`, `keepRoutes`) | SDK | Beta | [Credentials in URLs](./privacy.md#secret-routes-and-keep-routes) | +| Redact request and response bodies off the main thread, with markers for what is not kept | SDK | Beta | [Network calls and bodies](./network-and-bodies.md) | +| Name each GraphQL operation a request runs (`requestTerm`) | SDK | Beta | [GraphQL](./network-and-bodies.md#graphql) | +| Record a single-page app's route changes, so each step belongs to its page | SDK | Beta | [Single-page apps and navigation](./spa-navigation.md) | +| Sample page loads, keep capturing a long-open page, use your own session ids, pause | SDK | Beta | [Sessions and sampling](./sessions-and-sampling.md) | +| Report errors and warnings with a `KUI_E_` code and a link to its fix | SDK | Beta | [UI Capture errors and warnings](./errors.md) | +| Build with Vite, Next.js, webpack, Parcel, esbuild or no bundler, under a CSP | SDK | Beta | [Bundlers and frameworks](./bundlers.md), [CSP and workers](./csp-and-workers.md) | + +## Setting up + +| Feature | Surface | Status | Page | +| ------------------------------------------------------------------------- | ------------------------------------------ | --------- | --------------------------------------------------------------------- | +| Create an app to record into | REST, MCP | Available | [Create an app](./rest-api.md#create-an-app) | +| Create, list and revoke ingest keys | Dashboard, REST, MCP | Beta | [Ingest keys and environments](./ingest-keys.md) | +| Check that recordings arrive and have become flows | Dashboard, REST, MCP | Beta | [Capture status](./rest-api.md#capture-status) | +| End a visit at once, so its flows follow within minutes | REST (ingest) | Beta | [End a visit at once](./sessions-and-sampling.md#end-a-visit-at-once) | +| Check from CI that a build still records | REST | Beta | [Check capture in CI](./ci.md) | +| A read-only service-account key for one app (`UI_READER`), on a paid plan | Dashboard (create), REST, MCP | Beta | [Create the service account](./ci.md#create-the-service-account) | +| Sign in from a terminal or an agent, and connect an agent | CLI (`keploy login`, `keploy mcp-install`) | Available | [CLI](./cli.md) | +| Set up and read everything from an AI agent | MCP, REST | Beta | [Operate UI capture from an AI agent](./agents.md) | + +## Reading what was recorded + +| Feature | Surface | Status | Page | +| ---------------------------------------------------------------- | -------------------- | ------ | ---------------------------------------------------------------------------- | +| Flows: each page of each visit, with its steps and network calls | Dashboard, REST, MCP | Beta | [From first visit to journeys](./walkthrough-dashboard.md) | +| Journeys and the journey graph, each with its share of sessions | Dashboard, REST, MCP | Beta | [Journeys and replay (beta)](./journeys.md) | +| The journeys Keploy selects to test | Dashboard, REST, MCP | Beta | [Which journeys Keploy selects](./journeys.md#which-journeys-keploy-selects) | +| Recompute the journey plan now (`refresh=true`) | REST, MCP | Beta | [The plan over REST and MCP](./journeys.md#the-plan-over-rest-and-mcp) | +| The share of sessions that took any of a set of journeys | REST, MCP | Beta | [Share of sessions affected](./journeys.md#share-of-sessions) | +| The flow graph | REST, MCP | Beta | [The flow graph](./journeys.md#the-flow-graph) | +| Flows scrubbed for an agent's context | REST, MCP | Beta | [What an agent sees](./agents.md#what-an-agent-sees) | + +## Replay + +| Feature | Surface | Status | Page | +| ---------------------------------------------------------------------------- | --------------------- | ---------------------- | ---------------------------------------------- | +| Replay journeys as Playwright tests, against recorded mocks | CLI (`keploy ui run`) | Beta, not runnable yet | [Replay (beta)](./journeys.md#replay-beta) | +| **Generate Test** on a flow's page: creates a UI test run that stays pending | Dashboard | Beta, not runnable yet | [Replay (beta)](./journeys.md#replay-beta) | +| Read UI test runs and their verdicts | Dashboard, REST, MCP | Beta, not runnable yet | [List test runs](./rest-api.md#list-test-runs) | + +## Not available yet + +| Feature | Notes | +| ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | +| Pin a journey into the test plan | No surface pins one. See [Pinning](./journeys.md#pinning). | +| Recompute the journey plan from the dashboard | Use `refresh=true` over the REST API or MCP. | +| Accept an intended change | On no surface. | +| Run reports by email, and share links | On no surface. | +| A service-account role that runs UI tests in CI | `UI_READER` only reads. | +| The dashboard's **Flow Graph** panel, **Coverage** tab, **Impact Analysis** panel and generated test source | Each says the server does not expose it. The flow graph is on the REST API and MCP. | +| A retention setting for recordings | Recordings have no retention setting. A journey plan is kept 14 days. | + +## Related + +- [UI Testing overview](../running-keploy/ui-capture.md) +- [Limits and sizes](./limits.md) +- [Troubleshooting](./troubleshooting.md) +- [@keploy/capture-sdk 3.1.0 release notes](./capture-sdk-3-1-0-release-notes.md) diff --git a/versioned_docs/version-4.0.0/ui-capture/journeys.md b/versioned_docs/version-4.0.0/ui-capture/journeys.md new file mode 100644 index 000000000..3ddf8af3c --- /dev/null +++ b/versioned_docs/version-4.0.0/ui-capture/journeys.md @@ -0,0 +1,124 @@ +--- +id: journeys +title: "UI journeys and replay (beta)" +sidebar_label: Journeys and replay (beta) +description: What a journey is, how Keploy picks the journeys to test, the Journeys tab, the plan over REST and MCP, shares of sessions, and where replay stands in beta. +tags: + - UI testing + - UI capture + - journeys +keywords: + - user journeys + - journey plan + - share of sessions + - uiJourneys + - uiJourneyImpact + - Playwright replay + - UI test runs +--- + +import ProductTier from '@site/src/components/ProductTier'; + + + +Keploy chains each visit's flows, in order, into the path the visit took through your pages: its **journey**. From the journeys of an app's recent visits it builds a **journey plan**: how sessions move between pages, the journeys they take, each with its share of sessions, and the journeys Keploy selects to replay as tests. This page explains how the plan is built and where to read it: the dashboard's **Journeys** tab, the REST API and MCP. + +:::note Beta +UI Testing is in beta. Journeys and their shares work today. Replaying journeys as Playwright tests is in beta too, and its runner is not in a release build yet: see [Replay (beta)](#replay-beta). +::: + +## What a journey is {#what-a-journey-is} + +A session's journey is the pages it went through, in order: the page it landed on, then the page of each of its flows, in the order they happened. A page that follows itself counts once, and a journey holds at most 16 pages. + +- **A page is its path, with IDs folded.** A path segment that is a number, a UUID, a MongoDB ObjectId or a ULID is written `:id`, a long hexadecimal one `:hash`, and a JWT `:token`, so `/orders/1042` and `/orders/1043` are one page, `/orders/:id`. The query is left out. +- **A session took a journey when its pages start with the journey's pages.** A session that went `/` → `/products` → `/cart` took `/` → `/products` too, so a longer journey's sessions are also in the shorter ones. The plan lists as journeys the paths at least one session took whole, from its landing page to its last. +- **Every figure counts sessions,** one page load of your app with its in-app navigation, never people: the capture SDK carries no identity of the visitor. On a site whose links load pages, each page load is a session of its own, so its journeys are each one page long. See [Sessions and sampling](./sessions-and-sampling.md#what-a-session-is). +- **A journey's ID is stable:** it is computed from its pages, so the same pages have the same ID in every plan. + +A plan reads the app's sessions that started in the last 30 days and have been turned into flows (`PROCESSED`), at most the newest 50,000. A session that reached no page is counted apart, as `sessionsOnNoPage`, and is in no journey and no total. + +## Which journeys Keploy selects to test {#which-journeys-keploy-selects} + +Keploy ranks the journeys by how many sessions took them, the most recently seen first among equals. It then takes them in that order, skipping any that adds no move between pages not yet covered, until the journeys taken cover 80% of the window's moves, or until it has taken 20: + +- **Moves are weighed by sessions.** Each move from one page to the next counts the sessions that made it, and landing on a page counts as a move too. +- **A longer journey replaces a shorter one it continues,** because its test replays the shorter journey's pages too. +- **A journey with no recording to replay is not run.** Each selected journey is replayed from one session: the newest that took exactly that journey with no error response, preferring one that did something on its pages over one that only landed. Its `flowIds` are the recording a test of the journey replays. A journey is not run, and Keploy moves on, when there is no such session: `ERRORS_ONLY` when every session that took exactly that journey got an error response (a status of 400 or more, or no response), and `NO_REPLAYABLE_RECORDING` when none recorded it whole, because each had more than 100 flows. + +The [walkthrough](./walkthrough-dashboard.md#see-the-journeys) works through one plan: five visits along three paths, where a single journey covers 12 of the 15 weighed moves. + +## The Journeys tab {#the-journeys-tab} + +Open **UI Testing → UI Flows**, select your app in the header, and open the **Journeys** tab. It starts with how many sessions it counts, between which days (UTC), and a note on the unit: every figure counts sessions, not users. A note under it says when a bound left sessions out, such as "Only the newest 50,000 sessions in the window were read; older ones are not counted." + +**Journey graph** draws the pages and the moves between them, with each page's share of the sessions that reached it; a move back to a page already on the path is not drawn. The two tables under it are the complete figures: one of pages, with the sessions that reached each page and the sessions that started there, and one of moves, with the sessions that made each move. + +The top of the Journeys tab: the sessions in the last 30 days, the note that every figure counts sessions, and the journey graph with its tables of pages and moves, each with its share of sessions + +**Journey tests** lists the journeys Keploy replays, with the pages in order, the share of sessions, the badges under **Test**, and when a session last took it (**Last seen (UTC)**). **Selected** marks a journey Keploy picked, and **Runs** says a test of it has a recording to replay. A [pinned](#pinning) journey is marked **Pinned**, and **Not run**, with the reason, when it has no recording to replay, such as "every session that took it got an error response, so there is no clean recording to replay". **Other frequent journeys** lists the most taken journeys that are not in the test plan, marked **Not in the test plan**. + +Journey tests with one selected journey and its share of sessions, and Other frequent journeys with the journeys that are not in the test plan + +Each share is the server's: the sessions, the total they are a share of, and the percentage, shown to two decimals. A share under 0.01% shows as `<0.01%`, never as 0. + +When the tab has no plan to show, it says why: **No sessions in this window** when no session started in the last 30 days, and **No session has a journey yet** when sessions were read but none could be counted yet. + +## The plan over REST and MCP {#the-plan-over-rest-and-mcp} + +The same plan is `GET /client/v1/apps/{appId}/ui/journeys` on the REST API, and the tool `uiJourneys` on the Keploy MCP server, with an API key that has the `read` scope and `app:view` on the app. [Journey plan](./rest-api.md#journey-plan) lists its fields with a real answer. What differs from the tab: + +- **Pages are shown as an agent may read them:** a path segment that reads as a secret or a person's data is replaced with `REDACTED`, as in [What an agent sees](./agents.md#what-an-agent-sees), and pages that read alike are one, counted in `pagesMerged`. The graph is cut to 200 pages and 100 moves, and `ranked` to the 50 most taken journeys; what is left out is counted. +- **`freshness` says how current the plan is.** A plan is served for up to 24 hours, or until the sessions processed since it was computed reach a tenth of those it read (at least one; a plan that read the full 50,000 keeps its 24 hours), and the next read then computes a new one. `refresh=true` computes one now, at most once a minute per app; it needs the `write` scope and `testgen:run` on the app. +- **A read may have to wait.** When the server's queue of plan computations is full, or the request ends before its plan is ready, the answer is `429` `RATE_LIMITED`: retry in 10 seconds. + +A plan is kept for 14 days; its `planId` names it in [share of sessions](#share-of-sessions) calls until then. + +## Share of sessions affected {#share-of-sessions} + +`GET /client/v1/apps/{appId}/ui/journeys/impact?planId=&journeyIds=,`, or the MCP tool `uiJourneyImpact`, says how many of a plan's sessions took at least one of a set of its journeys: the share of sessions a change to those journeys would touch. It is a union, never a sum: a session that took two of the journeys counts once, so the share of two journeys can be less than their shares added up. + +- `journeyIds` takes 1 to 100 of the plan's `journeys`, the ones Keploy runs, joined with commas. Over MCP it is one string. +- A journey that is not one of the plan's `journeys` is `400` `INVALID_PARAMETER`; a plan older than 14 days is `404`. + +The [agent walkthrough](./walkthrough-agent.md#share-of-sessions) shows a call and its answer. + +## The flow graph {#the-flow-graph} + +`GET /client/v1/apps/{appId}/ui/flow-graph`, or the MCP tool `uiFlowGraph`, is a second view of how visits move: built from the app's 10,000 most recent flows, a page for each page pattern with its number of flows and its share of sessions, and a link for each move between a session's consecutive flows, with how often it happened and up to five of the flows it led to. Links only go forward in one page order, so moves back to an earlier page are counted in `backLinksDropped`. [Flow graph](./rest-api.md#flow-graph) has a real answer. + +The flow graph is on the REST API and MCP only. The dashboard's **Flow Graph** panel on the **Flows** tab does not draw it: it says that the server does not expose `uiFlowGraph` and that the figure was never measured. + +## Replay (beta) {#replay-beta} + +Replay is what the journey plan is for: Keploy turns the plan's journeys into Playwright tests that replay each journey's recording, its flows, against mocks of the network calls recorded with it. The capture SDK only records; generating and running the tests is Keploy's side. + +Replaying journeys as Playwright tests is in beta, and the `keploy ui` commands, its runner `keploy ui run` among them, are not in a release build yet. So no test runs today, and this page gives no steps to run one. + +What you can see of it today: + +- **Generate Test.** A flow's page in the dashboard has a **Generate Test** button. It creates a UI test run, and says: "Test run `` is PENDING, waiting for a runner. UI tests run in your own CI, not on Keploy's servers: a runner there claims the run, executes it and reports the result here. No runner ships in this release, so the run stays pending until one does." +- **Test runs.** That run is listed on the **Test Runs** tab, as **Pending**, and over the REST API and MCP: [List test runs](./rest-api.md#list-test-runs) and `listUITestRuns`, [Get a test run](./rest-api.md#get-a-test-run) and `getUITestRun`. A pending run has no results, and its `next` says that no runner has claimed it and not to poll for it. No API call creates or runs a test. +- **Verdicts.** A run's results use a closed set of verdicts, shown in the dashboard with these labels: + +| Verdict | Dashboard label | What it means | +| ------------------ | ----------------- | -------------------------------------------------------------- | +| `PASSED` | Passed | Replayed, and no change from the recording. | +| `FAILED` | Failed | A real difference from the recording. | +| `UNCOVERED` | No recording | In scope, but no recording exists to compare to. | +| `UNPROVEN` | Not proven | A comparison was attempted, but its result is not trustworthy. | +| `NONDETERMINISTIC` | Did not reproduce | The run did not reproduce itself. | +| `BLOCKED` | Blocked | The environment stopped it; nothing was measured. | +| `PENDING` | Pending | Not run yet. | + +## Pinning {#pinning} + +A pinned journey is tested whatever its rank, and the plan has room for 50. Pinning is not available to you yet: the dashboard, the REST API and MCP have no way to pin a journey. The plan's `pinned` field, and the tab's **Pinned** badge, are for it. + +## Related + +- [From first visit to journeys](./walkthrough-dashboard.md) +- [REST API: Journey plan](./rest-api.md#journey-plan) +- [MCP tools](./mcp-tools.md) +- [Operate UI capture from an AI agent](./agents.md) +- [Limits and sizes](./limits.md#on-the-server) diff --git a/versioned_docs/version-4.0.0/ui-capture/network-and-bodies.md b/versioned_docs/version-4.0.0/ui-capture/network-and-bodies.md index d02bbdea5..c09c91e2c 100644 --- a/versioned_docs/version-4.0.0/ui-capture/network-and-bodies.md +++ b/versioned_docs/version-4.0.0/ui-capture/network-and-bodies.md @@ -42,7 +42,7 @@ A framework's own requests are recorded like your app's. In the [Next.js sample The SDK starts recording the page's calls only once it has loaded rrweb. `init()` waits for `import("rrweb")` before it patches `fetch` and `XMLHttpRequest`, and your bundler normally puts rrweb in a chunk of its own, fetched over the network. **A call the page makes before that chunk has loaded is not recorded at all**, in a hidden tab as in a visible one. Calling `init()` as early in your app's startup as you can narrows that window; nothing closes it. -So a page's first calls are often missing from its recording. The [React sample shop](https://github.com/keploy/samples-typescript/tree/main/ui-capture-react-shop) imports its `src/keploy.ts` before anything else, and the first page's first request, `GET /api/featured`, is still usually missing. The shop does not hold its own requests back until the capture is recording, because that would make every visit wait for rrweb. +So a page's first calls are often missing from its recording. The [React sample shop](https://github.com/keploy/samples-typescript/tree/main/ui-capture-react-shop) imports its `src/keploy.ts` before anything else, and the first page's first request, `GET /api/featured`, is still usually missing. The SDK holds no request back while rrweb loads: until then `fetch` and `XMLHttpRequest` are still the browser's own, so such a request goes out as it would without the SDK, and is not recorded. An `init()` called while the browser is offline is the exception: it patches `fetch` and `XMLHttpRequest` at once, and sends nothing it records until rrweb has loaded once the browser is back online. If rrweb then cannot load, the capture is refused with [`KUI_E_DOM_RECORDER_UNAVAILABLE`](./errors.md#kui-e-dom-recorder-unavailable), and what it recorded meanwhile is dropped. On a page a service worker controls, `init()` asks for rrweb at once even offline, so precache rrweb's chunk with the rest of your app: a worker that cannot answer that request gets the capture refused, and refused again until the page is reloaded. diff --git a/versioned_docs/version-4.0.0/ui-capture/sdk-reference.md b/versioned_docs/version-4.0.0/ui-capture/sdk-reference.md new file mode 100644 index 000000000..cd69b9eab --- /dev/null +++ b/versioned_docs/version-4.0.0/ui-capture/sdk-reference.md @@ -0,0 +1,215 @@ +--- +id: sdk-reference +title: "@keploy/capture-sdk reference: options and API" +sidebar_label: SDK options and API +description: Every export of the Keploy capture SDK 3.1.0, the KeployCapture methods, each init option and privacy option, the error classes and what a batch carries. +tags: + - UI testing + - UI capture + - capture SDK + - reference +keywords: + - "@keploy/capture-sdk" + - capture SDK + - KeployCapture + - CaptureConfig + - PrivacyConfig + - CaptureError + - SDK options +--- + +import ProductTier from '@site/src/components/ProductTier'; + + + +The public API of `@keploy/capture-sdk` 3.1.0: the files the package ships, the methods of `KeployCapture`, every option `init` takes, the errors `onError` receives, and what each batch carries. The guides explain each one in context: [Install the SDK](./install-sdk.md), [Sessions and sampling](./sessions-and-sampling.md), [Privacy and masking](./privacy.md) and [Network calls and bodies](./network-and-bodies.md). + +## Entry points {#entry-points} + +You import the package by its name. Which file that loads depends on how your build reads the package: + +| You load it with | File | Used by | +| ----------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------- | +| `import` (the `exports` map) | `dist/index.mjs` | Vite, webpack 5, Next.js and esbuild, and a page with no bundler, which imports it by its path | +| `require` (the `exports` map, and `main`) | `dist/index.js` | CommonJS builds, such as a server build of your app, and Node | +| The `module` field | `dist/index.bundler.mjs` | Bundlers that read `module` and not the `exports` map: webpack 4, and Parcel 2 by default | +| `types` | `dist/index.d.ts` | TypeScript | +| The `unpkg` and `jsdelivr` fields | `dist/index.mjs` | Those CDNs; [Assets on a CDN](./bundlers.md#assets-on-a-cdn) says which URLs work | + +`dist/index.bundler.mjs` is the same SDK, built so that webpack 4 never reads `import.meta`, and it loads none of the SDK's files from beside it: a bundler resolves them by name. + +The SDK loads its other files itself, when a capture needs them: `@keploy/capture-sdk/request-term`, `/strict-attributes`, `/body-redact`, `/body-worker-start`, and the body worker `dist/body-worker.js`. Your bundler emits each as a file of your build, where it can: [Bundlers and frameworks](./bundlers.md#where-there-is-no-body-worker) says where the worker is missing. For bundlers that ignore the `exports` map, the package also ships `request-term/package.json`, `strict-attributes/package.json`, `body-redact/package.json` and `body-worker-start/package.json`. [Bundlers and frameworks](./bundlers.md) says what each setup needs, and [Content-Security-Policy and workers](./csp-and-workers.md#what-the-sdk-loads-and-sends) when each file loads. + +There is no script-tag build: the only way in is an `import`. The package's only dependency is `rrweb`, `^2.1.6`. + +## KeployCapture {#keploycapture} + +`KeployCapture` holds the page's one capture. It has static methods only: you never construct it. + +```ts +import {KeployCapture} from "@keploy/capture-sdk"; + +await KeployCapture.init({endpoint, apiKey}); // start; the only call you need +KeployCapture.pause(); // keep the session, record nothing more +KeployCapture.resume(); +KeployCapture.getSessionId(); // "" when no session is live +KeployCapture.getCaptureIdentity(); // the backend join, or why there is none +KeployCapture.getInstance(); // the capture, or null +await KeployCapture.stop(); // stop recording and send what is queued +``` + +### `init(config)` {#init} + +```ts +static init(config: CaptureConfig): Promise +``` + +Starts the capture and resolves to it. `config` is a [`CaptureConfig`](#captureconfig): `endpoint` and `apiKey` are required. While a capture is live, another `init()` returns that same capture and changes nothing, so call it once per page load, not per route. An `init()` made while a `continuous` capture waits for its next session starts that session at once, and a `pause()` in force carries into it. + +`init()` does not reject when the SDK refuses to start, such as for a privacy signal or an invalid option: it resolves, and the error reaches you through `onError`, in a task of its own. Online, it resolves once rrweb has loaded. Don't make your app's rendering wait for it: see [Call init once, as early as you can](./install-sdk.md#call-init-once-as-early-as-you-can). + +### `stop()` {#stop} + +```ts +static stop(): Promise +``` + +Ends the capture: recording stops and the queued events are sent. A body still being read gets up to one second to finish, and is then recorded cut. The promise resolves once the last send has settled; awaiting it is optional. `stop()` releases the capture, so a later `init()` starts a new session, and it ends a `continuous` capture's wait for its next session. When a session that ended on its own still has its last send in flight, `stop()` waits for it too, for at most 10 seconds. + +### `pause()` and `resume()` {#pause-and-resume} + +```ts +static pause(): void +static resume(): void +``` + +`pause()` keeps the session and records nothing more: no DOM event, and no network call that starts or is answered while it is paused. A call still reading its body is recorded at once with what had arrived, cut and marked `...[truncated]`. Between a `continuous` capture's sessions, a pause is kept for the next session. `resume()` records again; a tab that is hidden stays paused until it is shown. [Pause, resume, stop and hidden tabs](./sessions-and-sampling.md#pause-resume-stop) has the details. + +### `getSessionId()` {#getsessionid} + +```ts +static getSessionId(): string +``` + +The live session's id: the SDK's UUID, or what your `sessionIdGenerator` returned. It is `""` when no session is live: before `init()`, after `stop()`, and on a page that `sampleRate` left out. This is the id `POST /ui/v1/sessions//complete` takes, and the one `uiCaptureStatus` lists as `sdkSessionId`. Read it before you call `stop()`, which clears it. + +### `getInstance()` {#getinstance} + +```ts +static getInstance(): KeployCapture | null +``` + +The capture, a sampled-out one included. `null` before `init()`, after `stop()`, after a declined or refused `init()`, and between a `continuous` capture's sessions. + +### `getCaptureIdentity()` {#getcaptureidentity} + +```ts +static getCaptureIdentity(): + | {identity: CaptureIdentity} + | {refusal: "no-csprng"} + | null +``` + +What lets Keploy join this recording to a backend recording of the same requests, exactly as the SDK sends it with each batch. `identity` holds `captureId` (the session id), `sessionNonce` (a random value that tells this run from another run of the same session id), `t0WallMs` (when the capture started, in Unix milliseconds) and `appOrigins` (the page's origin, or none when the page has no usable origin, such as a `data:` URL). `{refusal: "no-csprng"}` means the browser has no `crypto.getRandomValues` to mint the nonce with: the recording is still made, and cannot be joined. It is `null` before a capture has started, and after `stop()`. + +## CaptureConfig {#captureconfig} + +What `init()` takes. Only `endpoint` and `apiKey` are required. + +| Option | Type | Default | What it does | +| --------------------- | ----------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `endpoint` | `string` | required | The ingest endpoint the batches are posted to: `https://api.keploy.io/ui/v1/ingest` on Keploy Cloud, or your API server's URL followed by `/ui/v1/ingest`. The SDK's own requests to it are never recorded. | +| `apiKey` | `string` | required | The app's [ingest key](./ingest-keys.md), sent as `X-API-Key` with every batch. Never another kind of Keploy key. | +| `privacyMode` | `"balanced"`, `"strict"` or `"off"` | `"balanced"` | How much of the page is recorded. See [Choose a privacy mode](./privacy.md#choose-a-privacy-mode). | +| `sampleRate` | `number`, 0 to 1 | `1` | The fraction of captures recorded, rolled when `init()` starts one. See [Sampling](./sessions-and-sampling.md#sampling). | +| `networkCapture` | `boolean` | `true` | Records `fetch` and `XMLHttpRequest` calls. `false` records the page only. | +| `maxSessionDuration` | `number`, milliseconds | `600000` | When a session ends on its own: 10 minutes. | +| `continuous` | `boolean` | `false` | Keeps capturing for the life of the page, one session at a time. No effect with a `sessionIdGenerator`. See [Keep capturing a long-open page](./sessions-and-sampling.md#continuous). | +| `batchSize` | `number` | `50` | Events per request, at most: clamped to 5,000, and a batch is also cut at 10 MiB. | +| `batchInterval` | `number`, milliseconds | `5000` | How often queued events are sent when there is not a full batch; a full batch is sent at once. | +| `maxQueueSize` | `number` | `5000` | Events held unsent. Past it, or past 16 MiB of events, the oldest are dropped. | +| `maxBodySize` | `number`, UTF-16 code units | `524288` | How much of a request or response body is recorded (512 KB). See [Large bodies](./network-and-bodies.md#large-bodies). | +| `maskSelectors` | `string[]` | none | CSS selectors whose text is masked, with every text node below them. Merged with `privacy.maskSelectors`. Input values are decided by `privacyMode` alone. | +| `unmaskSelectors` | `string[]` | none | CSS selectors whose text is kept in the clear, overriding `maskSelectors` and `"strict"` below them. Text only: it cannot unmask an input value. Merged with `privacy.unmaskSelectors`. | +| `privacy` | `Partial` | none | Finer privacy controls: see [PrivacyConfig](#privacyconfig). | +| `sessionIdGenerator` | `() => string` | none | Your own session id instead of the SDK's UUID: 1 to 200 characters of letters, digits, `.`, `-` and `_`, with no empty dot-separated part, returned synchronously. See [Your own session ids](./sessions-and-sampling.md#your-own-session-ids). | +| `honorPrivacySignals` | `boolean` | `true` | Records nothing for a browser that sends Do Not Track or Global Privacy Control, and reports [`KUI_E_CAPTURE_DECLINED`](./errors.md#kui-e-capture-declined). Set `false` only where your site has its own lawful basis and says so in its privacy policy. | +| `onError` | `(err: AnyCaptureError) => void` | none | Called once when a condition ends the capture, or keeps it from starting, with a [`CaptureError`](#errors-and-warnings). Warnings never call it. See [Handle SDK errors and warnings](./errors.md#handle-sdk-errors-and-warnings). | + +## PrivacyConfig {#privacyconfig} + +What the `privacy` option takes. Every field is optional in `privacy`; the default is what applies when you leave it out. + +| Field | Type | Default | What it does | +| ------------------- | ------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `maskSelectors` | `string[]` | `[]` | As `CaptureConfig.maskSelectors`, merged with it. | +| `unmaskSelectors` | `string[]` | `[]` | As `CaptureConfig.unmaskSelectors`, merged with it. | +| `blockSelectors` | `string[]` | `[]` | CSS selectors whose elements are left out of the recording entirely. See [Mask, unmask and block elements](./privacy.md#mask-unmask-and-block-elements). | +| `maskNetworkBodies` | `boolean` | `false` | Records every request and response body as `[MASKED]`, without reading the response. `privacyMode: "strict"` sets it, and refuses `false` beside it with [`KUI_E_PRIVACY_CONFLICT`](./errors.md#kui-e-privacy-conflict). See [Mask every body](./network-and-bodies.md#mask-every-body). | +| `sensitiveHeaders` | `string[]` | the six | Header names whose values are replaced with `[REDACTED]`. Adds to the six that are always redacted, `authorization`, `cookie`, `set-cookie`, `x-api-key`, `x-auth-token` and `proxy-authorization`, and cannot remove them. | +| `piiPatterns` | `PiiPattern[]` | `[]` | Your own patterns, as `{name: string, pattern: RegExp}`, run over headers and bodies, never over URLs. See [Your own patterns](./privacy.md#your-own-patterns). | +| `secretRoutes` | `readonly string[]` | `[]` | Routes of your app whose `:name` segments are credentials, such as `"/invites/:key"`. See [Credentials in URLs](./privacy.md#secret-routes-and-keep-routes). | +| `keepRoutes` | `readonly string[]` | `[]` | Routes whose `:name` segments are your app's own ids, which the SDK would otherwise take for a token, such as `"/teams/invite/:teamId"`. | + +A `secretRoutes` or `keepRoutes` entry that is not a valid route refuses the capture with [`KUI_E_PRIVACY_ROUTE_INVALID`](./errors.md#kui-e-privacy-route-invalid). + +`defaultPrivacyConfig()` returns these defaults, the six headers included. Its `maskNetworkBodies` is `false`, so passing it whole beside `privacyMode: "strict"` is refused with `KUI_E_PRIVACY_CONFLICT`. + +## Errors and warnings {#errors-and-warnings} + +`onError` receives a `CaptureError`, one of these subclasses. Each carries `code`, `status` (the HTTP status, or `null` when the SDK refused before sending anything), `serverMessage`, `issues`, `remedy` (`{command, manual, docs}`, where `docs` links the code's section of [UI Capture errors and warnings](./errors.md)), `evidence` and `message`. In TypeScript, the handler's argument is `AnyCaptureError`, a union of the subclasses, so checking `err.code` narrows `err.evidence` to that code's fields. + +| Class | Codes | `evidence` | +| ------------------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| `IngestRejection` | `KUI_E_INGEST_KEY_REJECTED`, `KUI_E_INGEST_ENDPOINT_NOT_FOUND`, `KUI_E_SESSION_CONFLICT`, `KUI_E_INGEST_REJECTED` | `status`, `serverMessage`, `endpoint`, `sessionId`, `issues` when the server sent them | +| `SessionIdRefusal` | `KUI_E_SESSION_ID_INVALID` | `sessionId`, `received`, `rule` | +| `DomRecorderRefusal` | `KUI_E_DOM_RECORDER_UNAVAILABLE` | `reason` | +| `StrictAttributesRefusal` | `KUI_E_STRICT_ATTRIBUTES_UNAVAILABLE` | `reason` | +| `PrivacyRouteRefusal` | `KUI_E_PRIVACY_ROUTE_INVALID` | `option`, `received`, `rule` | +| `CaptureDeclined` | `KUI_E_CAPTURE_DECLINED` | `signal`: `"doNotTrack"` or `"globalPrivacyControl"` | +| `PrivacyConflict` | `KUI_E_PRIVACY_CONFLICT` | `privacyMode`, `option` | + +Warnings are not errors: the capture goes on, `onError` is not called, and the SDK writes one `console.warn` line with the code. Two tables list every code with its summary, its `remedy` and its evidence fields: + +- `SDK_ERRORS`: the ten error codes above. +- `SDK_WARNINGS`: the six warning codes, `KUI_E_EVENT_UNSERIALISABLE`, `KUI_E_EVENT_OVERSIZED`, `KUI_E_EVENT_OVERSIZED_SCRUBBING`, `KUI_E_NAVIGATION_UNWRAPPED`, `KUI_E_REQUEST_TERM_FAILED` and `KUI_E_BODY_WORKER_UNAVAILABLE`. + +Two helpers read an ingest server's answer as the SDK does: `codeForStatus(status)` returns the code a status ends the capture with, or `null` for a `2xx`, a `429` or a `5xx`, which are not errors; `parseServerError(body)` returns the server's sentence and its `issues`. + +## Other exports {#other-exports} + +The package also exports these, by name: + +- **Privacy:** `PrivacyEngine`, which runs the SDK's masking over your own strings (see [Try your configuration](./privacy.md#try-your-configuration)), and `defaultPrivacyConfig`. +- **Session ids:** `isValidSessionId`, `SESSION_ID_PATTERN`, `SESSION_ID_MAX_LENGTH` (200) and `SESSION_ID_RULE`, the rule as the server words it. +- **Capture identity:** `CaptureIdentityBuilder`, `mintSessionNonce` and `currentOrigin`. +- **The parts `KeployCapture` is built from:** `KeployCaptureRecorder`, `NetworkInterceptor` and `Transport`. +- **A helper:** `describeValue`. +- **Types:** `CaptureConfig`, `PrivacyConfig`, `PiiPattern`, `SessionEvent`, `SessionEventType`, `NetworkEvent`, `NetworkRequestType`, `SessionMetadata`, `CaptureSession`, `TransportPayload`, `TransportConfig`, `EventCallback`, `NetworkEventCallback`, `RecorderState`, `OnEventCallback`, `OnSessionEndCallback`, `CaptureIdentity`, `IdentityRefusal`, and the error types `AnyCaptureError`, `CaptureErrorCode`, `CaptureWarningCode`, `CaptureRemedy`, `CaptureEvidence`, `CaptureWarningEvidence`, `IngestEvidence`, `SessionIdEvidence`, `DomRecorderEvidence`, `PrivacyRouteEvidence`, `CaptureDeclinedEvidence`, `PrivacyConflictEvidence`, `PrivacySignal`, `ServerAnsweredCode`, `ServerError` and `ServerIssue`. + +## What a batch carries {#what-a-batch-carries} + +Each request the SDK posts to `endpoint` has the ingest key in its `X-API-Key` header, and a JSON body, gzipped when the browser has `CompressionStream`, of this shape (`TransportPayload`): + +| Field | What it is | +| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `sessionId` | The session's id. | +| `batchId` | The batch's own id, minted once and sent unchanged with the same events on every retry, so a batch sent twice is stored once. | +| `events` | The batch's events, each a `SessionEvent`: `id`, `sessionId`, `timestamp` (Unix milliseconds), `type` (`"dom"`, `"network"` or `"custom"`), `data`, and `seq`, its place in the session. | +| `metadata` | The page's `url`, `userAgent`, `viewport`, `referrer`, `language`, `devicePixelRatio` and the `timestamp` the session started. | +| `sdk` | `{name, version}`: `version` is the SDK's, such as `3.1.0`. | +| `captureIdentity` | The [capture identity](#getcaptureidentity), or `null` when the capture cannot be joined. | + +A `"dom"` event's `data` is an rrweb event. A `"network"` event's `data` is a `NetworkEvent`: `method`, `url`, `requestHeaders`, `requestBody`, `responseHeaders`, `responseBody`, `statusCode`, `duration` (milliseconds), `type` (`"fetch"` or `"xhr"`) and `requestTerm` (see [GraphQL](./network-and-bodies.md#graphql)), every value masked as [Privacy and masking](./privacy.md) describes. [What leaves the browser](./privacy.md#what-leaves-the-browser) says what else the SDK sends, and to whom. + +## Version differences {#version-differences} + +This page describes 3.1.0. 3.0.1 has no `continuous`, `honorPrivacySignals`, `privacy.secretRoutes` or `privacy.keepRoutes`, its `remedy` has no `docs`, and it raises fewer codes: the note at the top of [UI Capture errors and warnings](./errors.md) lists them. The [3.1.0 release notes](./capture-sdk-3-1-0-release-notes.md) list everything 3.1.0 changes, and the TypeScript changes that can stop a 3.0.1 handler from compiling are in [its section 7](./capture-sdk-3-1-0-release-notes.md#7-typescript-handlers-written-for-301-may-not-compile). + +## Related + +- [Install the SDK](./install-sdk.md) +- [UI Capture errors and warnings](./errors.md) +- [Privacy and masking](./privacy.md) +- [Limits and sizes](./limits.md) +- [@keploy/capture-sdk on npm](https://www.npmjs.com/package/@keploy/capture-sdk) diff --git a/versioned_docs/version-4.0.0/ui-capture/troubleshooting.md b/versioned_docs/version-4.0.0/ui-capture/troubleshooting.md new file mode 100644 index 000000000..c310e59fd --- /dev/null +++ b/versioned_docs/version-4.0.0/ui-capture/troubleshooting.md @@ -0,0 +1,244 @@ +--- +id: troubleshooting +title: "Troubleshooting UI capture" +sidebar_label: Troubleshooting +description: What to do when Keploy UI capture records nothing, records into the wrong app, makes unexpected flows, cuts bodies, or an agent or the dashboard does not do what you expect. +tags: + - UI testing + - UI capture + - troubleshooting +keywords: + - UI capture troubleshooting + - capture SDK + - ingest key + - capture status + - KUI_E_SESSION_CONFLICT + - Keploy MCP +--- + +import ProductTier from '@site/src/components/ProductTier'; + + + +Each entry below is a symptom, its cause and what to do. When the SDK reports a `KUI_E_` code in the browser console or to `onError`, [UI Capture errors and warnings](./errors.md) has that code's own section. The app's [capture status](./rest-api.md#capture-status), on the dashboard's setup card or over the API, is the first thing to read: it says whether recordings arrive and whether they have become flows. + +## Setup {#setup} + +### The console shows `403` and "this API key is not a UI ingest key" {#not-an-ingest-key} + +**Cause:** `apiKey` holds a personal access token or another kind of Keploy key. The ingest endpoint takes only an ingest key. + +**Fix:** Create an ingest key for the app, in the dashboard or with `POST /client/v1/apps//ui/ingest-keys`, and pass it as `apiKey`. See [Ingest keys and environments](./ingest-keys.md). + +### The console shows `401` on the posts to `/ui/v1/ingest` {#ingest-401} + +**Cause:** The key is missing, unknown, expired or revoked, or its app was deleted. A revoked key is refused within about 30 seconds. + +**Fix:** Create a new ingest key for the app and use it. The capture has ended with [`KUI_E_INGEST_KEY_REJECTED`](./errors.md#kui-e-ingest-key-rejected); a new key takes effect on the next page load. + +### The console shows `404` or `405` on the posts {#ingest-404-405} + +**Cause:** `endpoint` is wrong: the route is `/ui/v1/ingest`. + +**Fix:** Use `https://api.keploy.io/ui/v1/ingest` on Keploy Cloud, or your API server's URL followed by `/ui/v1/ingest`. See [`KUI_E_INGEST_ENDPOINT_NOT_FOUND`](./errors.md#kui-e-ingest-endpoint-not-found). + +### Nothing arrives, and the console shows a CORS or Content-Security-Policy error {#cors-or-csp} + +**Cause:** Either the browser refused the request before any status reached the SDK, because the endpoint's path is outside `/ui/v1/` on another origin, or the page's Content-Security-Policy does not allow the endpoint in `connect-src`. The SDK reads either as a network failure: it keeps retrying, and never calls `onError`. + +**Fix:** Check the endpoint, and allow its origin in `connect-src`. See [Content-Security-Policy and workers](./csp-and-workers.md#the-directives-it-needs). + +### Creating a key asks you to "Confirm it's you" {#confirm-its-you} + +**Cause:** Creating or revoking an ingest key in the dashboard needs a recent sign-in. + +**Fix:** Click **Sign in again** and sign in; the dashboard then creates the key. See [Create an ingest key](./quickstart-dashboard.md#create-an-ingest-key). + +## Sessions {#sessions} + +### Capture status stays at `NO_SESSIONS` {#no-sessions} + +**Cause:** No recording has reached the app. Usually `init` does not run in the browser, the key is not this app's, or the browser sends Do Not Track or Global Privacy Control. + +**Fix:** Open the app with the browser's developer tools: the SDK posts to `/ui/v1/ingest` every few seconds while you use the page. A `KUI_E_` code in the console says why it does not. See [Check that it works](./install-sdk.md#check-that-it-works). + +### Sessions arrive in another app {#sessions-in-another-app} + +**Cause:** A page records into the app of the key it sends. The SDK sends no app of its own, so a key made for another app is accepted, and its recordings go into that app, with no error. + +**Fix:** Build the page with an ingest key of the app you mean. The key list (**Ingest keys** on the setup card, or `listUIIngestKeys`) shows each key's prefix, the start of the key, so you can tell which key a page ships. Keep each environment's visits apart with [an app per environment](./ingest-keys.md#one-app-per-environment). + +### Some visitors never show up {#some-visitors-never-show-up} + +**Cause:** The SDK records nothing for a browser that sends Do Not Track or Global Privacy Control, as it does by default, and Brave and DuckDuckGo send Global Privacy Control by default. A `sampleRate` under `1` leaves page loads out too. + +**Fix:** Nothing, for the privacy signals: those visitors said no. See [Visitors' privacy signals](./privacy.md#visitors-privacy-signals) and [Sampling](./sessions-and-sampling.md#sampling). + +### Each page of a site whose links load pages is a session of its own {#one-session-per-page-load} + +**Cause:** A session is one page load of your app with its in-app navigation. A link that loads a page starts a new page, and with it a new capture and a new session. So on such a site, every journey is one page long. + +**Fix:** This is how capture works on such a site; a single-page app keeps one session across its route changes. See [What a session is](./sessions-and-sampling.md#what-a-session-is). + +### `KUI_E_SESSION_CONFLICT` after you completed a visit with its tab open {#session-conflict-after-complete} + +**Cause:** `POST /ui/v1/sessions//complete` ended the session on Keploy's side, and the tab went on recording into it. Its next batch is refused with `409`, and the capture ends with [`KUI_E_SESSION_CONFLICT`](./errors.md#kui-e-session-conflict); with `continuous: true` and the SDK's own session ids, a new session starts at the visitor's next interaction instead. + +**Fix:** Stop the capture before you complete its session: close the tab, or call `KeployCapture.stop()` and wait for it to resolve, as the sample shops' scripted visits do. See [End a visit at once](./sessions-and-sampling.md#end-a-visit-at-once). + +### A tab that comes back after 30 minutes stops recording {#tab-back-after-30-minutes} + +**Cause:** A tab can send no batch for more than 30 minutes while its session is still open: on a computer that slept, or with a `maxSessionDuration` longer than 30 minutes (by default a session ends after 10). By then Keploy has completed the session, so the tab's next batch is refused, and its capture ends with `KUI_E_SESSION_CONFLICT`. + +**Fix:** Set `continuous: true`: with the SDK's own session ids, the capture then starts a new session at the visitor's next click, tap or key press. See [A tab that comes back after 30 minutes](./sessions-and-sampling.md#a-tab-that-comes-back). + +## Flows {#flows} + +### Sessions arrive, but no flows appear {#no-flows-yet} + +**Cause:** A visit becomes flows 30 minutes after its last activity. Until then capture status says `RECORDING`. + +**Fix:** Wait, or end the visit at once with `POST /ui/v1/sessions//complete`: its flows follow within a minute or two. See [End a visit at once](./sessions-and-sampling.md#end-a-visit-at-once). + +### Capture status says `FLOWS_READY` while some visits are still `COMPLETED` {#flows-ready-too-early} + +**Cause:** The state is `FLOWS_READY` as soon as the app has any flow, whatever its other sessions are doing. Visits finished later are still being processed. + +**Fix:** To wait for particular visits, read their sessions: `sessionsByStatus` counts every state, and `recentSessions` gives each recent session's `status` by its `sdkSessionId`. [Check capture in CI](./ci.md#a-capture-check-for-each-pull-request) waits that way. + +### A flow named `Navigate on /…`, with one step {#one-step-navigate-flow} + +**Cause:** A page that was opened and left untouched still makes a flow, of one step: arriving on the page. The texts for `NO_FLOWS` suggest otherwise. The setup card says the visits had no "click, typing or navigation to make a flow from", and capture status says "a page that is only loaded has no flow". Such a page makes this one-step flow. + +**Fix:** Nothing to fix: the flow records that a visitor arrived on the page and did nothing there. See [Read the flows](./walkthrough-dashboard.md#read-the-flows). + +### Capture status says `NO_FLOWS` or `ALL_FAILED` {#no-flows-or-all-failed} + +**Cause:** `NO_FLOWS`: the app's visits were processed, and none made a flow. `ALL_FAILED`: every finished visit failed to be processed; a visit is retried for about two hours first. + +**Fix:** Record a fresh visit that uses the app. If it fails again, contact Keploy support with the `sdkVersion` that `recentSessions` shows. See [Capture status](./rest-api.md#capture-status). + +### A single-page app's visit makes one flow, on the page it landed on {#one-flow-per-visit} + +**Cause:** `@keploy/capture-sdk` 3.0.1 records no route change made by script, so every step of the visit belongs to its first page. 3.1.0 records each route change, and each route is its own flow. + +**Fix:** Upgrade to 3.1.0. `recentSessions` in capture status shows each session's `sdkVersion`. See [Single-page apps and navigation](./spa-navigation.md#before-310). + +### The first page's first requests are missing {#first-requests-missing} + +**Cause:** The SDK records the page's requests only once it has loaded rrweb, which your bundler puts in a chunk of its own. Until then `fetch` and `XMLHttpRequest` are still the browser's own, so a request made in that window goes out as without the SDK, and is not recorded. + +**Fix:** Call `init` as early as you can, from a module your app imports before its own code. That narrows the window; nothing closes it. See [Start capture before your first call](./network-and-bodies.md#start-capture-before-your-first-call). + +## Bodies {#bodies} + +| A body reads | Why | See | +| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| `[Response body not read by the page]` | Your app never read that response's body, so the SDK did not either. A replay sends this text. | [How the SDK reads a body](./network-and-bodies.md#how-the-sdk-reads-a-body) | +| `...[truncated]` at its end | It was longer than `maxBodySize`, or it failed part-way. | [Large bodies](./network-and-bodies.md#large-bodies) | +| `[UNPARSEABLE_BODY_NOT_REDACTED]` | It was JSON longer than `maxBodySize`: a cut JSON body cannot be redacted, so it is not kept. | [Large bodies](./network-and-bodies.md#large-bodies) | +| `[Response body too large: N bytes]` | Its `Content-Length` was over `maxBodySize`, so it was not downloaded. | [Large bodies](./network-and-bodies.md#large-bodies) | +| `[Body cut: K of N characters kept, unverified]` | The page has no body worker, so bodies are redacted on the main thread up to 64 KiB; or the page left, or the capture stopped, with bodies still in the worker; or, with `0` kept, the bodies held for redaction were at their limit. | [Redaction off the main thread](./network-and-bodies.md#redaction-off-the-main-thread) | +| `[Body not captured: …]` | The SDK could not redact it, so it kept none of it. This line follows `[Body cut: 0 of N …]` and says why. | [Redaction off the main thread](./network-and-bodies.md#redaction-off-the-main-thread) | +| `[MASKED]` | `privacyMode: "strict"` or `privacy.maskNetworkBodies: true` records every body that way. | [Mask every body](./network-and-bodies.md#mask-every-body) | +| `[Blob: …]`, `[Binary: …]`, `[ReadableStream]`, `[Unreadable body]` | The body was not text the SDK reads. | [Large bodies](./network-and-bodies.md#large-bodies) | + +## Build and Content-Security-Policy {#build} + +### `KUI_E_DOM_RECORDER_UNAVAILABLE` {#rrweb-does-not-load} + +**Cause:** The browser could not load rrweb: a page with no bundler and no import map for `rrweb`, a Content-Security-Policy that blocks its chunk, or a deployment that dropped it. The capture ends before anything is sent. + +**Fix:** See [`KUI_E_DOM_RECORDER_UNAVAILABLE`](./errors.md#kui-e-dom-recorder-unavailable), and [No bundler](./bundlers.md#no-bundler) for the import map. + +### `parcel build` fails: the `buffer` polyfill is not installed {#parcel-buffer} + +**Cause:** rrweb's build reads Node's `Buffer`, and Parcel does not install the polyfill itself when `CI` is set. The build stops with `Node builtin polyfill "buffer/" is not installed, but auto install is disabled.` + +**Fix:** `npm install buffer`. See [Parcel 2](./bundlers.md#parcel-2). + +### `KUI_E_BODY_WORKER_UNAVAILABLE`, with `"part":"worker"` {#no-body-worker} + +**Cause:** The page cannot run the SDK's body worker: esbuild does not emit it, webpack 4 cannot, a Content-Security-Policy blocks it, or your assets are served from another origin. Bodies over 64 KiB are then recorded cut. + +**Fix:** Under esbuild, copy `node_modules/@keploy/capture-sdk/dist/body-worker.js` beside your bundle; allow `worker-src 'self'`; serve the worker from the page's origin. See [Where there is no body worker](./bundlers.md#where-there-is-no-body-worker). + +## Strict mode {#strict} + +### `KUI_E_PRIVACY_CONFLICT` {#privacy-conflict} + +**Cause:** `privacyMode: "strict"` is set with `privacy.maskNetworkBodies: false`, which asks for the bodies strict leaves out. A `privacy` object built from `defaultPrivacyConfig()` carries that `false`. + +**Fix:** Remove `maskNetworkBodies`, or use `"balanced"`. See [`KUI_E_PRIVACY_CONFLICT`](./errors.md#kui-e-privacy-conflict). + +### `KUI_E_STRICT_ATTRIBUTES_UNAVAILABLE` {#strict-attributes-unavailable} + +**Cause:** Strict could not load its attribute allow-list, a chunk of its own, so it recorded nothing. + +**Fix:** Deploy every chunk your build emits, or serve the package's `dist/` as it is. See [`KUI_E_STRICT_ATTRIBUTES_UNAVAILABLE`](./errors.md#kui-e-strict-attributes-unavailable). + +### A visitor's data shows up under strict {#data-under-strict} + +**Cause:** Strict still records what describes the page's structure, as written: URL paths, `id` and `class` values, a field's `name`, and `data-testid` values. + +**Fix:** Never build a `data-testid`, an `id` or a path from a visitor's data, or block that element with `privacy.blockSelectors`. See [What strict records, and what it doesn't](./privacy.md#what-strict-records). + +## Agents and the API {#agents} + +### The UI capture tools are missing from the MCP server's `tools/list` {#tools-missing} + +**Cause:** The server runs in tool-search mode: `tools/list` shows only its search and setup tools. + +**Fix:** Fetch the tools you need by name with `get_tool_schema`, and run them with `invoke_tool`. See [MCP tools](./mcp-tools.md#the-server). + +### Agents get `401` after weeks of working (`keploy mcp-install`) {#mcp-token-expired} + +**Cause:** The token `keploy mcp-install` mints expires after 90 days. Run again, `mcp-install` hands out the same token from `~/.keploy/mcp.yaml` without checking that it has expired. + +**Fix:** Run `keploy mcp-install --rotate`, then configure again every agent that used the old token. See [Connect your agent](./cli.md#keploy-mcp-install). + +### `429` `RATE_LIMITED` {#rate-limited} + +**Cause:** The API key made more than 100 requests in a minute, or the server's queue of journey plan computations is full. + +**Fix:** Wait, then retry: `Retry-After` seconds over REST; over MCP, which shows no headers, the 10 seconds a refused `uiJourneys` names, otherwise a minute. Poll capture status at most once a minute. See [Waiting and polling](./agents.md#waiting-and-polling). + +### `deleteApp` is refused {#delete-app-refused} + +**Cause:** Deleting an app needs the `admin` scope. A token from an MCP OAuth sign-in never has it, and only organization admins can give it to an API key. + +**Fix:** Delete the app with an admin's API key that has the `admin` scope. See [Delete an app](./rest-api.md#delete-an-app). + +### An ingest key, or a service-account key, is refused by the REST API {#key-refused-by-the-api} + +**Cause:** An ingest key can only post recordings: the REST API refuses it with `403` `INSUFFICIENT_SCOPE`, and the MCP server does not accept it. A service-account key bound to `UI_READER` only reads: it cannot create or delete apps, or list, mint or revoke ingest keys. + +**Fix:** Use a personal access token with the scope the operation needs. See [Errors an agent should handle](./agents.md#errors-an-agent-should-handle). + +## Dashboard {#dashboard} + +### A panel says the figure "was never measured" {#never-measured} + +**Cause:** The **Flow Graph** panel on the **Flows** tab and the **Coverage** tab are not served yet. Each says that the server does not expose it and that the figure was never measured: it is not zero. The **Generated Test** panel on a flow's page says the server does not expose the test's source. + +**Fix:** For the flow graph, use `GET …/ui/flow-graph` or the MCP tool `uiFlowGraph`. See [The flow graph](./journeys.md#the-flow-graph). + +### A test run from **Generate Test** stays pending {#generate-test-pending} + +**Cause:** **Generate Test** creates a UI test run and marks the flow **Test generated**. In the dashboard's own words: "No runner ships in this release, so the run stays pending until one does." Replaying journeys as Playwright tests is in beta, and the `keploy ui` commands, its runner `keploy ui run` among them, are not in a release build yet. + +**Fix:** None yet. See [Replay (beta)](./journeys.md#replay-beta). + +### The **Journeys** tab is empty {#journeys-tab-empty} + +**Cause:** A journey plan reads the app's sessions that started in the last 30 days and have been processed. **No sessions in this window** means there are none; **No session has a journey yet** means sessions were read but none could be counted yet. + +**Fix:** Record a visit and wait until capture status says `FLOWS_READY`, then reload the page. Over the API, `uiJourneys` with `refresh=true` computes a new plan at once; it needs the `write` scope and `testgen:run` on the app. See [Journeys and replay (beta)](./journeys.md). + +## Related + +- [UI Capture errors and warnings](./errors.md) +- [Install the SDK](./install-sdk.md#check-that-it-works) +- [Sessions and sampling](./sessions-and-sampling.md) +- [Operate UI capture from an AI agent](./agents.md) +- [Limits and sizes](./limits.md) diff --git a/versioned_sidebars/version-4.0.0-sidebars.json b/versioned_sidebars/version-4.0.0-sidebars.json index 00d337b3d..691029a3a 100644 --- a/versioned_sidebars/version-4.0.0-sidebars.json +++ b/versioned_sidebars/version-4.0.0-sidebars.json @@ -323,15 +323,20 @@ "ui-capture/bundlers", "ui-capture/csp-and-workers", "ui-capture/ingest-keys", + "ui-capture/ci", + "ui-capture/journeys", "ui-capture/agents" ] }, + "ui-capture/features", + "ui-capture/troubleshooting", { "type": "category", "label": "Reference", "collapsible": true, "collapsed": true, "items": [ + "ui-capture/sdk-reference", { "type": "doc", "id": "ui-capture/errors",