diff --git a/content/llms-root.txt b/content/llms-root.txt index 2e78fb427..13aa917f0 100644 --- a/content/llms-root.txt +++ b/content/llms-root.txt @@ -55,6 +55,13 @@ Keploy (founded 2021) is a CNCF Landscape project and API testing platform with - [Flaky Test Elimination](https://keploy.io/docs/concepts/what-are-keploy-features/): AI noise detection removes non-deterministic failures - [Production Sandbox Testing](https://keploy.io/docs/concepts/what-is-keploy/): Production-like environments without staging infrastructure +## UI Testing (Beta) +- [UI Testing overview](https://keploy.io/docs/running-keploy/ui-capture/): Record real user sessions in a web app with the capture SDK (@keploy/capture-sdk) and read each visit as UI flows and journeys in the dashboard, over the REST API, or from an AI agent through MCP +- [Dashboard quickstart](https://keploy.io/docs/ui-capture/quickstart-dashboard/): Create an ingest key, add it to a sample React shop, and see your first flows +- [From first visit to journeys](https://keploy.io/docs/ui-capture/walkthrough-dashboard/): Record five visits, read their flows and journeys, read the same data from a script, and clean up +- [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 + ## Keploy Cloud & Integrations - [Enterprise plan](https://keploy.io/docs/keploy-cloud/cloud-installation/): Getting started on the Enterprise plan — install Keploy, sign in, and the plan's features - [VS Code Extension](https://keploy.io/docs/keploy-explained/integrations-vscode/): IDE integration for test generation diff --git a/src/components/GetStartedPaths.js b/src/components/GetStartedPaths.js index 8f99705b3..90dad0584 100644 --- a/src/components/GetStartedPaths.js +++ b/src/components/GetStartedPaths.js @@ -7,10 +7,11 @@ import { FaRetweet, FaLaptopCode, FaLayerGroup, + FaMousePointer, } from "react-icons/fa"; import {SiKubernetes} from "react-icons/si"; -// The five entry points rendered as cards below, in display order. Exported +// The six entry points rendered as cards below, in display order. Exported // so the docs home can emit them as an ItemList off the same data the links // are built from -- a hand-copied list in the JSON-LD would quietly rot the // first time one of these paths moves. @@ -42,6 +43,12 @@ export const GET_STARTED_PATHS = [ "Universal Mocker: record your tests' database, queue and API calls once, then replay them offline", href: "/docs/universal-mocker/overview/", }, + { + name: "Record real user flows in your web app", + description: + "UI Testing (Beta): add the capture SDK, then read each visit as UI flows in the Keploy dashboard", + href: "/docs/ui-capture/quickstart-dashboard/", + }, ]; const [ @@ -50,6 +57,7 @@ const [ K8S_PROXY, LOCAL_RECORD, UNIVERSAL_MOCKER, + UI_CAPTURE, ] = GET_STARTED_PATHS; export const GetStartedPaths = () => { @@ -334,6 +342,65 @@ export const GetStartedPaths = () => { + {/* UI Testing: spans both columns, below Universal Mocker */} +
+ A browser SDK records each visit and masks personal data before + it leaves the browser. Read every visit as flows and journeys in + the dashboard, over the API, or from an AI agent. +
++ Add the capture SDK, then read each visit as UI flows in + the Keploy dashboard +
+{subtitle}
++ {subtitle} +
) : null}- Run the tests you need, then gate merges in CI with measurable signals—coverage, drift, performance, security, and data consistency. + Run the tests you need, then gate merges in CI with measurable + signals—coverage, drift, performance, security, and data consistency.
-
- The screenshots on this page are from a local deployment, so they show `http://localhost:8083` where Keploy Cloud shows `https://api.keploy.io`.
-
-2. Under **1. Create an ingest key**, optionally name the key (for example, `production web`) and click **Create ingest key**.
-
- If you signed in more than 15 minutes ago, Keploy asks you to confirm it's you before it creates the key.
-
-3. Copy the key. **It is shown only once.** The SDK snippet under **2. Add the SDK to your app** now contains it.
-
-
-
-4. [Install the SDK](#install-the-sdk) in your app with the snippet, deploy it, and use the app in a browser.
-
-5. Watch **3. Check that sessions arrive**. **Sessions received** counts visits as they arrive, and **Last activity** shows when the SDK last sent anything. **Flows extracted** goes up once a visit has been idle for 30 minutes and Keploy has processed it. The line under the counts says which [state](#check-that-capture-is-working) capture is in: the same state an agent reads from the API. When the first flows are ready, the page switches to its tabs on its own.
-
-
-
-6. Open the **Flows** tab to see each flow, and click a flow to see its steps and network calls.
-
-
-
-
+2. **The capture SDK** runs in your users' browsers. It records the page with [rrweb](https://github.com/rrweb-io/rrweb) and every `fetch` and `XMLHttpRequest` call the page makes, masks personal data in the browser, and posts the recording to Keploy's `/ui/v1/ingest` in batches.
+3. **Keploy ends a visit** after 30 minutes without activity, or at once when the visit is completed with `POST /ui/v1/sessions/
-Install the package:
+Each flow is the sequence of steps a user took on one page, with the network calls those steps made:
-```bash
-npm install @keploy/capture-sdk
-```
-
-Call `init` once, when your app starts, in code that runs in the browser:
-
-```javascript
-import {KeployCapture} from "@keploy/capture-sdk";
-
-await KeployCapture.init({
- endpoint: "https://api.keploy.io/ui/v1/ingest",
- apiKey: "
-Use the `endpoint` the setup card or the API gives you. It is `https://api.keploy.io/ui/v1/ingest` on Keploy Cloud and your own API server's `/ui/v1/ingest` when self-hosted. A self-hosted API server builds it from its `API_SERVER_URL`; if that isn't set to the server's public URL, the API returns an empty `endpoint` and says so in `next`, rather than guessing.
-
-In a server-rendered framework, start the SDK from a client-side effect so it runs only in the browser. For example, in a Next.js App Router layout:
-
-```tsx
-"use client";
-
-import {useEffect} from "react";
-
-export function UICapture() {
- useEffect(() => {
- let stop: (() => void) | undefined;
- void import("@keploy/capture-sdk").then(async ({KeployCapture}) => {
- await KeployCapture.init({
- endpoint: "https://api.keploy.io/ui/v1/ingest",
- apiKey: process.env.NEXT_PUBLIC_KEPLOY_UI_CAPTURE_API_KEY!,
- });
- stop = () => void KeployCapture.stop();
- });
- return () => stop?.();
- }, []);
- return null;
-}
-```
+## What works today {#what-works-today}
-:::caution Use a bundler
-The SDK loads its DOM recorder ([rrweb](https://github.com/rrweb-io/rrweb)) with a package import that your bundler resolves. Loaded on a page without a bundler or an import map, `@keploy/capture-sdk` 3.0.1 starts without an error but cannot record the page: it sends the page's network calls and no clicks, typing or navigation, so sessions arrive and never become flows. From the release that links the [UI Capture errors page](../ui-capture/errors.md), the SDK instead ends the capture before sending anything and reports [`KUI_E_DOM_RECORDER_UNAVAILABLE`](../ui-capture/errors.md#kui-e-dom-recorder-unavailable).
-:::
+| What | Status | Where |
+| -------------------------------------------------- | ---------------------- | -------------------------------------------------------------------------- |
+| Recording visits, masking in the browser | Beta | `@keploy/capture-sdk` 3.1.0 |
+| Flows: each page's steps and network calls | Beta | Dashboard **Flows** tab; REST and MCP (`listUIFlows`, `getUIFlow`) |
+| 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. |
-### SDK options
+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."
-| Option | Default | What it does |
-| -------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `endpoint` | required | The ingest URL. |
-| `apiKey` | required | The app's ingest key. |
-| `privacyMode` | `"balanced"` | `"balanced"` masks every typed value and records visible text. `"strict"` also masks all visible text. `"off"` records typed values. |
-| `networkCapture` | `true` | Records `fetch` and `XMLHttpRequest` calls. Set `false` to record only the page. |
-| `sampleRate` | `1` | Fraction of visits to record, from `0` to `1`. `0.1` records 10% of visits. |
-| `maxSessionDuration` | `600000` | Longest recording of one page load, in milliseconds (10 minutes). When it elapses, recording stops until the next `init` (the next page load). |
-| `maskSelectors` | `[]` | CSS selectors whose text is masked. |
-| `privacy` | — | Finer controls: `blockSelectors`, `maskNetworkBodies`, `sensitiveHeaders`, `piiPatterns`. |
+## Set up UI capture
-### What the SDK records, and what it masks
+You can set it up three ways, and they produce the same result: an ingest key for your app, and the SDK in your frontend.
-- **Typed values** are masked in every input, textarea and select with the default `privacyMode`. Password fields and hidden inputs are masked in every mode, including `"off"`. The values of radio buttons, checkboxes and buttons are not typed and are recorded in every mode; to leave an element out of the recording entirely, list it in `privacy.blockSelectors`.
-- **Visible text** on the page is recorded, unless you use `privacyMode: "strict"` or `maskSelectors`. Strict still records `data-testid` values as written, because replay finds elements by them, so never build one from user data: strict records `row-${email}` with the email in it. To drop an element from the recording entirely, list it in `privacy.blockSelectors`.
-- **Network calls** are recorded with their method, URL (including the query string), status, headers and bodies. The values of the `Authorization`, `Cookie`, `Set-Cookie`, `X-API-Key`, `X-Auth-Token` and `Proxy-Authorization` headers are always replaced with `[REDACTED]`. To stop recording bodies, set `privacy.maskNetworkBodies: true`; to stop recording network calls, set `networkCapture: false`.
-- **A body the SDK could not redact** is never recorded in the clear. The SDK redacts bodies in a Web Worker. At `init()` it asks for the same code for the page's main thread, for when the page is left or the capture stops, and it records the page's network from the start without waiting for either. A body that the SDK must record before it can redact it is recorded as **not captured**: `[Body cut: 0 of N characters kept, unverified]`, where N is the body's length, then a second line that says why, and nothing of the body. Replay never serves such a response body, and reports a test that reaches one as `unproven`; such a request body does not change replay.
- - `[Body not captured: the page left or the capture stopped before redaction was ready]`: a body the worker had not redacted yet when the page was left or the capture stopped, before the main thread's code had loaded; or a request answered while the page was leaving, before the SDK's worker was running. A page that only looked like it was leaving, for example after a link whose response is downloaded as a file, counts as leaving until it is restored from the back/forward cache or your script calls `init()` while no capture is running. It needs no fix, and raises no warning. The [`KUI_E_BODY_WORKER_UNAVAILABLE`](../ui-capture/errors.md#kui-e-body-worker-unavailable) section describes both markers in full.
- - `[Body not captured: the redaction code could not load]`: the code could not load at all, for example because the page's Content-Security-Policy refused it or the server answered 404. The SDK also writes [`KUI_E_BODY_WORKER_UNAVAILABLE`](../ui-capture/errors.md#kui-e-body-worker-unavailable) to the console, and its section says how to fix it.
+### In the dashboard {#set-up-ui-capture-in-the-dashboard}
-The dashboard shows a flow's recorded URLs and calls to people on your team who can view the app. The [REST API and MCP](#what-an-agent-sees) return less.
+Open **UI Testing → UI Flows**, select your app in the header, and follow the setup card: create an ingest key, add the SDK, and check that sessions arrive. The [dashboard quickstart](../ui-capture/quickstart-dashboard.md) walks through it with a sample shop, and the [walkthrough](../ui-capture/walkthrough-dashboard.md) continues to flows and journeys.
-## Set up UI Capture with the REST API
+### With the REST API {#set-up-ui-capture-with-the-rest-api}
Every step is available on the [Keploy Public API](./public-api.md) at `https://api.keploy.io/client/v1`. You need an API key: `write` scope to create or revoke an ingest key, `read` scope for everything else. Replace `
+
+An app with no flows yet opens on **Capture real user flows from your web app**, with a setup card titled **Connect** and your app's name. Its three steps are the rest of this quickstart. Once the app has flows, the same card is under the **Setup** tab.
+
+
+
+## 3. Create an ingest key {#create-an-ingest-key}
+
+The SDK sends what it records with an **ingest key**. An ingest key can only post recordings into this one app, so it is safe to ship in your page's JavaScript. A personal access token does not work in its place.
+
+1. Under **1. Create an ingest key**, optionally type a name for the key, for example `production web`. Without one, the key is named `web` and today's date.
+2. Click **Create ingest key**. If you signed in more than 15 minutes ago, Keploy first asks you to **Confirm it's you**: click **Sign in again** and sign in.
+3. Copy the key. **Copy this key now — it is shown only once.** The snippet under **2. Add the SDK to your app** now contains it, with the ingest endpoint for your Keploy server.
+
+
+
+The key in the screenshot is blanked.
+
+## 4. Add the key to the shop {#add-the-key-to-the-shop}
+
+Put the key in the shop's `.env`, in place of `kep_YOUR_INGEST_KEY`:
+
+```bash title=".env"
+VITE_KEPLOY_INGEST_ENDPOINT=https://api.keploy.io/ui/v1/ingest
+VITE_KEPLOY_INGEST_KEY=kep_YOUR_INGEST_KEY
+```
+
+The endpoint is Keploy Cloud's. If you self-host Keploy, use the endpoint in the card's snippet: your API server's URL followed by `/ui/v1/ingest`.
+
+The shop already does what the card's step 2 says. It installs `@keploy/capture-sdk`, and `src/main.tsx` imports `src/keploy.ts` before anything else, so the capture starts before the app's own code runs. `src/keploy.ts` calls `KeployCapture.init` once, with the endpoint and key from `.env`:
+
+```ts title="src/keploy.ts (excerpt)"
+await KeployCapture.init({
+ endpoint,
+ apiKey,
+ // The default, written out: every typed value is masked, and the page's
+ // visible text is kept. "strict" also masks all visible text and records
+ // no request or response body.
+ privacyMode: "balanced",
+ privacy: {
+ // Text that repeats what the shopper typed: the order confirmation
+ // shows their email, so its text is masked.
+ maskSelectors: ["[data-testid=order-confirmation]"],
+ // Never recorded: the reviews (people's names) are replaced by an
+ // empty box of the same size.
+ blockSelectors: ["[data-testid=reviews]"],
+ // A route whose path holds a credential, such as an invite link, is
+ // declared so its value is kept out of every event. The shop has none:
+ // secretRoutes: ["/invites/:key"],
+ },
+ onError(err) {
+ // The visitor's browser sends Do Not Track or Global Privacy Control:
+ // nothing is recorded, and nothing needs fixing.
+ if (err.code === "KUI_E_CAPTURE_DECLINED") return;
+ console.error(`[shop] Keploy UI capture stopped: ${err.code}`, err.message);
+ },
+});
+```
+
+The card's snippet sets only `endpoint` and `apiKey`. The shop also writes out `privacyMode: "balanced"`, which is the default: every typed value is masked in the browser, and the page's visible text is kept. For a public site, consider `"strict"`, which records no page text.
+
+## 5. Use the shop {#use-the-shop}
+
+Build the shop and serve the build:
+
+```bash
+npm run build && npm run preview
+```
+
+Open `http://localhost:4173` and shop: open **Products**, search for `kettle`, click **Add to cart**, open **Cart**, then **Checkout**.
+
+
+
+The production build is used because `npm run dev` runs React's development checks, which make every request twice, and the recording would show both.
+
+To check that the SDK is recording, open the browser's developer tools:
+
+- the console says `[shop] Keploy UI capture is recording session
+
+A visit ends after 30 minutes without activity, and its flows follow within a few minutes. To see flows sooner, end the visit yourself. Copy its session id from the console line above, close the shop's tab (the SDK sends what it still holds as the page is left), then complete the session with the ingest key in `X-API-Key`:
+
+```bash
+curl -X POST https://api.keploy.io/ui/v1/sessions/
+
+Open the **Flows** tab. Each row is one flow, with the session it came from, when it was last updated and its status. Since SDK 3.1.0 each route a visitor opens is its own flow, so one visit to Products, Cart and Checkout makes a flow for each page. Flow names are made from what happened and where, such as `Fill on /products` or `Click on /cart`.
+
+
+
+Click a flow to open it. Its **Step Timeline** lists each step with its time and page, and **Network Calls** lists each call the steps made, with its method, URL, status and time. What you typed is masked: the search for `kettle` shows as six asterisks.
+
+
+
+## Some visitors never show up {#some-visitors-never-show-up}
+
+The SDK honours Do Not Track and Global Privacy Control by default (`honorPrivacySignals: true`). When a visitor's browser sends either signal, `init()` records, patches and sends nothing for that visitor, and the SDK reports [`KUI_E_CAPTURE_DECLINED`](./errors.md#kui-e-capture-declined) to `onError` and once in the console. Brave and DuckDuckGo send Global Privacy Control by default, so visits from those browsers never appear.
+
+This is not an error to fix. Keep `KUI_E_CAPTURE_DECLINED` out of your error tracking, as the shop's `onError` does. Set `honorPrivacySignals: false` only where your site has its own lawful basis to record such visitors and says so in its privacy policy.
+
+## Next steps
+
+- [From first visit to journeys](./walkthrough-dashboard.md): record five visits along three paths, read their flows and journeys, read the same data from a script, and clean up.
+- [Install the SDK in your own app](../running-keploy/ui-capture.md#install-the-sdk): the same `init` call, in your app's entry point.
+- [UI Capture errors and warnings](./errors.md): what each `KUI_E_` code the SDK reports means and how to fix it.
+
+## Related
+
+- [UI Testing overview](../running-keploy/ui-capture.md)
+- [From first visit to journeys](./walkthrough-dashboard.md)
+- [UI Capture errors and warnings](./errors.md)
+- [@keploy/capture-sdk 3.1.0 release notes](./capture-sdk-3-1-0-release-notes.md)
+- [Keploy Public API](../running-keploy/public-api.md)
diff --git a/versioned_docs/version-4.0.0/ui-capture/walkthrough-dashboard.md b/versioned_docs/version-4.0.0/ui-capture/walkthrough-dashboard.md
new file mode 100644
index 000000000..980f06d2a
--- /dev/null
+++ b/versioned_docs/version-4.0.0/ui-capture/walkthrough-dashboard.md
@@ -0,0 +1,373 @@
+---
+id: walkthrough-dashboard
+title: "UI Testing walkthrough: from first visit to journeys"
+sidebar_label: From first visit to journeys
+description: Record five visits to a sample shop, then read them in the Keploy dashboard as flows and journeys, read the same data from a script, and clean up.
+tags:
+ - UI testing
+ - UI capture
+ - walkthrough
+keywords:
+ - UI capture
+ - capture SDK
+ - UI flows
+ - user journeys
+ - share of sessions
+ - Keploy dashboard
+---
+
+import HowTo from '@site/src/components/HowTo';
+import ProductTier from '@site/src/components/ProductTier';
+
+
+
+Once the first completed visit is processed, the page switches to its tabs on its own, and the card moves to the **Setup** tab. After all five visits, it counts five sessions and their flows:
+
+
+
+## 4. Read the flows {#read-the-flows}
+
+Open the **Flows** tab. Since SDK 3.1.0 each route a visitor opens is its own flow, so a visit to four pages makes four flows. The five visits make 15 flows. Each row names its session, so the flows of one visit share one session.
+
+
+
+A flow's name is a verb and the page it happened on. The verb is `Fill` when something was typed, else `Click` when something was clicked, else `Navigate`: the visitor only arrived. These are the flows the five visits make:
+
+| Flow | Flows | Where they come from |
+| -------------------- | ----- | ---------------------------------------------------------------- |
+| `Click on /` | 5 | Every visit's home page, where each visit clicked a link |
+| `Fill on /products` | 3 | The Products page of the visits that searched (1, 2 and 4) |
+| `Click on /products` | 1 | Visit 5 on the Products page, adding the kettle without a search |
+| `Click on /cart` | 2 | Visits 1 and 2 on the Cart page, clicking through to Checkout |
+| `Fill on /checkout` | 2 | Visits 1 and 2 typing the email address and placing the order |
+| `Navigate on /cart` | 1 | Visit 5 arriving on the Cart page and doing nothing there |
+| `Navigate on /about` | 1 | Visit 3 arriving on the About page |
+
+## 5. Inspect a flow {#inspect-a-flow}
+
+Click a `Fill on /products` flow. The one below is from a visit that searched for `kettle` and added it to the cart. The flow's header shows its status and how many steps and network calls it has, and below it:
+
+- **Step Timeline** lists each step with its time: what was typed or clicked, and on which page. What the visit typed is masked in the browser before it is sent: the search for `kettle` shows as six asterisks.
+- **Network Calls** lists each call the steps made, with its method, URL, status and time. The search's URL keeps its query, `?q=kettle`: under the default `privacyMode: "balanced"`, only typed values are masked, and a query value whose name is not a credential's is kept. `"strict"` replaces every query value.
+
+
+
+## 6. See the journeys {#see-the-journeys}
+
+Open the **Journeys** tab. A **journey** is the path of pages a session took, from the page it landed on. The tab starts with how many sessions it counts, between which days, and a note on the unit: every figure counts **sessions**, one page load of your app with its in-app navigation, not people. The capture SDK cannot tell whether two sessions are the same person.
+
+**Journey graph.** The chart draws the pages and the moves between them, with each page's share of the sessions that reached it. The tables under it are the exact figures: each page with the sessions that reached it and that started there, and each move between two pages with the sessions that made it.
+
+
+
+**Journey tests.** The journeys Keploy selects to replay as tests. A session took a journey when its pages start with the journey's pages, so a longer journey's sessions are also in the shorter ones: the four sessions that went from `/` to `/products` include the three that went on to `/cart`. Each row has its share of sessions, when a session last took it, and badges: **Selected** for a journey Keploy picked; **Runs** when a session recorded the journey whole without an error response, so a test has a recording to replay; and **Not run** with the reason when none did, for example when every session that took it got an error response.
+
+**Other frequent journeys.** The journeys sessions took that are not in the test plan, with the same figures.
+
+
+
+Keploy takes the most taken journeys in turn until they cover 80% of the window's moves between pages, counting each move by the sessions that made it and landing on the first page as a move, and takes at most 20. A journey that continues one already taken replaces it, because its test replays the shorter journey's pages too. Here one journey is enough: `/` → `/products` → `/cart` covers landing on `/` (5 sessions), `/` → `/products` (4) and `/products` → `/cart` (3), which is 12 of the 15 the moves weigh. It replaces `/` → `/products`, which is why that one is listed under **Other frequent journeys**.
+
+Replaying the selected journeys as Playwright tests is in beta, and its runner is not in a release build yet.
+
+## 7. Read the same data from a script {#read-the-same-data-from-a-script}
+
+The same flows and journeys are on the [Keploy Public API](../running-keploy/public-api.md), and as tools on the Keploy MCP server. Use an API key with `read` scope from **Settings → API Keys**, and your app's ID: the setup card's command for a script, under **Setting this up with an AI agent or a script?**, shows it in its URL.
+
+**Capture status.** The same state as the card's, with the counts and the most recent sessions:
+
+```bash
+curl https://api.keploy.io/client/v1/apps/
+
+Pages that use the key stop recording within about 30 seconds. The key stays in the list as revoked.
+
+**Delete the app** if you made it for this walkthrough. Deleting an app needs an API key with the `admin` scope:
+
+```bash
+curl -X DELETE https://api.keploy.io/client/v1/apps/