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 */} +
+ {/* Decorative gradient blob */} +
+ +
+
+ {/* Icon Badge */} +
+ +
+ + {/* Path Label */} +
+ + UI Testing + + + Beta + +
+ + {/* Content */} +

+ Capture Real User Flows From Your Web App +

+

+ 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. +

+
+ +
+ +
+
+ +
+
+

+ Record real user flows in your web app +

+

+ Add the capture SDK, then read each visit as UI flows in + the Keploy dashboard +

+
+
+ + → + + +
+
+
); diff --git a/src/components/QuickStartTabs.js b/src/components/QuickStartTabs.js index cd068fabc..583f15751 100644 --- a/src/components/QuickStartTabs.js +++ b/src/components/QuickStartTabs.js @@ -11,6 +11,10 @@ import { FaDownload, FaCircle, FaTerminal, + FaMousePointer, + FaKey, + FaCode, + FaStream, } from "react-icons/fa"; export const QuickStartTabs = () => { @@ -77,6 +81,36 @@ export const QuickStartTabs = () => { primary: false, }, }, + ui: { + id: "ui", + label: "UI Capture Quickstart", + time: "10 min", + icon: FaMousePointer, + color: "gray", + headline: "Quickstart: UI Capture (Beta)", + steps: [ + { + icon: FaKey, + title: "Create an ingest key", + description: "In the dashboard's UI Testing setup card", + }, + { + icon: FaCode, + title: "Add the SDK to your app", + description: "Or run the sample React shop", + }, + { + icon: FaStream, + title: "See your flows", + description: "Each visit's steps and network calls", + }, + ], + cta: { + label: "Start UI Capture Quickstart", + link: "/docs/ui-capture/quickstart-dashboard/", + primary: false, + }, + }, }; return ( @@ -95,8 +129,8 @@ export const QuickStartTabs = () => {

- {/* Two Quickstart Tiles */} -
+ {/* Quickstart Tiles */} +
{Object.values(tabs).map((tab) => { const isActive = activeTab === tab.id; const Icon = tab.icon; diff --git a/src/components/TestingCapabilities.js b/src/components/TestingCapabilities.js index 2dce35280..625a4d4fa 100644 --- a/src/components/TestingCapabilities.js +++ b/src/components/TestingCapabilities.js @@ -8,6 +8,7 @@ import { FaCamera, FaTachometerAlt, FaShieldAlt, + FaMousePointer, } from "react-icons/fa"; const capabilities = { @@ -15,33 +16,104 @@ const capabilities = { title: "Functional", color: "orange", items: [ - { icon: FaSync, label: "Regression testing", subtitle: "Catch behavior regressions in CI" }, - { icon: FaCubes, label: "Integration testing", subtitle: "Validate dependencies (DB/queues/services)" }, - { icon: FaRoute, label: "Flow testing (multi-step)", subtitle: "API journeys with setup + cleanup" }, - { icon: FaPlug, label: "API testing", subtitle: "Endpoint assertions across environments" }, - { icon: FaShieldAlt, label: "Contract testing", subtitle: "OpenAPI contract expectations" }, - { icon: FaCamera, label: "Schema testing", subtitle: "Field-level request/response validation" }, - { icon: FaDatabase, label: "DB validation tests", subtitle: "DB invariants and mutation checks" }, - { icon: FaTachometerAlt, label: "Chaos & fuzz tests", subtitle: "Fault + input chaos testing", badge: "Upcoming" }, + { + icon: FaSync, + label: "Regression testing", + subtitle: "Catch behavior regressions in CI", + }, + { + icon: FaCubes, + label: "Integration testing", + subtitle: "Validate dependencies (DB/queues/services)", + }, + { + icon: FaRoute, + label: "Flow testing (multi-step)", + subtitle: "API journeys with setup + cleanup", + }, + { + icon: FaPlug, + label: "API testing", + subtitle: "Endpoint assertions across environments", + }, + { + icon: FaShieldAlt, + label: "Contract testing", + subtitle: "OpenAPI contract expectations", + }, + { + icon: FaCamera, + label: "Schema testing", + subtitle: "Field-level request/response validation", + }, + { + icon: FaDatabase, + label: "DB validation tests", + subtitle: "DB invariants and mutation checks", + }, + { + icon: FaMousePointer, + label: "UI journey capture", + subtitle: "Real user flows and journeys from your web app", + badge: "Beta", + }, + { + icon: FaTachometerAlt, + label: "Chaos & fuzz tests", + subtitle: "Fault + input chaos testing", + badge: "Upcoming", + }, ], }, qualityGates: { title: "Quality Gates", color: "purple", items: [ - { icon: FaCubes, label: "Code Coverage", subtitle: "Line/branch coverage gates" }, - { icon: FaPlug, label: "Schema / API Business Coverage", subtitle: "% API paths + fields exercised" }, - { icon: FaCamera, label: "Baseline assertions", subtitle: "Behavior diffs after normalization" }, - { icon: FaShieldAlt, label: "Contract drifts detection", subtitle: "Breaking changes vs OpenAPI" }, - { icon: FaTachometerAlt, label: "Load & performance metrics", subtitle: "p95 latency + error-rate regression" }, - { icon: FaShieldAlt, label: "Security checks", subtitle: "Auth/schema/input validation" }, - { icon: FaDatabase, label: "Data consistency gate", subtitle: "Cleanup + DB invariants" }, - { icon: FaSync, label: "Crash free rate", subtitle: "0 crashes/panics across runs" }, + { + icon: FaCubes, + label: "Code Coverage", + subtitle: "Line/branch coverage gates", + }, + { + icon: FaPlug, + label: "Schema / API Business Coverage", + subtitle: "% API paths + fields exercised", + }, + { + icon: FaCamera, + label: "Baseline assertions", + subtitle: "Behavior diffs after normalization", + }, + { + icon: FaShieldAlt, + label: "Contract drifts detection", + subtitle: "Breaking changes vs OpenAPI", + }, + { + icon: FaTachometerAlt, + label: "Load & performance metrics", + subtitle: "p95 latency + error-rate regression", + }, + { + icon: FaShieldAlt, + label: "Security checks", + subtitle: "Auth/schema/input validation", + }, + { + icon: FaDatabase, + label: "Data consistency gate", + subtitle: "Cleanup + DB invariants", + }, + { + icon: FaSync, + label: "Crash free rate", + subtitle: "0 crashes/panics across runs", + }, ], }, }; -const CapabilityItem = ({ icon: Icon, label, subtitle, badge, color }) => { +const CapabilityItem = ({icon: Icon, label, subtitle, badge, color}) => { const colorClasses = { orange: { chipBorder: "border-orange-200/70 dark:border-orange-500/30", @@ -49,7 +121,8 @@ const CapabilityItem = ({ icon: Icon, label, subtitle, badge, color }) => { chipText: "text-orange-700 dark:text-orange-200", iconBg: "bg-orange-100 dark:bg-orange-900/20", iconText: "text-orange-600 dark:text-orange-300", - hover: "hover:bg-orange-100/70 dark:hover:bg-orange-900/20 hover:border-orange-300/80 dark:hover:border-orange-500/40", + hover: + "hover:bg-orange-100/70 dark:hover:bg-orange-900/20 hover:border-orange-300/80 dark:hover:border-orange-500/40", }, purple: { chipBorder: "border-purple-200/70 dark:border-purple-500/30", @@ -57,7 +130,8 @@ const CapabilityItem = ({ icon: Icon, label, subtitle, badge, color }) => { chipText: "text-purple-700 dark:text-purple-200", iconBg: "bg-purple-100 dark:bg-purple-900/20", iconText: "text-purple-600 dark:text-purple-200", - hover: "hover:bg-purple-100/70 dark:hover:bg-purple-900/20 hover:border-purple-300/80 dark:hover:border-purple-500/40", + hover: + "hover:bg-purple-100/70 dark:hover:bg-purple-900/20 hover:border-purple-300/80 dark:hover:border-purple-500/40", }, }; @@ -69,10 +143,14 @@ const CapabilityItem = ({ icon: Icon, label, subtitle, badge, color }) => { className={`inline-flex max-w-full items-center gap-2 rounded-full border px-3 py-1.5 text-sm transition-all ${classes.chipBorder} ${classes.chipBg} ${classes.hover}`} title={subtitle || label} > - + - {label} + + {label} + {badge ? ( {badge} @@ -82,7 +160,9 @@ const CapabilityItem = ({ icon: Icon, label, subtitle, badge, color }) => { {/* Subtitle: visible on mobile, tooltip-only on desktop */} {subtitle ? ( -

{subtitle}

+

+ {subtitle} +

) : null}
); @@ -100,7 +180,8 @@ export const TestingCapabilities = () => { Whatever your testing strategy, Keploy fits

- 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.

@@ -113,7 +194,9 @@ export const TestingCapabilities = () => {

{capabilities.functional.title}

- • What you run + + • What you run +
@@ -140,7 +223,9 @@ export const TestingCapabilities = () => {

{capabilities.qualityGates.title}

- • What blocks/permits merges + + • What blocks/permits merges +
@@ -164,7 +249,8 @@ export const TestingCapabilities = () => { ✓ - Same test assets can be reused across environments (local → CI → staging) with consistent assertions. + Same test assets can be reused across environments (local → CI → + staging) with consistent assertions.

@@ -172,4 +258,3 @@ export const TestingCapabilities = () => { }; export default TestingCapabilities; - diff --git a/src/pages/index.js b/src/pages/index.js index 59a216de3..d5ee8ac15 100644 --- a/src/pages/index.js +++ b/src/pages/index.js @@ -48,7 +48,7 @@ export default function Home() { // single author, publication date or headline. DocItem already suppresses // Article on /docs/ for exactly that reason, so emitting one here left the // site's only generic Article on the page the rule was written for. The - // ItemList mirrors the five entry points GetStartedPaths renders. + // ItemList mirrors the six entry points GetStartedPaths renders. const collectionPageSchema = docsUrl ? { "@context": "https://schema.org", diff --git a/static/img/ui-capture/ui-capture-demo-shop.webp b/static/img/ui-capture/ui-capture-demo-shop.webp new file mode 100644 index 000000000..19b712d87 Binary files /dev/null and b/static/img/ui-capture/ui-capture-demo-shop.webp differ diff --git a/static/img/ui-capture/ui-capture-flow-detail.webp b/static/img/ui-capture/ui-capture-flow-detail.webp index 79b7d3753..7eb678087 100644 Binary files a/static/img/ui-capture/ui-capture-flow-detail.webp and b/static/img/ui-capture/ui-capture-flow-detail.webp differ diff --git a/static/img/ui-capture/ui-capture-flows.webp b/static/img/ui-capture/ui-capture-flows.webp index 4ffd96b0b..4430708e3 100644 Binary files a/static/img/ui-capture/ui-capture-flows.webp and b/static/img/ui-capture/ui-capture-flows.webp differ diff --git a/static/img/ui-capture/ui-capture-journey-tests.webp b/static/img/ui-capture/ui-capture-journey-tests.webp new file mode 100644 index 000000000..39932e405 Binary files /dev/null and b/static/img/ui-capture/ui-capture-journey-tests.webp differ diff --git a/static/img/ui-capture/ui-capture-journeys.webp b/static/img/ui-capture/ui-capture-journeys.webp new file mode 100644 index 000000000..1eeff7f3c Binary files /dev/null and b/static/img/ui-capture/ui-capture-journeys.webp differ diff --git a/static/img/ui-capture/ui-capture-key-created.webp b/static/img/ui-capture/ui-capture-key-created.webp index 54962ee99..83656eef1 100644 Binary files a/static/img/ui-capture/ui-capture-key-created.webp and b/static/img/ui-capture/ui-capture-key-created.webp differ diff --git a/static/img/ui-capture/ui-capture-nav.webp b/static/img/ui-capture/ui-capture-nav.webp new file mode 100644 index 000000000..3ba134d60 Binary files /dev/null and b/static/img/ui-capture/ui-capture-nav.webp differ diff --git a/static/img/ui-capture/ui-capture-revoke.webp b/static/img/ui-capture/ui-capture-revoke.webp new file mode 100644 index 000000000..8bbb3cdae Binary files /dev/null and b/static/img/ui-capture/ui-capture-revoke.webp differ diff --git a/static/img/ui-capture/ui-capture-setup-card.webp b/static/img/ui-capture/ui-capture-setup-card.webp index a3e0359ef..a138da564 100644 Binary files a/static/img/ui-capture/ui-capture-setup-card.webp and b/static/img/ui-capture/ui-capture-setup-card.webp differ diff --git a/static/img/ui-capture/ui-capture-status-recording.webp b/static/img/ui-capture/ui-capture-status-recording.webp new file mode 100644 index 000000000..e2a122880 Binary files /dev/null and b/static/img/ui-capture/ui-capture-status-recording.webp differ diff --git a/static/img/ui-capture/ui-capture-status.webp b/static/img/ui-capture/ui-capture-status.webp index 75ba5caf8..7b5ab1bd5 100644 Binary files a/static/img/ui-capture/ui-capture-status.webp and b/static/img/ui-capture/ui-capture-status.webp differ 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 01f12a8ce..1aa8dc34a 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 @@ -1,8 +1,8 @@ --- id: ui-capture title: Capture real user flows from your web app -sidebar_label: UI Capture -description: Record real user sessions in your web app with the Keploy capture SDK and turn every visit into UI flows you can read in the dashboard, over the REST API, or from an AI agent through MCP. +sidebar_label: Overview +description: Keploy UI Testing records real user sessions in your web app and turns each visit into UI flows and journeys, in the dashboard, the REST API or MCP. tags: - UI testing - UI capture @@ -11,147 +11,69 @@ tags: - MCP - AI agent keywords: + - UI testing - UI capture - capture SDK - user flows + - user journeys - session recording - ingest key - Keploy MCP - AI agent --- -UI Capture records how real people use your web app and turns each visit into a **UI flow**: the steps a user took (pages, clicks, typing, selections) and the network calls those steps made. You add a small browser SDK to your frontend, Keploy receives the recording, and the flows appear in the Keploy dashboard and through the API. +import ProductTier from '@site/src/components/ProductTier'; + + -You can set it up three ways, and they produce the same result: +Keploy UI Testing records how real people use your web app. A small browser SDK, `@keploy/capture-sdk`, records each visit in your users' browsers and masks personal data before anything leaves the browser. Keploy turns each visit into **UI flows**, the steps a user took on each page and the network calls those steps made, and into **journeys**: the paths visits take through your pages, each with its share of sessions. You read them in the Keploy dashboard, over the REST API, or from an AI agent through MCP. -- [In the Keploy dashboard](#set-up-ui-capture-in-the-dashboard), with a few clicks. -- [With the REST API](#set-up-ui-capture-with-the-rest-api), from a script or CI job. -- [From an AI coding agent](#set-up-ui-capture-from-an-ai-agent-mcp), such as Claude Code or Cursor, through the Keploy MCP server. +**New here?** The [dashboard quickstart](../ui-capture/quickstart-dashboard.md) records your first flows from a sample shop in about 10 minutes, and the [walkthrough](../ui-capture/walkthrough-dashboard.md) goes on to journeys. :::note Beta -UI Capture is in beta. This page describes what works today, including its current [limitations](#limitations). +UI Testing is in beta. Recording visits and reading them as flows and journeys works today. Replaying journeys as Playwright tests is in beta too, and its runner is not in a release build yet: see [What works today](#what-works-today). ::: -## How UI Capture works +## How UI capture works {#how-ui-capture-works} 1. **An ingest key** connects the SDK to one Keploy app. It can only post recordings into that app, so it is safe to ship in your page's JavaScript. -2. **The capture SDK** (`@keploy/capture-sdk`) runs in your users' browsers. It records the page and the `fetch`/`XMLHttpRequest` calls it makes, masks what users type, and sends the recording to Keploy in small batches. -3. **Keploy ends a visit** after 30 minutes without activity, then extracts its flows, usually within a few minutes. -4. **You read the flows** in the dashboard, or an agent reads them through the REST API or MCP. - -## Before you begin - -- A Keploy app to record into. Create one in the [Keploy Console](https://app.keploy.io) if you have none. -- Permission to run test generation on that app (`testgen:run`) to create or revoke an ingest key, the same in the dashboard and the API. Viewing capture status and flows needs only view access to the app (`app:view`). -- A web frontend built with a bundler (Vite, webpack, Next.js, and similar). See [Install the SDK](#install-the-sdk) for why. - -## Set up UI Capture in the dashboard - -1. In the Keploy Console, select your app and open **UI Testing → UI Flows** in the left navigation. An app with no flows yet opens on the setup card; an app with flows has it under the **Setup** tab. - - The UI Capture setup card, with steps to create an ingest key, add the SDK and check that sessions arrive - - 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. - - A newly created ingest key, shown once, with the SDK install command and an init snippet that already contains the key - -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. - - The status panel showing one session received, the time of the last activity, one flow extracted, the app's ingest key and how to set this up from an agent - -6. Open the **Flows** tab to see each flow, and click a flow to see its steps and network calls. - - The flows table listing a captured flow with its session, last update time and status - - A flow's detail page with its step timeline and the network calls the steps made +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//complete`. It then extracts the visit's flows, usually within a few minutes. +4. **Each page of a visit is its own flow**, a route change in a single-page app included, and Keploy chains a visit's flows into its journey. Every journey figure counts sessions: one page load of your app, its in-app navigation included. +5. **You read them** in the dashboard under **UI Testing → UI Flows**, or an agent reads them through the REST API or MCP. -The setup card also lists your app's ingest keys, with when each was created, last used and expires. To stop a key from being accepted, click the trash icon next to it, then **Revoke**. Pages using that key stop recording within about 30 seconds. +Each visit's flows are listed per app in the dashboard: -## Install the SDK +The Flows tab's table of flows, each with its name, session, last update time and status, under the note that each route is its own flow since SDK 3.1.0 -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: "", -}); -``` +A flow's Step Timeline, with a masked search typed into the search box and the clicks that followed, beside its Network Calls -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 `` with your app's ID. -### Create an ingest key +#### Create an ingest key {#create-an-ingest-key} ```bash curl -X POST https://api.keploy.io/client/v1/apps//ui/ingest-keys \ @@ -160,163 +82,47 @@ curl -X POST https://api.keploy.io/client/v1/apps//ui/ingest-keys \ -d '{"name": "storefront prod"}' ``` -`name` is optional, and so is `ttlDays` (1 to 365; without it the key does not expire). The response has everything needed to install the SDK, including an `init` snippet with the key in it: - -```json -{ - "data": { - "key": { - "id": "28ff3828-d0e9-4a05-8615-c48c1fd51bba", - "name": "storefront prod", - "keyPrefix": "kep_dpeSyTYC", - "appId": "", - "status": "active", - "createdAt": 1791282595 - }, - "apiKey": "kep_dpeSyTYC…", - "endpoint": "https://api.keploy.io/ui/v1/ingest", - "sdk": { - "package": "@keploy/capture-sdk", - "install": "npm install @keploy/capture-sdk", - "init": "import { KeployCapture } from \"@keploy/capture-sdk\";\n\nawait KeployCapture.init({ … });\n" - }, - "next": [ - "apiKey is shown only in this response: store it now (it is safe to ship in the page; it can only post recordings into this app)", - "install the SDK and call KeployCapture.init once at app start-up, in the browser bundle", - "browse the app, then GET /client/v1/apps//ui/capture-status (MCP: uiCaptureStatus) to see sessions arrive", - "a session becomes flows 30 minutes after its last activity; read them with GET /client/v1/apps//ui/flows" - ] - } -} -``` - -`apiKey` appears only in this response. Store it before you continue. +`name` is optional, and so is `ttlDays` (1 to 365; without it the key does not expire). The response carries the key as `apiKey`, the `endpoint` the SDK posts to, the SDK's install command and an `init` snippet with the key in it, and the `next` steps. `apiKey` appears only in this response: store it before you continue. Creating a key needs `testgen:run` on the app. -### Check that capture is working +#### Check that capture is working {#check-that-capture-is-working} ```bash curl https://api.keploy.io/client/v1/apps//ui/capture-status \ -H "Authorization: Bearer kep_YOUR_API_KEY" ``` -The response names a `state`, explains it, and lists what to do `next`: - -```json -{ - "data": { - "state": "FLOWS_READY", - "explanation": "flows have been extracted from recorded sessions", - "next": [ - "read them with GET /client/v1/apps//ui/flows (MCP: listUIFlows)", - "each flow lists its steps and the network calls it made" - ], - "endpoint": "https://api.keploy.io/ui/v1/ingest", - "idleAfterSeconds": 1800, - "totalSessions": 1, - "sessionsByStatus": {"PROCESSED": 1}, - "lastBatchAt": 1791282469, - "totalFlows": 1, - "recentSessions": [ - { - "id": "eda95518-6f70-4a80-b618-9ea986db11a0", - "sdkSessionId": "a760c5be-2a02-4d2f-8d4d-3ff1ed94c0fe", - "status": "PROCESSED", - "startedAt": 1791282469, - "lastBatchAt": 1791282469, - "completedAt": 1791282487, - "eventCount": 32, - "batches": 1, - "sdkVersion": "3.0.1" - } - ] - } -} -``` - -| `state` | What it means | What to do | -| ------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | -| `NO_SESSIONS` | No recording has reached this app. | Check the page calls `init` with this app's ingest key and endpoint. | -| `RECORDING` | Sessions are arriving. Each becomes flows `idleAfterSeconds` after its last activity. | Wait, or keep using the app. | -| `PROCESSING` | Finished visits are being turned into flows. | Check again in a minute. | -| `FLOWS_READY` | At least one flow exists. | [List the flows](#read-the-flows). | -| `NO_FLOWS` | Visits were processed but contained no user action (a page opened and left untouched). | Record a visit that clicks, types or navigates. | -| `ALL_FAILED` | Every finished visit failed to process. | Record a fresh visit; contact Keploy support if it fails again. | +The response names a `state`, explains it, and lists what to do `next`. It also counts the app's sessions by status and its flows, and lists its most recent sessions. -A visit that can't be processed is retried with backoff for about two hours and then counted as failed, so no state lasts forever. A session's `id` is the `sessionId` its flows carry; `sdkSessionId` is the browser's own ID for the same visit. +| `state` | What it means | What to do | +| ------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| `NO_SESSIONS` | No recording has reached this app. | Check that the page calls `init` with an ingest key for this app and the right endpoint. | +| `RECORDING` | Sessions are arriving. Each becomes flows `idleAfterSeconds` after its last activity. | Wait, keep using the app, or end a visit at once with `POST /ui/v1/sessions//complete` and the ingest key. | +| `PROCESSING` | Finished visits are being turned into flows. | Check again in a minute. | +| `FLOWS_READY` | At least one flow exists. | [Read the flows](#read-the-flows). | +| `NO_FLOWS` | Visits were processed but none had a user action to make a flow from (a page opened and left untouched). | Record a visit that clicks, types or navigates. | +| `ALL_FAILED` | Every finished visit failed to process. | Record a fresh visit; contact Keploy support if it fails again. | -Timestamps in seconds: `createdAt`, `startedAt`, `lastBatchAt`, `completedAt`. Step and network-call `timestamp`s in a flow are in milliseconds. +A visit that can't be processed is retried with backoff for about two hours and then counted as failed, so no state lasts forever. -### Read the flows - -List an app's flows: +#### Read the flows {#read-the-flows} ```bash +# An app's flows curl https://api.keploy.io/client/v1/apps//ui/flows \ -H "Authorization: Bearer kep_YOUR_API_KEY" -``` - -```json -{ - "data": [ - { - "id": "45733249-11ef-42be-a758-b0f621fb697d", - "name": "Fill on /", - "description": "6 steps, 1 API calls, 2.7s", - "status": "CLUSTERED", - "sessionId": "eda95518-6f70-4a80-b618-9ea986db11a0", - "clusterId": "ff14bf67-d5aa-4ca0-8feb-cd265b079f3c", - "steps": 6, - "networkCalls": 1, - "createdAt": 1791282487 - } - ] -} -``` - -Get one flow's steps and calls: -```bash +# One flow's steps and network calls curl https://api.keploy.io/client/v1/apps//ui/flows/ \ -H "Authorization: Bearer kep_YOUR_API_KEY" -``` -```json -{ - "data": { - "id": "45733249-11ef-42be-a758-b0f621fb697d", - "name": "Fill on /", - "steps": 6, - "networkCalls": 1, - "stepList": [ - { - "index": 1, - "action": "input", - "selector": "#search", - "hasValue": true, - "pageUrl": "https://shop.example.com/", - "timestamp": 1791282467268 - }, - { - "index": 2, - "action": "click", - "selector": "#go", - "pageUrl": "https://shop.example.com/", - "timestamp": 1791282467813 - } - ], - "networkCallList": [ - { - "method": "GET", - "url": "https://shop.example.com/api/search", - "responseStatus": 200, - "timestamp": 1791282467824 - } - ] - } -} +# The journey plan: how sessions move between pages, and each journey's share of sessions +curl https://api.keploy.io/client/v1/apps//ui/journeys \ + -H "Authorization: Bearer kep_YOUR_API_KEY" ``` -### Manage ingest keys +The [walkthrough](../ui-capture/walkthrough-dashboard.md#read-the-same-data-from-a-script) shows what each one returns. + +#### Manage ingest keys {#manage-ingest-keys} ```bash # List an app's ingest keys (never returns a key's secret) @@ -328,18 +134,20 @@ curl -X DELETE https://api.keploy.io/client/v1/apps//ui/ingest-keys/", +}); +``` + +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 URL followed by `/ui/v1/ingest` when you self-host. 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. + +- **Early, and once.** The SDK starts recording the page's requests once it has loaded rrweb, which your bundler normally puts in a chunk of its own. A request the page makes before then is not recorded, so start `init` before your app's own code runs. Call it once per page load, not per route: a second `init` returns the same capture. +- **Three sample setups.** The [UI capture sample shops](https://github.com/keploy/samples-typescript) show the call in a React and Vite app (`ui-capture-react-shop`: `src/keploy.ts`, imported first in `src/main.tsx`), a Next.js App Router app (`ui-capture-next-shop`: `instrumentation-client.ts`) and plain HTML pages with no bundler (`ui-capture-html-shop`). +- **Without a bundler**, serve the package's `dist/` directory as it is, import `dist/index.mjs` from it, and map `rrweb` with an import map before the SDK loads. If rrweb cannot be loaded, the capture ends before anything is sent and reports [`KUI_E_DOM_RECORDER_UNAVAILABLE`](../ui-capture/errors.md#kui-e-dom-recorder-unavailable). + +### 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). | -- **A visit is ended by 30 minutes of inactivity.** A user who comes back to the same tab after that is not recorded again until the page reloads. -- **One recording lasts at most one page load and 10 minutes** by default (`maxSessionDuration`). -- **Single-page-app route changes are not yet recorded as navigation.** In an app that changes routes without a full page load, a flow's steps all show the page where the visit started. -- **The SDK needs a bundler.** See [Install the SDK](#install-the-sdk). +The [package's README on npm](https://www.npmjs.com/package/@keploy/capture-sdk) describes each option in full. -## Troubleshooting +## Privacy at a glance {#what-the-sdk-records-and-what-it-masks} -An SDK error or warning names a `KUI_E_` code, and [UI Capture SDK errors and warnings](../ui-capture/errors.md) explains each one: what happened, why, and how to fix it. +Masking happens in the browser, before anything is sent, so Keploy's server never sees the original. + +- **Typed values** are masked in every input, textarea and select under `"balanced"` (the default) and `"strict"`. Password and hidden fields are masked in every mode, `"off"` included. The values of radio buttons, checkboxes and buttons are not typed and are recorded under `"balanced"` and `"off"`; to leave such an element out of the recording, list it in `privacy.blockSelectors`. +- **Visible text** is recorded under `"balanced"`, except inside `maskSelectors`. `"strict"` masks all of it. Strict still records `data-testid` values as written, so never build one from user data. +- **Network calls** are recorded with their method, URL, status, headers and bodies. The values of the `Authorization`, `Cookie`, `Set-Cookie`, `X-API-Key`, `X-Auth-Token` and `Proxy-Authorization` headers, and of any header whose name reads as a credential's, are always replaced with `[REDACTED]`. Bodies are redacted by structure: a value under a credential's name is replaced. `privacy.maskNetworkBodies: true` replaces every body with `[MASKED]`, `"strict"` sets it, and `networkCapture: false` records no call. +- **A body the SDK could not redact** is never recorded in the clear: it is recorded as not captured. [`KUI_E_BODY_WORKER_UNAVAILABLE`](../ui-capture/errors.md#kui-e-body-worker-unavailable) describes both markers. +- **Visitors who send Do Not Track or Global Privacy Control** are not recorded, by default. + +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. + +## Limitations {#limitations} + +- **A visit ends after 30 minutes without activity.** A visitor who comes back to the same tab after that is not recorded again until the page reloads, unless you set `continuous: true`, which starts a new session at the visitor's next click, tap or key press. +- **A session lasts at most `maxSessionDuration`**, 10 minutes by default. Set `continuous: true` to keep capturing for the life of the page. +- **Requests made before `init` has loaded rrweb are not recorded.** See [Install the SDK](#install-the-sdk). +- **A site whose links load pages records each page load as its own session**, so its journeys never span a page load. A single-page app's route changes stay in one session. +- **Sampling is per page load, not per user.** The SDK carries no user identity, so journey figures are shares of sessions, not of people. +- **Replaying journeys as Playwright tests is in beta and not runnable yet.** See [What works today](#what-works-today). + +## 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. A `401` or `403` means the key is not an ingest key, or has been revoked. +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. `capture-status` shows `RECORDING` until then, and `NO_FLOWS` if the visit had no clicks, typing or navigation. If your visits did have those, check that your app is built with a bundler: without one, SDK 3.0.1 records only network calls, and from the release that links the errors page the SDK reports `KUI_E_DOM_RECORDER_UNAVAILABLE` instead (see [Install the SDK](#install-the-sdk)). +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, and `NO_FLOWS` if the visit had no clicks, typing or navigation. + +## Related + +- [Dashboard quickstart](../ui-capture/quickstart-dashboard.md) +- [From first visit to journeys](../ui-capture/walkthrough-dashboard.md) +- [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) +- [Keploy Public API](./public-api.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 dbf69c886..7deeea22b 100644 --- a/versioned_docs/version-4.0.0/ui-capture/errors.md +++ b/versioned_docs/version-4.0.0/ui-capture/errors.md @@ -123,7 +123,7 @@ A program that reads the console can match the code and parse the JSON after the **Fix:** Mint a UI ingest key for this app and pass it as `apiKey` to `KeployCapture.init()`. You can mint one: -- In the Keploy dashboard, as described in [Set up UI Capture in the dashboard](../running-keploy/ui-capture.md#set-up-ui-capture-in-the-dashboard). +- In the Keploy dashboard, as described in [Create an ingest key](./quickstart-dashboard.md#create-an-ingest-key) in the dashboard quickstart. - With `POST /client/v1/apps//ui/ingest-keys` and a scoped Public API key with `write` scope in `Authorization: Bearer`, as described in [Create an ingest key](../running-keploy/ui-capture.md#create-an-ingest-key). The Keploy MCP server's `uiCaptureSetup` tool makes the same call. Both need `testgen:run` on the app. A new key takes effect on the next page load. @@ -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. A tool error carries: +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: - `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/quickstart-dashboard.md b/versioned_docs/version-4.0.0/ui-capture/quickstart-dashboard.md new file mode 100644 index 000000000..de9a15394 --- /dev/null +++ b/versioned_docs/version-4.0.0/ui-capture/quickstart-dashboard.md @@ -0,0 +1,238 @@ +--- +id: quickstart-dashboard +title: "UI Testing quickstart: record your first flows in the dashboard" +sidebar_label: Dashboard quickstart +description: Record visits to a sample React shop with the Keploy capture SDK and read them as UI flows in the Keploy dashboard, in about 10 minutes. +tags: + - UI testing + - UI capture + - quickstart +keywords: + - UI capture quickstart + - capture SDK + - ingest key + - UI flows + - React + - Keploy dashboard +--- + +import HowTo from '@site/src/components/HowTo'; +import ProductTier from '@site/src/components/ProductTier'; + +/complete.", +url: "#watch-the-sessions-arrive", +}, +{ +name: "See your flows", +text: "When the card says Flows are ready, open the Flows tab and click a flow to see its steps and network calls.", +url: "#see-your-flows", +}, +]} +/> + + + +In this quickstart you add the Keploy capture SDK's ingest key to a small React shop, use the shop in your browser, and read each visit as **UI flows** in the Keploy dashboard: the steps you took on each page and the network calls those steps made. It takes about 10 minutes. The same steps work for your own web app. + +:::note Beta +UI Testing is in beta. Recording visits and reading them as flows and journeys works today. Replaying journeys as Playwright tests is in beta too, and its runner is not in a release build yet, so this quickstart stops at the flows. See [what works today](../running-keploy/ui-capture.md#what-works-today). +::: + +## Before you begin + +- A Keploy account. Sign in at [app.keploy.io](https://app.keploy.io). +- An app to record into. UI Testing records into the app you select in the dashboard's header. If you have none, create one with the [Public API](../running-keploy/public-api.md): generate a token with the **Write** scope under **Settings → API Keys → Generate new token**, then run: + + ```bash + curl -X POST https://api.keploy.io/client/v1/apps \ + -H "Authorization: Bearer kep_YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"name": "docs-demo-shop"}' + ``` + + An app's name cannot be changed later, and two apps cannot share one. + +- Permission to run test generation on the app (`testgen:run`), which creating an ingest key needs. Viewing capture status and flows needs only view access to the app (`app:view`). +- Node.js 22.22 or later, npm and git, for the sample shop. + +## 1. Get the sample shop {#get-the-sample-shop} + +The [React sample shop](https://github.com/keploy/samples-typescript/tree/main/ui-capture-react-shop) is a small shop built with React, Vite and React Router: Home, Products with a search box, Cart, Checkout and About. Its API runs inside Vite, so there is nothing else to start. + +```bash +git clone https://github.com/keploy/samples-typescript && cd samples-typescript/ui-capture-react-shop +cp .env.example .env +npm ci +``` + +## 2. Open UI Testing → UI Flows {#open-ui-flows} + +In the [Keploy dashboard](https://app.keploy.io), select your app in the header, then open **UI Testing → UI Flows** in the left navigation. + +The left navigation's UI Testing section, with its UI Flows item and a Beta label + +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. + +The setup card for an app with no ingest key: 1. Create an ingest key, 2. Add the SDK to your app, 3. Check that sessions arrive with no sessions yet, the empty Ingest keys list, and how to set this up with an AI agent or a script + +## 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 setup card after Create ingest key: the new key in a box that says it is shown only once, the install command, an init snippet with the endpoint and the key filled in, and the key listed under Ingest keys + +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 sample shop's Products page after a search for kettle, with the kettle added to the cart + +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 `; +- while you click around, the **Network** tab shows a `POST` to `/ui/v1/ingest` every few seconds, answered `200`. + +## 6. Watch the sessions arrive {#watch-the-sessions-arrive} + +Back in the dashboard, the card's **3. Check that sessions arrive** counts what has reached Keploy. It checks again every 30 seconds; the refresh icon next to the heading checks at once. + +- **Sessions received** counts visits. One visit is one page load of the shop, its route changes included. +- **Last activity** is when the SDK last sent anything. +- **Flows extracted** goes up once a visit has ended and Keploy has turned it into flows. + +Check that sessions arrive, with one session received, the time of its last activity, no flows extracted yet, and the line saying each visit becomes flows about 30 minutes after its last activity + +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//complete \ + -H "X-API-Key: kep_YOUR_INGEST_KEY" +``` + +Its flows follow within a minute or two. A tab left open on the completed session is refused at its next batch, and its capture ends with [`KUI_E_SESSION_CONFLICT`](./errors.md#kui-e-session-conflict). The shop's `npm run demo:visits` script does all of this for you: it drives five scripted visits, stops each one's capture and completes it. The [walkthrough](./walkthrough-dashboard.md#record-five-visits) uses it. + +## 7. See your flows {#see-your-flows} + +When the first flows exist, the line under the counts says **Flows are ready — see the Flows tab.** and the page switches to its tabs on its own. The **Setup** tab keeps the card. + +Check that sessions arrive once flows exist: sessions received, the time of the last activity, flows extracted, and the line Flows are ready — see the Flows tab + +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`. + +The Flows tab's table of flows, each with its name, session, last update time and status, under the note that each route is its own flow since SDK 3.1.0 + +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. + +A flow's Step Timeline, with a masked search typed into the search box and the clicks that followed, beside its Network Calls: the product search and adding to the cart + +## 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'; + + + + + +This walkthrough picks up where the [dashboard quickstart](./quickstart-dashboard.md) ends. You record five visits to the sample shop along three paths, then follow them through the Keploy dashboard: capture status, flows, one flow's steps and calls, and the journeys the visits took, with each journey's share of sessions. Then you read the same data with `curl` and clean up. It takes about 20 minutes. Every screenshot on this page comes from these five visits. + +:::note Beta +UI Testing is in beta. Recording visits and reading them as flows and journeys works today. Replaying journeys as Playwright tests is in beta too, and its runner is not in a release build yet, so this walkthrough reads journeys and does not replay them. See [what works today](../running-keploy/ui-capture.md#what-works-today). +::: + +## What you'll do {#what-youll-do} + +1. Set up the sample shop with an ingest key. +2. Record five visits with the shop's scripted visits. +3. Watch capture status go from sessions arriving to flows ready. +4. Read the flows, and one flow's steps and network calls. +5. See the journeys the visits took, and their shares of sessions. +6. Read the same data from a script. +7. Clean up. + +## 1. Set up {#set-up} + +Follow steps 1 to 4 of the [dashboard quickstart](./quickstart-dashboard.md): + +1. [Get the sample shop](./quickstart-dashboard.md#get-the-sample-shop). +2. [Open UI Testing → UI Flows](./quickstart-dashboard.md#open-ui-flows) with your app selected. +3. [Create an ingest key](./quickstart-dashboard.md#create-an-ingest-key). +4. [Add the key to the shop](./quickstart-dashboard.md#add-the-key-to-the-shop): put it in the shop's `.env`. + +Use an app with no sessions yet, so the figures you see match the ones here. + +## 2. Record five visits {#record-five-visits} + +Build the shop and serve the build. In a second terminal, install Playwright's Chromium once, then run the scripted visits: + +```bash +npm run build && npm run preview # http://localhost:4173 +``` + +```bash +npx playwright install chromium # once +npm run demo:visits +``` + +`npm run demo:visits` drives five visits through the shop in a headless Chromium, using the endpoint and key from `.env`. It stays six seconds on each page, so that each page's calls stay in that page's flow. It ends each visit and marks it complete (`POST /ui/v1/sessions//complete`, with the key), so Keploy turns it into flows within a minute or two instead of after 30 idle minutes. Each visit is printed with its session: + +```text +visit 1/5: / > /products > /cart > /checkout -- session 5f0c… completed +``` + +The five visits take three paths through the shop: + +| Visit | Pages | What it does on the way | +| ----- | ----------------------------------------- | ----------------------------------------------------------- | +| 1, 2 | `/` → `/products` → `/cart` → `/checkout` | Searches for `kettle`, adds it to the cart, places an order | +| 3 | `/` → `/about` | | +| 4 | `/` → `/products` | Searches for `kettle` | +| 5 | `/` → `/products` → `/cart` | Adds the kettle to the cart | + +The visits type only made-up data: the catalogue word `kettle` and the address `shopper@example.com`. + +To record visits by hand instead, open `http://localhost:4173` and shop. A visit you make by hand becomes flows 30 minutes after its last activity, unless you [complete it](./quickstart-dashboard.md#watch-the-sessions-arrive). + +## 3. Watch capture status {#watch-capture-status} + +Open **UI Testing → UI Flows**. Until the app has flows, the page shows the setup card, whose **3. Check that sessions arrive** says what has reached Keploy. Its counts check again every 30 seconds. The line under them is the same state that `GET …/ui/capture-status` (MCP: `uiCaptureStatus`) returns to a script or an agent: + +| State | The card says | +| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `NO_SESSIONS` | No sessions yet. Open your app in a browser with the SDK installed; check the browser console for a [keploy] message if nothing arrives. | +| `RECORDING` | Sessions are arriving. Each visit becomes flows about 30 minutes after its last activity. | +| `PROCESSING` | Visits have finished and their flows are being extracted, normally within a minute. | +| `FLOWS_READY` | Flows are ready — see the Flows tab. | +| `NO_FLOWS` | Visits were processed, but none had a click, typing or navigation to make a flow from. Record a visit that uses the app. | +| `ALL_FAILED` | Every finished visit failed to process. Record a fresh visit; if it fails again, contact Keploy support. | + +While a visit is recording, until it is completed or has been idle for 30 minutes, the card counts its session and no flows yet: + +Check that sessions arrive while a visit is recording: one session received, its last activity, no flows extracted, and the line saying each visit becomes flows about 30 minutes after its last activity + +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: + +Check that sessions arrive after the five visits: five sessions received, the last activity, the flows extracted, and the line Flows are ready — see the Flows tab + +## 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. + +The Flows tab's table of the five visits' flows, each with its name, session, last update time and status, under the note that each route is its own flow since SDK 3.1.0 + +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. + +A Fill on /products flow: its Step Timeline with a masked search typed into the search box and the clicks that followed, beside its Network Calls: the product search with its query and adding the kettle to the cart + +## 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. + +The top of the Journeys tab for the five visits: five sessions in the last 30 days, the note that every figure counts sessions, and the journey graph from the home page to Products, Cart, Checkout and About, with tables of the pages and of the moves, each with its share of sessions + +**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. + +Journey tests with one selected journey, / to /products to /cart, taken by 3 of 5 sessions, and Other frequent journeys with the three journeys that are not in the test plan and their shares of sessions + +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//ui/capture-status \ + -H "Authorization: Bearer kep_YOUR_API_KEY" +``` + +```json +{ + "data": { + "state": "FLOWS_READY", + "explanation": "flows have been extracted from recorded sessions", + "next": [ + "read them with GET /client/v1/apps//ui/flows (MCP: listUIFlows)", + "each flow lists its steps and the network calls it made" + ], + "endpoint": "https://api.keploy.io/ui/v1/ingest", + "idleAfterSeconds": 1800, + "totalSessions": 5, + "sessionsByStatus": {"PROCESSED": 5}, + "lastBatchAt": 1795156629, + "totalFlows": 15, + "recentSessions": [ + { + "id": "934c1a89-806f-47e5-9366-3afdf1929f46", + "sdkSessionId": "3424f2bf-2271-4a66-83d4-2edfa422a7ae", + "status": "PROCESSED", + "startedAt": 1795156620, + "lastBatchAt": 1795156629, + "completedAt": 1795156634, + "eventCount": 31, + "batches": 3, + "sdkVersion": "3.1.0" + } + ] + } +} +``` + +This response is shortened: `recentSessions` lists the five sessions, newest first. A session's `id` is the `sessionId` its flows carry; `sdkSessionId` is the browser's own id for the visit, the one the shop logs and `/complete` takes. Timestamps are in seconds. + +**Flows.** Each flow with its name, session and counts. `GET …/ui/flows/` returns one flow's steps and network calls: + +```bash +curl https://api.keploy.io/client/v1/apps//ui/flows \ + -H "Authorization: Bearer kep_YOUR_API_KEY" + +curl https://api.keploy.io/client/v1/apps//ui/flows/ \ + -H "Authorization: Bearer kep_YOUR_API_KEY" +``` + +```json +{ + "data": { + "id": "2276a4a5-73c9-4815-be09-b7dc8c483c09", + "name": "Fill on /products", + "description": "5 steps, 4 API calls, 8.6s", + "status": "CLUSTERED", + "sessionId": "df71c5fc-fe59-45f3-934a-2b8346059092", + "clusterId": "1cecbc2d-8f03-4b8a-8c16-d4b9c4846a8f", + "steps": 5, + "networkCalls": 4, + "createdAt": 1795156600, + "stepList": [ + { + "index": 1, + "action": "input", + "selector": "[data-testid=\"search-input\"]", + "hasValue": true, + "pageUrl": "http://localhost:4173/products", + "timestamp": 1795156538552 + }, + { + "index": 2, + "action": "click", + "selector": "[data-testid=\"search-button\"]", + "pageUrl": "http://localhost:4173/products", + "timestamp": 1795156538577 + } + ], + "networkCallList": [ + { + "method": "GET", + "url": "http://localhost:4173/api/products", + "responseStatus": 200, + "timestamp": 1795156538591 + }, + { + "method": "POST", + "url": "http://localhost:4173/api/cart", + "responseStatus": 201, + "timestamp": 1795156539641 + } + ] + } +} +``` + +This is the flow from step 5, shortened to two of its five steps and two of its four calls. A flow's step and call `timestamp`s are in milliseconds. The API returns less than the dashboard: a step says that a value was typed (`hasValue`) and never what, and URLs come without their query, so the search's call has no `?q=kettle`. [What an agent sees](../running-keploy/ui-capture.md#what-an-agent-sees) lists what is left out. + +**Journeys.** The same plan as the **Journeys** tab: + +```bash +curl https://api.keploy.io/client/v1/apps//ui/journeys \ + -H "Authorization: Bearer kep_YOUR_API_KEY" +``` + +```json +{ + "data": { + "planId": "55d10d00-14df-48d8-adfd-a3375c552f29", + "windowDays": 30, + "totalSessions": 5, + "coveragePermille": 800, + "coverageTargetPermille": 800, + "maxJourneys": 20, + "journeys": [ + { + "id": "5520e1875d1e42296f14e8bcd944c8e6", + "pages": ["/", "/products", "/cart"], + "sessions": 3, + "sessionPercentage": 60, + "lastSeenAt": 1795156620, + "selected": true, + "pinned": false, + "representativeSessionId": "934c1a89-806f-47e5-9366-3afdf1929f46", + "sdkVersion": "3.1.0", + "flowIds": [ + "7884b42d-b0fc-42ce-8cfc-b0a0dbc3e216", + "004b5a8d-d018-4f8e-847a-99914919a940", + "477c7cdd-a3a7-4f93-b646-b0aa8bb6a1aa" + ] + } + ] + } +} +``` + +This response is shortened too. It also carries `ranked`, the most taken journeys, with `/` → `/products` first; `nodes` and `edges`, the graph's pages and moves; and `freshness`, which says when the plan was computed. `flowIds` are the recording a test of the journey replays, each a flow you can read with `GET …/ui/flows/`. + +The Keploy MCP server has the same calls as tools: `uiCaptureStatus`, `listUIFlows`, `getUIFlow` and `uiJourneys`. See [From an AI agent (MCP)](../running-keploy/ui-capture.md#set-up-ui-capture-from-an-ai-agent-mcp). + +## 8. Clean up {#clean-up} + +**Revoke the ingest key.** Open the **Setup** tab. Under **Ingest keys**, click the trash icon next to the key. The row asks you to confirm: **Pages using it stop recording.** Click **Revoke**. + +An ingest key's row asking to confirm the revoke, with the line Pages using it stop recording and the Revoke and Cancel buttons + +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/ \ + -H "Authorization: Bearer kep_YOUR_ADMIN_KEY" +``` + +## What's next {#whats-next} + +- [Install the SDK in your own app](../running-keploy/ui-capture.md#install-the-sdk), as early in its startup as you can. +- [Set up UI capture from an AI agent](../running-keploy/ui-capture.md#set-up-ui-capture-from-an-ai-agent-mcp) through the Keploy MCP server. +- [UI Capture errors and warnings](./errors.md): what each `KUI_E_` code means and how to fix it. + +## Related + +- [UI Testing overview](../running-keploy/ui-capture.md) +- [Dashboard quickstart](./quickstart-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_sidebars/version-4.0.0-sidebars.json b/versioned_sidebars/version-4.0.0-sidebars.json index 61c13096d..504a13401 100644 --- a/versioned_sidebars/version-4.0.0-sidebars.json +++ b/versioned_sidebars/version-4.0.0-sidebars.json @@ -284,11 +284,48 @@ "type": "category", "label": "UI Testing", "collapsed": true, + "link": { + "type": "doc", + "id": "running-keploy/ui-capture" + }, "items": [ - "running-keploy/ui-capture", - "ui-capture/errors", - "ui-capture/refusals", - "ui-capture/capture-sdk-3-1-0-release-notes" + { + "type": "category", + "label": "Quickstarts", + "collapsible": true, + "collapsed": false, + "items": ["ui-capture/quickstart-dashboard"] + }, + { + "type": "category", + "label": "Walkthroughs", + "collapsible": true, + "collapsed": false, + "items": ["ui-capture/walkthrough-dashboard"] + }, + { + "type": "category", + "label": "Reference", + "collapsible": true, + "collapsed": true, + "items": [ + { + "type": "doc", + "id": "ui-capture/errors", + "label": "Errors and warnings" + }, + { + "type": "doc", + "id": "ui-capture/refusals", + "label": "Refused verbs" + }, + { + "type": "doc", + "id": "ui-capture/capture-sdk-3-1-0-release-notes", + "label": "SDK 3.1.0 release notes" + } + ] + } ] }, {