Class CaptureService

java.lang.Object
com.shaft.mcp.CaptureService
@Service public class CaptureService extends Object
MCP adapter for deterministic managed-browser SHAFT Capture recording.

  • Constructor Details

    • CaptureService

      public CaptureService()
      Creates the default MCP Capture service, wiring default Playwright/mobile services for direct Java callers and tests that construct this class without Spring.

  • Method Details

    • start

      @Tool(name="capture_start", description="starts a recording, dispatching to the active engine: WEB (or no active session) always launches its own privacy-safe SHAFT-managed browser via CDP capture, and while it is active, element_* tools drive the recorded browser directly (no driver_initialize needed); PLAYWRIGHT/mobile sessions instead record actions on the already-active driver (targetUrl/browser/headless are WEB-only; sessionGoal names the generated test on WEB, or is used as the recorder's mode label on PLAYWRIGHT/mobile); optional nested codegenOptions replaces the flat targetUrl/browser/outputPath/headless/sessionGoal args with the full Playwright-codegen-compatible request (viewport, geolocation, HAR, proxy, etc.), absorbing the former capture_start_codegen tool -- WEB/NONE only. IMPORTANT: this tool takes no engine/platform argument of its own -- with no active session (the default), it ALWAYS launches a desktop Chrome/Edge browser, never a mobile app, even when the caller's intent is to record on a mobile device or emulator; to record a mobile app, call driver_initialize(engine=mobile_native) or driver_initialize(engine=mobile_web) FIRST to make that engine active, then call capture_start (with no WEB-only args) so it dispatches to the mobile recorder instead") public McpCaptureUnionStatus start(@ToolParam(required=false,description="initial http, https, or file URL; blank opens an empty browser; WEB/NONE only") String targetUrl, @ToolParam(required=false,description="Chrome or Edge; blank selects Chrome; WEB/NONE only") String browser, @ToolParam(required=false,description="recording/capture JSON path; blank selects a timestamped recording") String outputPath, @ToolParam(required=false,description="whether to launch without a visible window; blank/omitted defaults to headless per repo policy; WEB/NONE only") Boolean headless, @ToolParam(required=false,description="optional user intent for the journey; drives generated test class and method names on WEB, or the recorder's mode label on PLAYWRIGHT/mobile") String sessionGoal, @ToolParam(required=false,description="full Playwright-codegen-compatible request (viewport, geolocation, HAR, proxy, API capture, etc.); when supplied, its own fields replace targetUrl/browser/outputPath/headless/sessionGoal entirely; WEB/NONE only, absorbs capture_start_codegen") CaptureService.CaptureCodegenStartRequest codegenOptions)
      Starts deterministic capture, dispatching on the MCP session's active engine (design doc amendment A3): a WEB session (or no active session) always launches a fresh SHAFT-managed browser via its own CDP capture, regardless of what else is active; a PLAYWRIGHT or mobile (MOBILE_NATIVE/MOBILE_WEB) session instead records actions performed on that already-active driver, delegating to that engine's own recorder start (package-private PlaywrightService.recordStart(String, String, boolean)/MobileService.recordStart(String, String, boolean), no longer separate tool names since commit 4).
      Parameters:
      targetUrl - initial http, https, or file URL; WEB/NONE only
      browser - Chrome or Edge; blank selects Chrome; WEB/NONE only
      outputPath - recording/capture JSON path; blank selects a timestamped recording
      headless - whether to launch without a visible window; unspecified defaults to headless per repo policy, matching apiStart(String, String, Boolean, NetworkCaptureOptions, String, String, String); WEB/NONE only
      sessionGoal - WEB/NONE: optional user intent for the journey, drives generated test class and method names; PLAYWRIGHT/mobile: used as the recorder's descriptive mode label
      Returns:
      union recorder status; McpCaptureUnionStatus.engine() names the dispatched engine

    • start

      public McpCaptureUnionStatus start(String targetUrl, String browser, String outputPath, Boolean headless, String sessionGoal)
      Java-caller convenience overload defaulting codegenOptions to unset; not an MCP tool.
      Parameters:
      targetUrl - initial http, https, or file URL
      browser - Chrome or Edge
      outputPath - recording/capture JSON path
      headless - whether to launch without a visible window
      sessionGoal - optional user intent for the journey
      Returns:
      safe recorder status for the active engine

    • codegenFeatures

      @Tool(name="capture_codegen_features", description="returns Playwright codegen features and how SHAFT Capture/MCP maps each feature") public List<CodegenFeatureCatalog.Feature> codegenFeatures()
      Returns the Playwright codegen feature inventory and SHAFT support mapping.
      Returns:
      codegen feature mapping

    • status

      @Tool(name="capture_status", description="returns recorder status for the active engine: WEB (or no active session) returns SHAFT Capture session, browser, URL, event count, pending debounced-signal count, warnings, and output status (when no session is active the warnings list persisted recordings that can be turned into code without a live session); PLAYWRIGHT/mobile return that engine's own recorder status; the union's engine field names which is populated") public McpCaptureUnionStatus status()
      Returns safe recorder status, dispatching on the MCP session's active engine (design doc amendment A3): the returned union's engine discriminator names which recording family (webStatus, playwrightStatus, or mobileStatus) is populated.
      Returns:
      current or final recorder status for the active engine

    • stop

      @Tool(name="capture_stop", description="stops the active recording for the active engine; after WEB reaches COMPLETED, show outputPath and generate replay-proven code by passing it as sessionPath to capture_generate_replay (or capture_code_blocks for a faster, unproven draft); the union's engine field names which recorder was stopped") public McpCaptureUnionStatus stop(boolean discard)
      Stops the active recording, dispatching on the MCP session's active engine (design doc amendment A3); see status() for the union return shape.
      Parameters:
      discard - whether to delete capture artifacts after shutdown
      Returns:
      final recorder status for the active engine

    • stepDelete

      @Tool(name="capture_step_delete", description="deletes a recorded step by its stable stepId from the active Playwright or mobile recording; returns an actionable error naming the active engine for a WEB CDP capture_start session, whose recording format has no step editor") public McpMobileRecordingStatus stepDelete(String stepId)
      Deletes a recorded step by its stable stepId from the active Playwright or mobile recording, dispatching on the MCP session's active engine. A WEB CDP capture_start session has no step editor for this (design doc amendment A3): McpRecordingStepEditor only understands the mobile/Playwright JSON recording format, so this returns an actionable error naming the active engine instead.
      Parameters:
      stepId - stable step id (e.g. "m2"), as surfaced in recorder status
      Returns:
      updated recorder status for the active engine

    • stepReorder

      @Tool(name="capture_step_reorder", description="moves a recorded step up or down by its stable stepId (direction: up|down) within the active Playwright or mobile recording; returns an actionable error naming the active engine for a WEB CDP capture_start session, whose recording format has no step editor") public McpMobileRecordingStatus stepReorder(String stepId, String direction)
      Moves a recorded step up or down by its stable stepId within the active Playwright or mobile recording, dispatching on the MCP session's active engine; see stepDelete(String) for why a WEB CDP session returns an actionable error instead.
      Parameters:
      stepId - stable step id (e.g. "m2"), as surfaced in recorder status
      direction - "up" or "down"
      Returns:
      updated recorder status for the active engine

    • apiStart

      @Tool(name="capture_api_start", description="starts SHAFT Capture with API network recording enabled; dispatches to the mobile loopback MITM proxy when a mobile engine is active OR mobilePlatform is explicitly given (the mobile proxy never requires a live Appium/WebDriver session), absorbing mobile_api_record_start (outputPath/mobilePlatform/mobileDeviceLabel are mobile-only and ignored on WEB)") public McpCaptureApiUnionStatus apiStart(String targetUrl, String browser, Boolean headless, NetworkCaptureOptions networkOptions, @ToolParam(required=false) String outputPath, @ToolParam(required=false) String mobilePlatform, @ToolParam(required=false) String mobileDeviceLabel)
      Launches a fresh SHAFT-managed browser and starts API capture with network recording.
      Parameters:
      targetUrl - initial http, https, or file URL
      browser - Chrome or Edge; blank selects Chrome
      headless - whether to launch without a visible window; unspecified defaults to headless per repo policy
      networkOptions - network capture filtering options; blank selects capture-all defaults
      Returns:
      safe recorder status with network transaction count

    • apiStatus

      @Tool(name="capture_api_status", description="returns SHAFT Capture session status including network transaction count and recent endpoints; dispatches to the mobile loopback MITM proxy when a mobile engine is active, or when a standalone mobile API session (started with no active engine) is already running") public McpCaptureApiUnionStatus apiStatus()
      Returns safe recorder status with network transaction count and recent endpoints.
      Returns:
      current recorder status including network metrics

    • apiStop

      @Tool(name="capture_api_stop", description="stops SHAFT API Capture with the same single-session lock guarantee as capture_stop; dispatches to the mobile loopback MITM proxy when a mobile engine is active, or when a standalone mobile API session (started with no active engine) is already running") public McpCaptureApiUnionStatus apiStop(boolean discard)
      Stops the active API capture recording.
      Parameters:
      discard - whether to delete capture artifacts after shutdown
      Returns:
      final recorder status

    • apiTransactions

      @Tool(name="capture_api_transactions", description="returns captured network transactions without bodies or sensitive headers; supports filtering asset noise on WEB; dispatches to the mobile loopback MITM proxy's transactions when a mobile engine is active, or when a standalone mobile API session is already running (includeAssets/excludePattern are WEB-only there)") public List<NetworkTransaction> apiTransactions(boolean includeAssets, String excludePattern)
      Returns sanitized summaries of captured network transactions.
      Parameters:
      includeAssets - whether to include asset resource types (images, fonts, stylesheets, media)
      excludePattern - optional |-separated glob pattern(s) of URLs to exclude
      Returns:
      ordered, bounded list of transaction summaries without sensitive data

    • generateApi

      @Tool(name="capture_api_generate", description="generates, compiles, and returns copy-paste SHAFT.API code blocks from recorded API transactions") public McpCaptureReplayResult generateApi(String sessionPath, String outputDirectory, String packageName, String className, String style, String validationDepth, boolean overwrite, boolean replay, String openApiSpecPath, List<String> excludedTransactionIds, List<String> pinnedJsonPaths)
      Generates, compiles, and returns copy-paste SHAFT.API code blocks from a recorded session's API transactions.
      Parameters:
      sessionPath - persisted Capture JSON path inside the MCP workspace
      outputDirectory - generated project root inside the MCP workspace; blank selects generated-tests
      packageName - generated Java package
      className - optional generated class name; blank derives one from the session ID
      style - SCENARIO (default; chains correlated values through variables), PER_REQUEST (one independent test per transaction), or HYBRID_UI_API (interleaves API assertions after their correlated UI anchor; deterministic even with no AI enrichment)
      validationDepth - STATUS, STATUS_HEADERS, SCHEMA (default), FULL_BODY, or BUSINESS (pins each stable business field by JSON path; skips volatile/correlated/sensitive leaves)
      overwrite - whether existing artifacts may be replaced
      replay - whether to execute the generated test after compiling (off by default; unsafe to enable automatically for non-idempotent methods)
      openApiSpecPath - optional path (inside the MCP workspace) to an OpenAPI JSON/YAML spec to cross-report recorded endpoints against; blank skips coverage
      excludedTransactionIds - recorded transaction IDs to omit from generation entirely (drives a recorder transaction-table include/exclude selection); empty includes every renderable transaction
      pinnedJsonPaths - response JSON paths (e.g. $.status) to force-assert as business assertions at BUSINESS validation depth even when the leaf is classified volatile or correlated; a sensitive or blank-value leaf is never asserted regardless of pinning; empty pins nothing (the default)
      Returns:
      generated artifacts, compile/replay result, and copy-paste code blocks

    • apiResponseLeaves

      @Tool(name="capture_api_response_leaves", description="returns classified response-body leaves (stable/volatile/sensitive) per transaction for a recorded session without generating any test source, for a pin-this-path picker; sensitive values are redacted") public List<ApiCaptureGenerator.TransactionLeaves> apiResponseLeaves(String sessionPath, List<String> excludedTransactionIds)
      Lists classified response leaves (stable/volatile/sensitive) per transaction for a recorded session, without generating any test source -- the data source for a "pin this path as a business assertion" picker (issue #3530 negative-case). A sensitive leaf's value is redacted.
      Parameters:
      sessionPath - persisted Capture JSON path
      excludedTransactionIds - transaction ids to omit, same semantics as capture_api_generate
      Returns:
      one entry per renderable transaction, each carrying its classified leaves

    • checkpoint

      @Tool(name="capture_checkpoint", description="records a USER_MARKER, ASSERTION, PAGE_TRANSITION, RECOVERY, FLOW_START, or FLOW_END checkpoint") public CaptureStatus checkpoint(String description, String kind)
      Adds a human-review checkpoint to the active recording.
      Parameters:
      description - checkpoint description
      kind - checkpoint kind; blank selects USER_MARKER
      Returns:
      safe recorder status

    • setMode

      @Tool(name="capture_set_mode", description="reads or toggles the active recorder's live authoring mode: record (default) or inspect") public String setMode(String mode)
      Reads or toggles the active recorder's live authoring mode.
      Parameters:
      mode - blank reads the current mode without changing it; "record" or "inspect" (case-insensitive) sets it
      Returns:
      the mode now in effect

    • pickLocator

      @Tool(name="capture_pick_locator", description="ranks caller-supplied locator candidates for a picked element and returns a copy-paste SHAFT.GUI.Locator snippet") public CaptureService.McpPickLocatorResult pickLocator(List<CaptureService.McpLocatorCandidate> candidates)
      Ranks caller-supplied locator candidates for one picked element (best-first) and renders a copy-paste SHAFT.GUI.Locator... Java snippet for the winner. Mirrors CaptureControlServer's /locator/pick endpoint (used by a detached recorder UI); this MCP tool serves the same in-process, without a loopback HTTP round trip.

      When no valid candidates are supplied (for example, an IntelliJ Pick-Locator caret action probing readiness with an empty payload), this falls back to the last pick persisted under this service's session runtime directory by CaptureControlServer's /locator/pick endpoint -- see CaptureControlFiles.readLastPick(). Freshness of that persisted pick (how long ago it was captured) is a documented non-goal for v1; see CaptureControlFiles.LastPick.capturedAtMillis().

      Parameters:
      candidates - locator candidates observed for the picked element, e.g. from the recorder overlay's inspect-mode click handler
      Returns:
      the winning candidate's snippet plus every candidate ranked best-first

    • generateReplay

      public McpCaptureReplayResult generateReplay(String sessionPath, String outputDirectory, String packageName, String className, boolean overwrite, boolean replay, boolean useAi, boolean allowLocalAi, boolean allowRemoteAi, String driverVariableName)
      Generates, compiles, and optionally replays a deterministic SHAFT TestNG test from a Capture session.

      Plain Java overload with no progress reporting, preserved for direct callers (for example, white-box tests); the MCP-exposed tool is generateReplay(String, String, String, String, boolean, boolean, boolean, boolean, boolean, String, String, String, McpSyncServerExchange).

      Parameters:
      sessionPath - persisted Capture JSON path inside the MCP workspace
      outputDirectory - generated project root inside the MCP workspace
      packageName - generated Java package
      className - optional generated class name
      overwrite - whether existing generated source and test-data files may be replaced; status reports are always refreshed
      replay - whether to execute the generated test
      useAi - whether to request optional AI enrichment preview
      allowLocalAi - explicit approval for local inference
      allowRemoteAi - explicit approval for remote inference
      driverVariableName - Java driver variable name used in extracted snippets
      Returns:
      generation report plus copy-paste code blocks

    • generateReplay

      @McpTool(name="capture_generate_replay", description="generates, compiles, optionally replays, and returns copy-paste SHAFT code blocks from a persisted recording JSON (sessionPath); works on any recording file, no active capture session required; optional backend (web|playwright|mobile) selects the codegen target, defaulting to the active engine (absorbs playwright_capture_generate_replay/playwright_replay_recording/mobile_replay_recording)") public McpCaptureReplayResult generateReplay(@McpToolParam(required=false,description="persisted Capture JSON path inside the MCP workspace; blank uses the most recently modified recording under recordings/") String sessionPath, @McpToolParam(required=false,description="generated project root inside the MCP workspace; blank defaults to generated-tests under the workspace") String outputDirectory, @McpToolParam(required=false,description="generated Java package; blank defaults to generated.capture") String packageName, @McpToolParam(required=false,description="generated Java class name; blank derives a name from the recorded session (its goal, or a seeded name), suffixed Test") String className, @McpToolParam(required=false,description="whether existing generated source and test-data files may be replaced; status reports are always refreshed; defaults to false") boolean overwrite, @McpToolParam(required=false,description="whether to compile AND execute the generated test, replay-proving it: true is required for the report status to be SUCCESS (the replay actually passed); false -- or any replay that never runs, e.g. after a compilation failure -- yields codegen-only output the report marks UNCONFIRMED, never SUCCESS; defaults to false") boolean replay, @McpToolParam(required=false,description="whether to request optional AI enrichment preview") boolean useAi, @McpToolParam(required=false,description="explicit approval for local inference") boolean allowLocalAi, @McpToolParam(required=false,description="explicit approval for remote inference") boolean allowRemoteAi, @McpToolParam(required=false,description="Java driver variable name used in extracted snippets; blank defaults to driver") String driverVariableName, @McpToolParam(required=false,description="codegen target: web (default) | playwright | mobile; blank infers from the active engine") String backend, @McpProgressToken String progressToken, io.modelcontextprotocol.server.McpSyncServerExchange exchange)
      Generates, compiles, and optionally replays a deterministic SHAFT TestNG test from a Capture session, streaming best-effort milestone progress over the MCP exchange when the caller requested it.
      Parameters:
      sessionPath - persisted Capture JSON path inside the MCP workspace; blank uses the most recently modified recording under this workspace's recordings/
      outputDirectory - generated project root inside the MCP workspace
      packageName - generated Java package
      className - optional generated class name
      overwrite - whether existing generated source and test-data files may be replaced; status reports are always refreshed
      replay - whether to execute the generated test
      useAi - whether to request optional AI enrichment preview
      allowLocalAi - explicit approval for local inference
      allowRemoteAi - explicit approval for remote inference
      driverVariableName - Java driver variable name used in extracted snippets
      progressToken - MCP progress token supplied by the requester; null when the client did not request progress notifications
      exchange - live MCP server exchange used to emit progress notifications; injected by the annotation-scanning MCP tool provider, never exposed in the tool's input schema
      Returns:
      generation report plus copy-paste code blocks

    • codeBlocks

      @Tool(name="capture_code_blocks", description="generates a Java full-class snippet plus agent guidance for repo-aware insertion from a persisted recording JSON (sessionPath); works on any recording file, no active capture session required; optional backend (web|playwright|mobile) selects the codegen target, defaulting to the active engine (absorbs playwright_capture_code_blocks/mobile_recording_code_blocks)") public McpCaptureReplayResult codeBlocks(@ToolParam(required=false,description="persisted Capture JSON path inside the MCP workspace; blank uses the most recently modified recording under recordings/") String sessionPath, @ToolParam(required=false,description="generated project root inside the MCP workspace; defaults to generated-tests under the workspace") String outputDirectory, @ToolParam(required=false,description="Java package for the generated class; defaults to tests.generated") String packageName, @ToolParam(required=false,description="Java class name for the generated class; defaults to RecordedFlowTest") String className, @ToolParam(required=false,description="overwrite an existing generated file; defaults to false") Boolean overwrite, @ToolParam(required=false,description="Java driver variable name used in extracted snippets; defaults to driver") String driverVariableName, @ToolParam(required=false,description="codegen target: web (default) | playwright | mobile; blank infers from the active engine") String backend)
      Generates deterministic copy-paste code blocks from a persisted Capture session without replaying.
      Parameters:
      sessionPath - persisted Capture JSON path inside the MCP workspace; blank uses the most recently modified recording under this workspace's recordings/
      outputDirectory - generated project root inside the MCP workspace
      packageName - generated Java package
      className - optional generated class name
      overwrite - whether existing generated source and test-data files may be replaced; status reports are always refreshed
      driverVariableName - Java driver variable name used in extracted snippets
      Returns:
      generated snippets and report

    • recordAtTargetCodeBlocks

      @Tool(name="capture_record_at_target_code_blocks", description="generates focused Capture snippets for insertion at an existing Java source anchor; optional backend (web|playwright|mobile) selects the codegen target, defaulting to the active engine (absorbs playwright_record_at_target_code_blocks/mobile_record_at_target_code_blocks)") public McpCaptureReplayResult recordAtTargetCodeBlocks(@ToolParam(required=false,description="persisted Capture JSON path inside the MCP workspace; blank uses the most recently modified recording under recordings/") String sessionPath, @ToolParam(required=false,description="generated project root inside the MCP workspace; defaults to generated-tests under the workspace") String outputDirectory, @ToolParam(required=false,description="Java package for the generated class; defaults to tests.generated") String packageName, @ToolParam(required=false,description="Java class name for the generated class; defaults to RecordedFlowTest") String className, @ToolParam(required=false,description="overwrite an existing generated file; defaults to false") Boolean overwrite, String targetSourcePath, String insertAfter, @ToolParam(required=false,description="Java driver variable name used in extracted snippets; defaults to driver") String driverVariableName, @ToolParam(required=false,description="codegen target: web (default) | playwright | mobile; blank infers from the active engine") String backend)
      Generates focused record-at-target code blocks for an existing Java source anchor.
      Parameters:
      sessionPath - persisted Capture JSON path inside the MCP workspace
      outputDirectory - generated project root inside the MCP workspace
      packageName - generated Java package
      className - optional generated class name
      overwrite - whether existing generated source and test-data files may be replaced; status reports are always refreshed
      targetSourcePath - existing Java source path inside the MCP workspace
      insertAfter - method name or textual anchor to insert after
      driverVariableName - Java driver variable name used in extracted snippets
      Returns:
      generated snippets and report

    • targetCandidates

      @Tool(name="capture_target_candidates", description="suggests existing Java Page Object or test targets for Capture record-at-target insertion") public List<com.shaft.mcp.McpJavaTargetScanner.Candidate> targetCandidates(String repositoryPath, int maxResults)
      Suggests existing Java classes and anchors for record-at-target insertion.
      Parameters:
      repositoryPath - workspace-contained repository or source root
      maxResults - maximum candidates to return
      Returns:
      ranked Java target candidates

    • compareCodeBlocks

      @Tool(name="capture_backend_comparison", description="compares WebDriver and Playwright Capture code-block outputs without editing source") public CaptureService.CaptureBackendComparisonResult compareCodeBlocks(String sessionPath, String outputDirectory, String packageName, String className, boolean overwrite, String driverVariableName)
      Compares generated WebDriver and Playwright code blocks for the same Capture session.
      Parameters:
      sessionPath - persisted Capture JSON path inside the MCP workspace
      outputDirectory - generated project root inside the MCP workspace
      packageName - generated Java package
      className - optional generated class name
      overwrite - whether existing artifacts may be replaced
      driverVariableName - Java driver variable name used in extracted snippets
      Returns:
      backend comparison result

    • evidencePack

      @Tool(name="capture_evidence_pack", description="returns a local manifest of Capture source, report, review UI, screenshots, and checks") public McpEvidencePack evidencePack(String sourcePath, String reportPath, String reviewPath, List<String> screenshotPaths)
      Builds a local manifest of Capture codegen evidence for PR review.
      Parameters:
      sourcePath - generated source path inside the MCP workspace
      reportPath - generation report path inside the MCP workspace
      reviewPath - review UI or workbench path inside the MCP workspace
      screenshotPaths - optional screenshot paths inside the MCP workspace
      Returns:
      evidence manifest

    • generate

      public CaptureGenerationResult generate(String sessionPath, String outputDirectory, String packageName, String className, boolean overwrite, boolean replay, boolean aiPreview, String enrichmentPreviewPath, boolean applyEnrichment, boolean approveEnrichment, boolean allowLocalAi, boolean allowRemoteAi)
      Generates a deterministic SHAFT TestNG test from a persisted Capture session.
      Parameters:
      sessionPath - persisted Capture JSON path
      outputDirectory - generated project root
      packageName - generated Java package
      className - optional generated class name
      overwrite - whether existing artifacts may be replaced
      replay - whether to execute the compiled generated test
      aiPreview - whether to request a review-only AI proposal
      enrichmentPreviewPath - preview path to write or apply
      applyEnrichment - whether to apply the reviewed preview
      approveEnrichment - explicit approval to apply the preview
      allowLocalAi - explicit approval for local inference
      allowRemoteAi - explicit approval for remote inference
      Returns:
      generated artifacts and validation report