/**
 * types/index.ts
 *
 * Central type definitions for the entire Playwright Pilot AI system.
 *
 * This file is the single source of truth for all shared data shapes. Every
 * major subsystem (execution, healing, skills, YAML, MCP tools) imports its
 * types from here rather than defining them locally. This keeps cross-system
 * contracts explicit and makes type changes easy to track.
 *
 * Sections:
 *   - TestIntent / GeneratedTest — what a test is and what was generated
 *   - ElementContext             — rich element metadata stored in Page Objects for healing
 *   - StepContext                — per-step execution state written to disk
 *   - Healing                   — HealingContext, HealingResult, HealingStrategy
 *   - DOM analysis              — DOMElement, PageAnalysis
 *   - Config                    — FrameworkConfig, ExecutionReport
 *   - Skills                    — SkillResult, SkillContext
 *   - Compact page summary      — CompactElement, CompactStep
 *   - YAML test definition      — YamlLocator, YamlAssertion, YamlStep, TestYaml, YamlStepResult, YamlExecutionReport
 *   - CompactPageSummary        — the minimal structure Claude needs to write a spec
 */
/**
 * Describes what a test should do: its name, the URL to visit, and an ordered
 * list of natural-language steps. Saved to disk after generation and loaded
 * at execution time.
 */
export interface TestIntent {
    /** Human-readable test name, e.g. "empty login validation". */
    name: string;
    /** The original user prompt that triggered test generation. */
    prompt: string;
    /** The URL under test. */
    url: string;
    /** Ordered natural-language step descriptions, e.g. "click the Login button". */
    intent: string[];
    /** Additional metadata about when and how the test was generated. */
    metadata: IntentMetadata;
}
/** Metadata recorded alongside a TestIntent at generation time. */
export interface IntentMetadata {
    /** ISO timestamp when the intent was created. */
    generatedAt: string;
    /** The URL that was tested. */
    url: string;
    /** Framework identifier, always "playwright-pilot-ai". */
    framework: string;
}
/**
 * The full output of the test-generation process: the intent that drove it,
 * the generated TypeScript code, and where on disk it was saved.
 */
export interface GeneratedTest {
    intent: TestIntent;
    /** The full TypeScript source of the generated .spec.ts file. */
    code: string;
    /** Absolute path where the spec file was written. */
    filePath: string;
}
/**
 * Rich metadata about one interactive element, stored in the Page Object's
 * ELEMENT_CONTEXTS constant. Used by the HealingEngine to find alternative
 * locators when the original one fails.
 */
export interface ElementContext {
    /** Property name on the page object, e.g. "emailField" */
    key: string;
    /** Plain English description, e.g. "email input field" */
    description: string;
    /** HTML tag name, e.g. "input", "button". */
    tag?: string;
    /** ARIA role, e.g. "button", "textbox". */
    role?: string;
    /** Associated label text. */
    label?: string;
    /** Placeholder text for input fields. */
    placeholder?: string;
    /** Visible inner text of the element. */
    text?: string;
    /** data-testid attribute value if present. */
    testId?: string;
    /** Inferred interaction type — used by skill orchestrator and POM generator */
    actionType?: 'click' | 'fill' | 'select' | 'check' | 'assert' | 'navigate';
    /** Original locator expression used at generation time */
    originalLocator: string;
}
/**
 * Records the execution state of one test step, written to disk before and
 * after every step so that healing and reporting have accurate, current data.
 */
export interface StepContext {
    /** Name of the test this step belongs to. */
    testName: string;
    /** Zero-based position of this step in the test. */
    stepIndex: number;
    /** Human-readable description of what this step does. */
    stepDescription: string;
    /** Key into the page object's ELEMENT_CONTEXTS */
    elementKey?: string;
    /** The full element context for this step's target element, if available. */
    elementContext?: ElementContext;
    /** The locator expression that was used for this step. */
    locatorUsed: string;
    /** Current execution status of this step. */
    status: 'pending' | 'passed' | 'failed' | 'healed';
    /** Error message if the step failed. */
    error?: string;
    /** Path to the screenshot captured at failure time. */
    screenshotPath?: string;
    /** Path to the DOM snapshot HTML file captured at failure time. */
    domSnapshotPath?: string;
    /** Locator that healed the step, if healing succeeded */
    healedLocator?: string;
    /** Name of the healing strategy that succeeded, e.g. "element-context". */
    healingStrategy?: string;
    /** ISO timestamp when this context was last written. */
    timestamp: string;
}
/**
 * All the information available to the HealingEngine when a step fails.
 */
export interface HealingContext {
    /** Zero-based step index. */
    stepIndex: number;
    /** Human-readable description of the failed step. */
    stepDescription: string;
    /** The error message from Playwright. */
    failureReason: string;
    /** Path to the screenshot captured at failure time. */
    screenshotPath: string;
    /** Full HTML snapshot of the page at failure time. */
    domSnapshot: string;
    /** The test intent being executed. */
    intent: TestIntent;
    /** Stored element metadata for the failing step, if available. */
    elementContext?: ElementContext;
}
/**
 * The outcome of a healing attempt — whether it succeeded, what locator was
 * found (if any), and which strategy produced it.
 */
export interface HealingResult {
    /** True if a working alternative locator was found. */
    success: boolean;
    /** The locator expression that was found to work. Present only when success is true. */
    repairedLocator?: string;
    /** Which healing strategy produced this result. */
    strategy: HealingStrategy;
    /** Human-readable explanation of the result. */
    notes: string;
}
/** The strategies the HealingEngine tries, in order of preference. */
export type HealingStrategy = 'retry' | 'element-context' | 'semantic-text' | 'accessibility' | 'nearby-dom' | 'failed';
/**
 * A single interactive element extracted from the live page DOM.
 * All fields except tag and selector are optional because not every element
 * will have all attributes.
 */
export interface DOMElement {
    /** HTML tag name, e.g. "button", "input", "a". */
    tag: string;
    /** ARIA role attribute value. */
    role?: string;
    /** Accessible label (from aria-label or associated <label> element). */
    label?: string;
    /** Input placeholder text. */
    placeholder?: string;
    /** Visible inner text content. */
    text?: string;
    /** data-testid attribute value. */
    testId?: string;
    /** id attribute value. */
    id?: string;
    /** name attribute value (common on form inputs). */
    name?: string;
    /** type attribute (for inputs: text, email, password, checkbox, etc.). */
    type?: string;
    /** href attribute for anchor elements. */
    href?: string;
    /** The best available CSS selector for this element. */
    selector: string;
}
/**
 * The complete structured analysis of a single page, produced by DOMAnalyzer.
 * Elements are categorized into lists so skills can focus on the subset they care about.
 */
export interface PageAnalysis {
    /** The current page URL. */
    url: string;
    /** The page title. */
    title: string;
    /** All interactable elements found (buttons, inputs, links, etc.). */
    interactableElements: DOMElement[];
    /** Form field elements (input, textarea, select). */
    forms: DOMElement[];
    /** Navigation and link elements. */
    navigation: DOMElement[];
    /** Table and grid elements. */
    tables: DOMElement[];
    /** Dialog and alertdialog elements. */
    popups: DOMElement[];
}
/**
 * Top-level configuration for the Playwright Pilot AI framework,
 * loaded from environment variables by config-loader.ts.
 */
export interface FrameworkConfig {
    /** Base URL of the application under test. */
    baseUrl: string;
    /** Absolute path to the directory where spec files are saved. */
    testsDir: string;
    /** Absolute path to the root artifacts directory. */
    artifactsDir: string;
}
/**
 * The complete result of running a TestIntent: overall status, timing,
 * healing counts, and per-step context records.
 */
export interface ExecutionReport {
    /** Name of the test that was run. */
    testName: string;
    /** Whether the test passed, failed, or passed with healing. */
    status: 'passed' | 'failed' | 'healed';
    /** Total wall-clock duration in milliseconds. */
    duration: number;
    /** Number of steps where healing was attempted (not necessarily successful). */
    healingAttempts: number;
    /** Per-step execution records in step order. */
    stepContexts: StepContext[];
    /** ISO timestamp when the run completed. */
    timestamp: string;
}
/**
 * The output produced by a single skill's execute() call.
 */
export interface SkillResult {
    /** Identifies which skill produced this result. */
    skillName: string;
    /** How confident the skill is in its results (0–1). */
    confidence: number;
    /** Playwright locator expression strings found by this skill. */
    selectors: string[];
    /** Element context objects built by this skill (may be empty). */
    elementContexts: ElementContext[];
    /** Optional TypeScript code snippet generated by this skill. */
    generatedCode?: string;
    /** Optional extra data (e.g. CompactStep[] from AssertionGenerationSkill). */
    metadata?: Record<string, unknown>;
}
/**
 * The input context provided to every skill's execute() call.
 */
export interface SkillContext {
    /** The page analysis to work with. */
    pageAnalysis: PageAnalysis;
    /** The user's natural-language test description. */
    userPrompt?: string;
    /** Ordered list of natural-language steps from the user. */
    intentSteps?: string[];
    /** Failure context — present when the skill is being used for healing. */
    failureContext?: HealingContext;
    /** Kebab-case slug for file naming, e.g. "checkout-flow" */
    slug?: string;
    /** PascalCase class name, e.g. "CheckoutFlowPage" */
    className?: string;
    /** Target output language — 'javascript' for CommonJS Node.js, 'typescript' for TS (default). */
    language?: 'javascript' | 'typescript';
}
/** One element entry in the compact page summary — all fields MCP-resolved */
export interface CompactElement {
    /** Camelcase key matching the POM property name, e.g. "emailField". */
    key: string;
    /** The action this element is used for. */
    action: 'fill' | 'click' | 'select' | 'check' | 'navigate' | 'assert';
    /** Ready-to-use Playwright locator expression string. */
    locator: string;
    /** POM method name, e.g. "fillEmail". */
    method: string;
    /** Human-readable label for display in the prompt table. */
    label?: string;
}
/** Compact flow step — MCP-derived, one line in the spec */
export interface CompactStep {
    /** Step position (0-based). */
    index: number;
    /** Human-readable step description. */
    description: string;
    /** Matches CompactElement.key */
    elementKey?: string;
    /** Ready-to-use expect() assertion expressions for this step. */
    assertions: string[];
}
/** Locator strategy entry — mirrors Playwright's locator API */
export interface YamlLocator {
    /** The Playwright strategy to use for locating the element. */
    strategy: 'getByRole' | 'getByLabel' | 'getByPlaceholder' | 'getByText' | 'getByTestId' | 'css';
    /** The value to pass to the strategy (role name, label text, CSS selector, etc.). */
    value: string;
    /** Additional options passed to the Playwright locator method, e.g. { name: 'Login', exact: true }. */
    options?: Record<string, unknown>;
}
/** Inline assertion inside a step */
export interface YamlAssertion {
    /** The kind of assertion to perform. */
    type: 'visible' | 'hidden' | 'text' | 'url' | 'title' | 'count' | 'attribute' | 'enabled' | 'checked';
    /** The element to assert against (required for all types except url and title). */
    locator?: YamlLocator;
    /** The expected value: boolean for visible/hidden/checked, string for text/url/title, number for count. */
    expected?: string | number | boolean;
    /** Attribute name — required only for type="attribute". */
    attribute?: string;
}
/** One executable step in the YAML test definition */
export interface YamlStep {
    /** Step number (0-based). */
    index: number;
    /** Human-readable description of what this step does. */
    description: string;
    /** The action to perform. */
    action: 'navigate' | 'click' | 'fill' | 'select' | 'check' | 'uncheck' | 'hover' | 'scroll' | 'wait' | 'screenshot' | 'assert' | 'pressKey';
    /** Primary locator — used first */
    locator?: YamlLocator;
    /** Ordered fallbacks tried when primary locator fails (self-healing) */
    fallbackLocators?: YamlLocator[];
    /** POM element key — for cross-reference with intent JSON */
    elementKey?: string;
    /** Fill value, URL for navigate, key name for pressKey, waitFor state for wait */
    value?: string;
    /** waitFor state after action: networkidle | load | domcontentloaded | selector */
    waitFor?: 'networkidle' | 'load' | 'domcontentloaded' | string;
    /** Assertion to evaluate after the action */
    assertion?: YamlAssertion;
    /** Screenshot output path (for action=screenshot) */
    screenshotPath?: string;
    /** Timeout override in ms for this step */
    timeout?: number;
    /** If true, continue even if this step fails */
    continueOnFailure?: boolean;
}
/** Top-level portable YAML test definition */
export interface TestYaml {
    /** Schema version — always "1.0". */
    version: '1.0';
    /** Human-readable test name. */
    name: string;
    /** What this test verifies. */
    description: string;
    /** The URL under test. */
    url: string;
    /** How this test was created. */
    source: 'live-browser' | 'video' | 'steps';
    /** ISO timestamp when this file was generated. */
    generatedAt: string;
    /** Test execution configuration. */
    config: {
        waitForNetworkIdle: boolean;
        screenshotOnFailure: boolean;
        continueOnFailure: boolean;
        /** Default step timeout in milliseconds. */
        defaultTimeout: number;
        headless: boolean;
    };
    /** Ordered list of executable steps. */
    steps: YamlStep[];
    /** Paths to related artifacts generated at the same time. */
    artifacts: {
        pomPath: string;
        specPath: string;
        yamlPath: string;
        intentPath: string;
    };
}
/** Result of a single YAML step execution */
export interface YamlStepResult {
    /** Step index matching the YamlStep. */
    index: number;
    /** Human-readable step description. */
    description: string;
    /** Outcome of the step. */
    status: 'passed' | 'failed' | 'healed' | 'skipped';
    /** The locator expression that was actually used (may be a fallback). */
    locatorUsed?: string;
    /** The fallback locator that healed the step, if healing occurred. */
    healedLocator?: string;
    /** Error message if the step failed. */
    error?: string;
    /** Path to a screenshot taken during or after this step. */
    screenshotPath?: string;
    /** How long this step took in milliseconds. */
    durationMs: number;
}
/** Full YAML execution report */
export interface YamlExecutionReport {
    /** Name of the test that was run. */
    testName: string;
    /** Path to the YAML file that was executed. */
    yamlPath: string;
    /** Overall outcome: "passed" if all steps passed, "partial" if some failed, "failed" if all failed. */
    status: 'passed' | 'failed' | 'partial';
    /** Number of steps that passed (including healed steps). */
    passed: number;
    /** Number of steps that failed. */
    failed: number;
    /** Number of steps that passed only after healing. */
    healed: number;
    /** Total wall-clock duration in milliseconds. */
    durationMs: number;
    /** Per-step result records. */
    steps: YamlStepResult[];
    /** ISO timestamp when the run completed. */
    timestamp: string;
}
/**
 * Everything Claude needs to write the spec — no raw DOM, no giant JSON.
 * Built by generate_test and passed back to the MCP server.
 */
export interface CompactPageSummary {
    /** The page URL. */
    url: string;
    /** The page title. */
    title: string;
    /** Kebab-case test slug. */
    slug: string;
    /** PascalCase POM class name. */
    className: string;
    /** Relative path where the POM should be saved. */
    pomPath: string;
    /** Relative path where the spec should be saved. */
    testPath: string;
    /** Compact element table for the prompt. */
    elements: CompactElement[];
    /** Ordered flow steps with assertion expressions. */
    steps: CompactStep[];
    /** Complete POM TypeScript source — MCP-generated, Claude saves verbatim. */
    pomCode: string;
}
/**
 * Result returned by the project scaffolder after initialising a new project.
 * Included in SaveTestOutput when the target directory was empty.
 */
export interface ScaffoldResult {
    /** Absolute path to the project root that was scaffolded. */
    projectRoot: string;
    /**
     * Relative paths of files that were newly created.
     * Files that already existed are omitted (scaffolding is idempotent).
     */
    filesCreated: string[];
    /**
     * Ordered shell commands the user should run after scaffolding
     * (e.g. npm install, npx playwright install).
     */
    nextSteps: string[];
}
//# sourceMappingURL=index.d.ts.map