Repository navigation
docs(ui-capture): agent quickstart and walkthrough, and REST, MCP and CLI references - #991
Merged
Merged
Conversation
… CLI references The UI Testing section's agent path: an AI agent sets up UI capture and reads flows and journeys through the Keploy MCP server or the REST API. - ui-capture/quickstart-agent: connect an agent (OAuth, a personal access token, keploy login + keploy mcp-install), what it does, curl without MCP. - ui-capture/walkthrough-agent: every tool call and its answer, from a staging run against a throwaway app, IDs replaced. - ui-capture/agents: credentials, the lifecycle as MCP tools and REST routes, waits, errors, what an agent sees, what it cannot do yet. - ui-capture/rest-api, mcp-tools, cli: references, checked against api-server main and the released keploy binary. - running-keploy/ui-capture: the REST and MCP setup moves to those pages, with a "Where did a section go?" table. - ui-capture/errors: keploy ui --help and keploy ui run are not in a release build yet; the flags of keploy ui run are no longer listed. - NO_FLOWS: a page opened and left untouched still makes a one-step Navigate flow (flowengine extract.go, dedup.go); the overview and the REST state table no longer say it makes none. - Sidebar (agents joins the Guides category), llms.txt, and links in the dashboard walkthrough, privacy and sessions pages to the moved sections. Signed-off-by: slayerjain <shubhamkjain@outlook.com>
slayerjain
force-pushed
the
docs/ui-capture-agent-references
branch
from
November 20, 2026 08:14
ab95c32 to
5719b74
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this does
The UI Testing section gets its agent path, end to end: an AI agent can set up UI capture in a web app and read what it records, through the Keploy MCP server or the REST API. Six new pages, and the REST and MCP setup the overview has carried until now moves into them.
New:
/docs/ui-capture/quickstart-agent/(AI agent quickstart, under Quickstarts). Connect Claude Code, Cursor, Codex or another MCP client to the Keploy MCP server three ways (OAuth sign-in; a personal access token, with the command and a screenshot of the setup card's agent callout;keploy loginandkeploy mcp-install), ask the agent, what it does, using the app, reading the flows, the same steps with curl, what the agent sees, clean-up./docs/ui-capture/walkthrough-agent/(An agent onboards a web app, under Walkthroughs). Twelve steps, each with the realinvoke_toolcall and its answer: find the tools,createApp,uiCaptureSetup, the SDK in the sample shop,uiCaptureStatusat NO_SESSIONS, RECORDING and FLOWS_READY,/complete,listUIFlows,getUIFlow,uiJourneys,uiJourneyImpact(with a comma-joinedjourneyIdsand a refused one),listUITestRuns,revokeUIIngestKey,deleteApp; then the waits and what an agent cannot do yet./docs/ui-capture/agents/(Operate from an AI agent, under Guides). Credentials (OAuth, PAT,keploy mcp-installand its 90-day token,KEPLOY_API_KEY, aUI_READERservice-account key on a paid plan) and what each can do; tool-search mode; the lifecycle as MCP tool and REST route; waiting and polling; the errors to branch on; what an agent sees; what agents cannot do yet./docs/ui-capture/rest-api/(every UI Capture operation, scope and permission, parameters, a real answer, plus the ingest endpoints and/complete),/docs/ui-capture/mcp-tools/(the server, the 15 tools with their inputs and scopes, a JSON-RPC call, input types, OAuth or API key) and/docs/ui-capture/cli/(keploy loginandkeploy mcp-installas the released binary has them;keploy uiis not in a release build).Changed:
running-keploy/ui-capture): "With the REST API" and "From an AI agent (MCP)" are now short sections that link the new pages; their old sub-sections (create an ingest key, check that capture is working, read the flows, manage ingest keys, what an agent sees) moved, and a Where did a section go? table at the bottom points to each one's new place.#set-up-ui-capture-with-the-rest-apiand#set-up-ui-capture-from-an-ai-agent-mcpare kept.ui-capture/errors.md: the "mint a key" link points to the REST reference; "Handle errors from the Keploy UI tools" no longer listskeploy ui run's flags as commands of the binary, and sayskeploy ui --helpandkeploy ui runare not in a release build yet (founder ruling D2: replay is beta, not runnable yet). No{#kui-e-…}section is touched.walkthrough-dashboard.md,privacy.md,sessions-and-sampling.md: links follow the moved sections.NO_FLOWS: the overview and the REST state table said a page that is only loaded makes no flow, repeating api-server's own hint. The extractor turns every page's load into a navigate action (api-serverpkg/service/uicapture/flowengine/extract.go:440-466) and skips only empty sequences (flowengine/dedup.go:214-216), so an untouched page makes a one-stepNavigate on /aboutflow, as on staging. Both now say so.llms.txt: the six pages.Replay stays "beta, not runnable yet" everywhere: no page gives a step to generate or run a test, and every page that mentions runs says a run today comes only from the dashboard's Generate Test and stays pending.
Screenshot
One,
ui-capture-agent-callout.webp(76 KB): the setup card's "Setting this up with an AI agent or a script?" callout, an element shot. Taken by a Playwright script on a build box against Keploy's staging dashboard, for a throwaway app (docs-demo-agent) the script created and deleted; the staging host is written asapi.keploy.io; no key is in the shot.How the examples were made
The same box job drove the lifecycle as an agent does, through the staging MCP server (
invoke_toolover JSON-RPC) and the REST API, against the throwaway app: six visits to the React sample shop (samples-typescript main, SDK 3.1.0) in headless Chromium, each ended with/complete. Every JSON answer on the pages is from that run, with IDs replaced by fresh UUIDs, the staging host written asapi.keploy.io, the key blanked, and lists shortened. A few REST-page answers were captured through the MCP server (which dispatches the same handler in-process) and are printed in the REST API's field order. Clean-up: the keys revoked,deleteApp, andGETof the app answered404. Before the run, the script checked that staging serves api-server main's UI Capture operations: the servedopenapi.yaml's UI Capture paths are byte-identical to main's.The CLI page was checked against the released binary itself (Keploy 3.9.4, the latest release; asset checksum verified): its help tree,
keploy login --help,keploy mcp-install --help, andkeploy ui --help, which answersunknown command "ui".Sources checked
Sources: keploy/api-server main 7d97ad0db (
api:), keploy/enterprise-ui main 4a5d8c5d (eui:), keploy/enterprise v3.9.4 cbd2ee776b, the releasedkeploybinary (ent:), keploy/ui-capture v3.1.0 9bae8002 (uic:), keploy/samples-typescript main 6231b4e (samples:). Staging serves api-server main's UI Capture operations: the servedopenapi.yaml's UI Capture paths are byte-identical to main's.ui-capture/cli
keploy --helplistslogin,logout,mcp-install,skill, … and noui;keploy ui --helpanswersError: unknown command "ui" for "keploy".keploy uitree builds only under theuicapturetag); ent:goreleaser.yaml:116-120, 165-169, 196-197, 226-227, 280-281 (no release build sets it).--finishwaits 70 s).--no-wait,--finish,--json), 882-921 (an accepted API key answers signed in, no device code).--manual-loginasks for an API key), 350-365 (KEPLOY_API_KEY), 366-380 (a stored session, then the browser sign-in).keploy).mcp_url).ui-capture/mcp-tools
keploy-atg), 282-285 (one tool per OpenAPI operation), 304-315 (tool-search listing, lean instructions, streamable HTTP, stateless).tools/list), 158-268 (search_tools: names and a summary, 10 by default, keyword-scored), 270-322 (get_tool_schema), 326-360 (invoke_tool).typedParam: number, boolean, else string, sojourneyIdsis a string), 306-358, 374-387 (annotations).status_code, 4xx/5xx as errors); api:pkg/mcp/proxy.go:141-188 (isError).x-required-scopeof each operation (45-180, 2418-2793).testgen:run).tools/list,get_tool_schemaof the 15 tools (names, required inputs, types), a refusedgetUITestRun.ui-capture/rest-api
/client/v1/docs,/client/v1/openapi.yaml).X-API-Key), 109-112 (an ingest key is 403), 627-650 (rate-limit headers,Retry-After); response.go:21-46 (envelope, pagination); errors.go:30-115 (codes).ttlDays, reserved name, 409,no-store,next, empty endpoint), 313-360 (list, revoke), 362-449 (status), 454-483 (flows, no pagination meta), 491-610 (flow graph bounds), 620-635 (limit1-200), 1018-1086 (one flow); api:pkg/models/uicapture.go:17-32 (session and flow statuses), 572-594 (flow graph fields).next).RATE_LIMITED,Retry-After: 10), 189-224 (refreshneedstestgen:run), 226-249 (impact); api:pkg/service/uicapture/journeyplan/service.go:268-290 (impact IDs from the plan'sjourneys).next), 347-410 (list, paged; one run).ui-capture/agents
getSessionId); eui:app/ui-testing/[flowId]/page.tsx:552-567 (Generate Test's pending run).ui-capture/quickstart-agent
ui-capture/walkthrough-agent
running-keploy/ui-capture, errors.md, walkthrough-dashboard.md, llms-root, sidebar
keploy ui --helpandkeploy ui runare not in a release build (the binary's tree above).Checks
On a build box, with CI's commands (node 22, yarn 1.22), on this commit (on main 9cc6d36):
prettier@2.8.8 --checkon the changed.mdfilessrc="/docs/…"resolves understatic/yarn install --frozen-lockfileand the yarn.lock checkyarn buildonmainand on this branch: neither prints a warning or error line, so the branch adds none (onBrokenLinksandonBrokenAnchorsarethrow)verify-linkedin-tag,verify-schema,verify-lastmod,verify-moved-urlsandverify-ui-capture-sdk-links(49 error sections, 5 refused verbs, 4 README links)yarn buildwithonBrokenAnchors: throwalso covers the moved sections: nothing on the site links an overview heading this change removesIn the built site: every heading id the pages link to exists (the overview's kept ones and
#where-did-a-section-go, and each new page's sections); the image is in the build;llms.txtand the sitemap list the six new pages; both task pages carry theirHowTo; a rendered-text comparison of each page's source with its HTML differs only at the JSX components and code-block titles, anderrors.mddiffers nowhere.