Praman — Agent-First SAP UI5 Test Automation Plugin - v1.2.0
    Preparing search index...

    Class AgenticHandler

    Autonomous test operation handler with checkpoint-based resumability.

    Orchestrates LLM calls, capability lookups, and checkpoint management for AI-driven test generation. All methods return AiResponse<T> envelopes — never throw on LLM errors.

    Execute autonomous SAP UI5 test operations

    pramanAI.agentic

    All

    const handler = new AgenticHandler(llm, buildPageContext, capabilities);
    const result = await handler.generateTest('Create a PO for vendor V001', page);
    if (result.status === 'success') {
      for (const step of result.data.steps) {
        await handler.interpretStep(step, page);
      }
    }
    Index

    Constructors

    constructor

    Methods

    generateTest interpretStep resumeFromCheckpoint saveCheckpoint suggestActions

    Constructors

    • Constructs an AgenticHandler.

      Parameters

      • llm: LlmService

        LLM provider service for sending prompts.

      • contextBuilder: (
            page: DiscoveryPage,
            config: Readonly<PramanConfig>,
        ) => Promise<AiResponse<PageContext>>

        Function to build page context (same as buildPageContext).

          • (
                page: DiscoveryPage,
                config: Readonly<PramanConfig>,
            ): Promise<AiResponse<PageContext>>

          • Builds a complete AI PageContext from the current Playwright page state.

            Parameters

            • page: DiscoveryPage

              Playwright Page instance (or any structural equivalent).

            • config: Readonly<PramanConfig>

              Readonly Praman configuration (used for timeout).

            Returns Promise<AiResponse<PageContext>>

            AiResponse<PageContext> — matches the shape returned by discoverPage(), potentially enriched with ui5Version.

            Combines bulk control discovery with UI5 version detection. The UI5 version is read via a separate page.evaluate() call and merged into the returned PageContext only when it is available. If the version call fails (e.g. the page is not a UI5 application), the context is still returned successfully without ui5Version.

            Uses config.controlDiscoveryTimeout as the discovery timeout.

            Build AI context from current page UI5 state

            pramanAI.buildContext

            All

            import { buildPageContext } from '#ai/context-builder.js';

            const response = await buildPageContext(page, config);
            if (response.status === 'success') {
              logger.info('UI5 version:', response.data.ui5Version ?? 'unknown');
              logger.info('Controls found:', response.data.controls.length);
            }
      • capabilityRegistry: CapabilityRegistry

        Registry of available Praman capabilities.

      • recipeRegistry: RecipeRegistry = ...

        Optional registry of reusable test recipes (defaults to a new RecipeRegistry).

      Returns AgenticHandler

      const handler = new AgenticHandler(llm, buildPageContext, capabilities);

    Methods

    • Generate a test for a natural language scenario.

      Parameters

      • scenario: string

        Natural language description of the test scenario.

      • page: DiscoveryPage

        Playwright page (or structural equivalent).

      Returns Promise<AiResponse<AiGeneratedTest>>

      AiResponse<AiGeneratedTest> with steps and generated TypeScript code.

      Returns AiResponse<AiGeneratedTest> — both natural language steps AND runnable TypeScript code. Each step is executed separately via interpretStep(step: string): Promise<AiResponse<void>> which maps step text to Praman fixture calls using the CapabilityRegistry.

      This two-phase design (generate → execute) enables checkpoint/resume (AgenticCheckpoint): if step 3 fails, re-execute from step 3 without re-generating the full step list.

      Translate business scenario to executable Praman test steps and code

      const result = await handler.generateTest(
        'Create a purchase order for vendor V001, material M1000, quantity 10',
        page,
      );
      if (result.status === 'success') {
        logger.info('Steps:', result.data.steps);
        logger.info('Code:', result.data.code);
      }

    • Execute a single natural language step by mapping it to Praman fixture calls.

      Parameters

      • step: string

        Natural language step description.

      • page: DiscoveryPage

        Playwright page (or structural equivalent).

      Returns Promise<AiResponse<void>>

      AiResponse<void> indicating success or failure.

      Maps step text to registered capabilities in CapabilityRegistry. Used with generateTest() for two-phase generate → execute workflow. On failure, the AgenticCheckpoint captures progress for resume.

      Execute a single natural language step

      const result = await handler.interpretStep('Fill Vendor field with 100001', page);
      if (result.status === 'error') {
        log.error({ err: result.error }, 'Step failed');
      }
    • Beta

      Resume from a previously saved checkpoint.

      Parameters

      • checkpointId: string

        Session ID of the checkpoint to retrieve.

      Returns AgenticCheckpoint | undefined

      The checkpoint if found, or undefined.

      Beta — checkpoint serialization format may change in minor releases.

      Returns the in-memory checkpoint. For cross-process resume, first load from disk and call saveCheckpoint before calling this method.

      const checkpoint = handler.resumeFromCheckpoint('sess-001');
      if (checkpoint) {
        // Resume execution from where it left off
        const remaining = checkpoint.remainingSteps;
        for (const step of remaining) {
          await handler.interpretStep(step, page);
        }
      }
    • Beta

      Save an execution checkpoint for later resumability.

      Parameters

      Returns void

      Beta — checkpoint serialization format may change in minor releases.

      Stores the checkpoint in an in-memory Map keyed by checkpoint.sessionId. Retrieve via resumeFromCheckpoint.

      For cross-process persistence, serialize with JSON.stringify(checkpoint) before saving to disk, then restore with handler.saveCheckpoint(JSON.parse(stored) as AgenticCheckpoint).

      handler.saveCheckpoint({
        sessionId: 'sess-001',
        currentStep: 2,
        completedSteps: ['navigate', 'fillVendor'],
        remainingSteps: ['fillMaterial', 'save'],
        state: {},
        timestamp: new Date().toISOString(),
      });

    • Suggest next actions given the current page state.

      Parameters

      • pageContext: PageContext

        Current page context snapshot.

      Returns Promise<AiResponse<string[]>>

      AiResponse<string[]> containing action suggestions.

      Returns AI-recommended operations based on discovered controls and the current page context. Returns AiResponse<string[]> with a list of human-readable action suggestions.

      const suggestions = await handler.suggestActions(pageContext);
      if (suggestions.status === 'success') {
        logger.info('Next actions:', suggestions.data);
      }

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods