browsecraft 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,984 @@
+import { NodeRemoteValue, BrowserName, BiDiSession, StorageCookie } from 'browsecraft-bidi';
+export { StorageCookie } from 'browsecraft-bidi';
+export { After, AfterFeature, AfterStep, AutoStepOptions, AutoStepResult, AfterAll as BddAfterAll, BeforeAll as BddBeforeAll, BddExecutor, Before, BeforeFeature, BeforeStep, BrowsecraftDataTable, ExecutorOptions, FeatureResult, GeneratedStepDef, GherkinDocument, Feature as GherkinFeature, Scenario as GherkinScenario, Given, RunResult, ScenarioContext, ScenarioResult, Step, StepDefinition, StepFunction, StepMatch, StepResult, StepStatus, StepWorld, Then, TsBddOptions, When, and, autoGenerateSteps, autoGenerateStepsFromDocument, but, clearFeatures, createExecutor, defineParameterType, feature, getSupportedLanguages, given, globalRegistry, matchesTags, parseGherkin, parseTagExpression, pending, runFeatures, scenario, then, when } from 'browsecraft-bdd';
+
+/** What the user passes to click(), fill(), get() */
+type ElementTarget = string | LocatorOptions;
+/** Advanced locator options (for when you need precision) */
+interface LocatorOptions {
+    /** Find by ARIA role (e.g., 'button', 'link', 'textbox') */
+    role?: string;
+    /** Find by accessible name or visible text */
+    name?: string;
+    /** Find by <label> text (for form inputs) */
+    label?: string;
+    /** Find by visible text content */
+    text?: string;
+    /** Find by data-testid attribute */
+    testId?: string;
+    /** Find by CSS selector */
+    selector?: string;
+    /** Require exact text match (default: false = partial match) */
+    exact?: boolean;
+    /** Which match to use if multiple found (0-based, default: 0) */
+    index?: number;
+}
+/** Result of locating an element */
+interface LocatedElement {
+    /** The node reference for BiDi commands */
+    node: NodeRemoteValue;
+    /** How we found it (for debugging/logging) */
+    strategy: string;
+}
+
+/** Full configuration with all options */
+interface BrowsecraftConfig {
+    /** Which browser to use (default: 'chrome') */
+    browser: BrowserName;
+    /** Run in headless mode (default: true) */
+    headless: boolean;
+    /** Global timeout for actions in ms (default: 30000) */
+    timeout: number;
+    /** How many times to retry a failed test (default: 0) */
+    retries: number;
+    /** Take screenshots: 'always', 'on-failure', or 'never' (default: 'on-failure') */
+    screenshot: 'always' | 'on-failure' | 'never';
+    /** Base URL prepended to all page.goto() calls (default: '') */
+    baseURL: string;
+    /** Custom browser executable path */
+    executablePath?: string;
+    /** Viewport size (default: 1280x720) */
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** Start the browser window maximized (headed mode only, default: false) */
+    maximized: boolean;
+    /** Number of parallel workers (default: CPU cores / 2) */
+    workers: number;
+    /** Test file pattern (default: '**\/*.test.{ts,js,mts,mjs}') */
+    testMatch: string;
+    /** Output directory for reports/screenshots (default: '.browsecraft') */
+    outputDir: string;
+    /** AI mode: 'auto' detects GitHub Models availability, 'off' disables (default: 'auto') */
+    ai: 'auto' | 'off' | AIConfig;
+    /** Enable verbose debug logging (default: false) */
+    debug: boolean;
+}
+interface AIConfig {
+    provider: 'github-models';
+    /** Model to use (default: 'openai/gpt-4o-mini') */
+    model?: string;
+    /** Explicit GitHub token (overrides env vars) */
+    token?: string;
+}
+/** Users provide a partial config -- everything has smart defaults */
+type UserConfig = Partial<BrowsecraftConfig>;
+/**
+ * Define your Browsecraft config with full type safety and IntelliSense.
+ * This function is optional -- it's just a type helper for your IDE.
+ *
+ * ```ts
+ * // browsecraft.config.ts
+ * import { defineConfig } from 'browsecraft';
+ *
+ * export default defineConfig({
+ *   browser: 'firefox',
+ *   timeout: 60_000,
+ * });
+ * ```
+ */
+declare function defineConfig(config: UserConfig): UserConfig;
+/**
+ * Resolve user config by merging with defaults.
+ * This is used internally -- users never call this.
+ */
+declare function resolveConfig(userConfig?: UserConfig): BrowsecraftConfig;
+
+/** Options for page.goto() */
+interface GotoOptions {
+    /** Wait until page reaches this state (default: 'complete') */
+    waitUntil?: 'none' | 'interactive' | 'complete';
+    /** Timeout in ms (default: config.timeout) */
+    timeout?: number;
+}
+/** Options for page.fill() */
+interface FillOptions {
+    /** Timeout in ms (default: config.timeout) */
+    timeout?: number;
+}
+/** Options for page.click() */
+interface ClickOptions {
+    /** Timeout in ms (default: config.timeout) */
+    timeout?: number;
+    /** Mouse button (default: 0 = left) */
+    button?: number;
+    /** Number of clicks (default: 1, use 2 for double-click) */
+    clickCount?: number;
+}
+/** Mock response definition */
+interface MockResponse {
+    /** HTTP status code */
+    status?: number;
+    /** Response headers */
+    headers?: Record<string, string>;
+    /** Response body (string or object that will be JSON-stringified) */
+    body?: string | Record<string, unknown>;
+    /** Content type (default: 'application/json' for objects, 'text/plain' for strings) */
+    contentType?: string;
+}
+/**
+ * Page represents a single browser tab/page.
+ * This is the main API surface users interact with.
+ *
+ * Every action auto-waits for the element to be ready.
+ * No sleep(). No waitFor(). It just works.
+ */
+declare class Page {
+    /** @internal */
+    readonly session: BiDiSession;
+    /** @internal */
+    readonly contextId: string;
+    /** @internal */
+    private config;
+    /** @internal */
+    private interceptIds;
+    /** @internal -- event listener unsubscribe functions for cleanup */
+    private eventCleanups;
+    constructor(session: BiDiSession, contextId: string, config: BrowsecraftConfig);
+    /**
+     * Navigate to a URL.
+     *
+     * ```ts
+     * await page.goto('https://example.com');
+     * await page.goto('/login');  // uses baseURL from config
+     * ```
+     */
+    goto(url: string, options?: GotoOptions): Promise<void>;
+    /**
+     * Reload the current page.
+     */
+    reload(options?: GotoOptions): Promise<void>;
+    /**
+     * Go back in browser history.
+     */
+    goBack(): Promise<void>;
+    /**
+     * Go forward in browser history.
+     */
+    goForward(): Promise<void>;
+    /**
+     * Click an element. Finds it by text, role, or selector -- auto-waits.
+     *
+     * ```ts
+     * await page.click('Submit');                           // by text
+     * await page.click({ role: 'button', name: 'Submit' }); // precise
+     * await page.click({ selector: '#my-button' });          // CSS
+     * ```
+     */
+    click(target: ElementTarget, options?: ClickOptions): Promise<void>;
+    /**
+     * Fill a text input. First arg finds the input, second is the value.
+     *
+     * ```ts
+     * await page.fill('Email', 'user@test.com');       // by label
+     * await page.fill('Search', 'browsecraft');          // by placeholder
+     * await page.fill({ selector: '#email' }, 'test');   // by CSS
+     * ```
+     */
+    fill(target: ElementTarget, value: string, options?: FillOptions): Promise<void>;
+    /**
+     * Type text character by character (triggers keyboard events).
+     * Use this instead of fill() when you need realistic keyboard input.
+     *
+     * ```ts
+     * await page.type('Search', 'browsecraft');
+     * ```
+     */
+    type(target: ElementTarget, text: string, options?: FillOptions): Promise<void>;
+    /**
+     * Select an option from a <select> dropdown.
+     *
+     * ```ts
+     * await page.select('Country', 'United States');
+     * ```
+     */
+    select(target: ElementTarget, value: string, options?: FillOptions): Promise<void>;
+    /**
+     * Check a checkbox or radio button.
+     *
+     * ```ts
+     * await page.check('I agree to the terms');
+     * ```
+     */
+    check(target: ElementTarget, options?: ClickOptions): Promise<void>;
+    /**
+     * Uncheck a checkbox.
+     */
+    uncheck(target: ElementTarget, options?: ClickOptions): Promise<void>;
+    /**
+     * Hover over an element.
+     *
+     * ```ts
+     * await page.hover('Profile Menu');
+     * ```
+     */
+    hover(target: ElementTarget, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Get a single element. Returns an ElementHandle for assertions.
+     *
+     * ```ts
+     * const heading = page.get('Welcome back!');
+     * await expect(heading).toBeVisible();
+     * ```
+     */
+    get(target: ElementTarget): ElementHandle;
+    /**
+     * Get a locator by visible text. Alias for get() with text matching.
+     *
+     * ```ts
+     * const btn = page.getByText('Submit');
+     * ```
+     */
+    getByText(text: string, options?: {
+        exact?: boolean;
+    }): ElementHandle;
+    /**
+     * Get a locator by ARIA role and optional name.
+     *
+     * ```ts
+     * const btn = page.getByRole('button', { name: 'Submit' });
+     * ```
+     */
+    getByRole(role: string, options?: {
+        name?: string;
+        exact?: boolean;
+    }): ElementHandle;
+    /**
+     * Get a locator by label text (for form inputs).
+     *
+     * ```ts
+     * const email = page.getByLabel('Email Address');
+     * ```
+     */
+    getByLabel(label: string, options?: {
+        exact?: boolean;
+    }): ElementHandle;
+    /**
+     * Get a locator by data-testid attribute.
+     *
+     * ```ts
+     * const card = page.getByTestId('user-card');
+     * ```
+     */
+    getByTestId(testId: string): ElementHandle;
+    /** Get the current page URL */
+    url(): Promise<string>;
+    /** Get the page title */
+    title(): Promise<string>;
+    /** Get the full page HTML content */
+    content(): Promise<string>;
+    /**
+     * Get cookies for the current page's browsing context.
+     *
+     * ```ts
+     * const cookies = await page.cookies();
+     * const session = cookies.find(c => c.name === 'session_id');
+     * ```
+     */
+    cookies(filter?: {
+        name?: string;
+        domain?: string;
+        path?: string;
+    }): Promise<StorageCookie[]>;
+    /**
+     * Set one or more cookies.
+     *
+     * ```ts
+     * await page.setCookies([
+     *   { name: 'token', value: 'abc123', domain: 'example.com' },
+     *   { name: 'theme', value: 'dark', domain: 'example.com' },
+     * ]);
+     * ```
+     */
+    setCookies(cookies: Array<{
+        name: string;
+        value: string;
+        domain?: string;
+        path?: string;
+        httpOnly?: boolean;
+        secure?: boolean;
+        sameSite?: 'strict' | 'lax' | 'none';
+        expiry?: number;
+    }>): Promise<void>;
+    /**
+     * Clear all cookies (or those matching a filter).
+     *
+     * ```ts
+     * await page.clearCookies();                           // all cookies
+     * await page.clearCookies({ name: 'session_id' });     // specific cookie
+     * await page.clearCookies({ domain: 'example.com' });  // by domain
+     * ```
+     */
+    clearCookies(filter?: {
+        name?: string;
+        domain?: string;
+        path?: string;
+    }): Promise<void>;
+    /**
+     * Execute JavaScript in the page and return the result.
+     *
+     * ```ts
+     * const title = await page.evaluate('document.title');
+     * const count = await page.evaluate(() => document.querySelectorAll('li').length);
+     * ```
+     */
+    evaluate<T = unknown>(expression: string | (() => T)): Promise<T>;
+    /**
+     * Take a screenshot of the page.
+     *
+     * ```ts
+     * const buffer = await page.screenshot();
+     * ```
+     */
+    screenshot(): Promise<Buffer>;
+    /**
+     * Mock a network request with a fake response.
+     *
+     * ```ts
+     * await page.mock('POST /api/login', { status: 200, body: { token: 'abc' } });
+     * await page.mock('GET /api/users', { status: 500 });
+     * await page.mock('https://api.example.com/data', { body: { items: [] } });
+     * ```
+     */
+    mock(pattern: string, response: MockResponse): Promise<void>;
+    /**
+     * Remove all network mocks and clean up event listeners.
+     */
+    clearMocks(): Promise<void>;
+    /**
+     * Accept the next dialog (alert, confirm, prompt).
+     *
+     * ```ts
+     * await page.acceptDialog();
+     * page.click('Delete'); // triggers confirm dialog
+     * ```
+     */
+    acceptDialog(text?: string): Promise<void>;
+    /**
+     * Dismiss the next dialog.
+     */
+    dismissDialog(): Promise<void>;
+    /**
+     * Double-click an element.
+     *
+     * ```ts
+     * await page.dblclick('Edit');
+     * ```
+     */
+    dblclick(target: ElementTarget, options?: ClickOptions): Promise<void>;
+    /**
+     * Tap an element (touch gesture).
+     *
+     * ```ts
+     * await page.tap('Menu');
+     * ```
+     */
+    tap(target: ElementTarget, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Focus an element.
+     *
+     * ```ts
+     * await page.focus('Email');
+     * ```
+     */
+    focus(target: ElementTarget, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Remove focus from an element.
+     *
+     * ```ts
+     * await page.blur('Email');
+     * ```
+     */
+    blur(target: ElementTarget, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Get the visible inner text of an element (like element.innerText).
+     *
+     * ```ts
+     * const text = await page.innerText('h1');
+     * ```
+     */
+    innerText(target: ElementTarget, options?: {
+        timeout?: number;
+    }): Promise<string>;
+    /**
+     * Get the innerHTML of an element.
+     *
+     * ```ts
+     * const html = await page.innerHTML('.container');
+     * ```
+     */
+    innerHTML(target: ElementTarget, options?: {
+        timeout?: number;
+    }): Promise<string>;
+    /**
+     * Get the current value of an input/textarea/select.
+     *
+     * ```ts
+     * const email = await page.inputValue('Email');
+     * ```
+     */
+    inputValue(target: ElementTarget, options?: {
+        timeout?: number;
+    }): Promise<string>;
+    /**
+     * Select multiple options from a <select multiple> dropdown.
+     *
+     * ```ts
+     * await page.selectOption('Colors', ['red', 'blue']);
+     * ```
+     */
+    selectOption(target: ElementTarget, values: string | string[], options?: FillOptions): Promise<void>;
+    /**
+     * Drag an element to another element or position.
+     *
+     * ```ts
+     * await page.dragTo('Draggable', 'Drop Zone');
+     * ```
+     */
+    dragTo(source: ElementTarget, dest: ElementTarget, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Wait for an element matching the target to appear in the DOM.
+     *
+     * ```ts
+     * await page.waitForSelector('.loaded');
+     * await page.waitForSelector({ role: 'dialog' });
+     * ```
+     */
+    waitForSelector(target: ElementTarget, options?: {
+        timeout?: number;
+        state?: 'attached' | 'visible' | 'hidden';
+    }): Promise<ElementHandle>;
+    /**
+     * Wait for a JavaScript function to return a truthy value.
+     *
+     * ```ts
+     * await page.waitForFunction('document.querySelectorAll("li").length > 5');
+     * await page.waitForFunction(() => window.appReady === true);
+     * ```
+     */
+    waitForFunction<T = unknown>(expression: string | (() => T), options?: {
+        timeout?: number;
+    }): Promise<T>;
+    /**
+     * Wait for a specific URL. Usually you use expect(page).toHaveURL() instead.
+     */
+    waitForURL(url: string | RegExp, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Wait for the page to finish loading.
+     */
+    waitForLoadState(state?: 'load' | 'domcontentloaded'): Promise<void>;
+    /**
+     * Close this page/tab.
+     */
+    close(): Promise<void>;
+    /**
+     * Press a keyboard key.
+     *
+     * ```ts
+     * await page.press('Enter');
+     * await page.press('Control+a');
+     * ```
+     */
+    press(key: string): Promise<void>;
+    /** Resolve a relative URL against the baseURL */
+    private resolveURL;
+    /** Get a shared reference from a located node */
+    private getSharedRef;
+    /** Get the center coordinates of an element */
+    private getElementCenter;
+    /**
+     * Scroll element into view and click it.
+     *
+     * Uses JavaScript `.click()` as the primary mechanism because it is
+     * immune to viewport coordinate mismatches, DPI scaling, layout shifts,
+     * and Chrome BiDi's unreliable element-origin support. This works
+     * identically in headless and headed mode, with or without slowMo delays.
+     *
+     * The element is scrolled into view first so it's visible in headed mode
+     * (important when users are watching the test run).
+     */
+    private scrollIntoViewAndClick;
+    /** Extract a string from a script evaluation result */
+    private extractStringResult;
+    /** Convert a BiDi RemoteValue back to a JS value */
+    private deserializeRemoteValue;
+}
+/**
+ * A lazy reference to an element. Does not locate the element until
+ * you interact with it or assert on it.
+ */
+declare class ElementHandle {
+    /** @internal */
+    readonly page: Page;
+    /** @internal */
+    readonly target: ElementTarget;
+    constructor(page: Page, target: ElementTarget);
+    /** Click this element */
+    click(options?: ClickOptions): Promise<void>;
+    /** Fill this element with text */
+    fill(value: string, options?: FillOptions): Promise<void>;
+    /** Get the visible text content of this element */
+    textContent(): Promise<string>;
+    /** Get an attribute value */
+    getAttribute(name: string): Promise<string | null>;
+    /** Check if the element is visible on the page */
+    isVisible(): Promise<boolean>;
+    /** Count matching elements */
+    count(): Promise<number>;
+    /** Get the visible inner text (like element.innerText, not textContent) */
+    innerText(): Promise<string>;
+    /** Get the innerHTML of this element */
+    innerHTML(): Promise<string>;
+    /** Get the current value of an input/textarea/select */
+    inputValue(): Promise<string>;
+    /** Check if the element is enabled (not disabled) */
+    isEnabled(): Promise<boolean>;
+    /** Check if a checkbox/radio is checked */
+    isChecked(): Promise<boolean>;
+    /** Get the bounding box of the element */
+    boundingBox(): Promise<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null>;
+    /** Take a screenshot of just this element */
+    screenshot(): Promise<Buffer>;
+    /** Double-click this element */
+    dblclick(options?: ClickOptions): Promise<void>;
+    /** Hover over this element */
+    hover(options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /** Type text into this element character by character */
+    type(text: string, options?: FillOptions): Promise<void>;
+    /** Focus this element */
+    focus(options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /** Remove focus from this element */
+    blur(options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /** @internal Locate the element with auto-wait */
+    locate(timeout?: number): Promise<LocatedElement>;
+    private getRef;
+}
+
+/**
+ * Browser represents a running browser instance.
+ * Use `Browser.launch()` to start one, or let the test() fixtures do it for you.
+ *
+ * ```ts
+ * const browser = await Browser.launch();
+ * const page = await browser.newPage();
+ * await page.goto('https://example.com');
+ * await browser.close();
+ * ```
+ */
+declare class Browser {
+    /** @internal */
+    readonly session: BiDiSession;
+    /** @internal */
+    private config;
+    /** @internal */
+    private pages;
+    private constructor();
+    /**
+     * Launch a new browser instance.
+     *
+     * ```ts
+     * const browser = await Browser.launch(); // Chrome, headless
+     * const browser = await Browser.launch({ browser: 'firefox', headless: false });
+     * ```
+     */
+    static launch(userConfig?: UserConfig): Promise<Browser>;
+    /**
+     * Connect to an already-running browser.
+     *
+     * ```ts
+     * const browser = await Browser.connect('ws://localhost:9222/session');
+     * ```
+     */
+    static connect(wsEndpoint: string, userConfig?: UserConfig): Promise<Browser>;
+    /**
+     * Create a new page (tab).
+     *
+     * ```ts
+     * const page = await browser.newPage();
+     * await page.goto('https://example.com');
+     * ```
+     */
+    newPage(): Promise<Page>;
+    /** Get all open pages. */
+    get openPages(): Page[];
+    /**
+     * Create an isolated browser context (like incognito).
+     * Returns a BrowserContext that can create its own pages.
+     */
+    newContext(): Promise<BrowserContext>;
+    /** Close the browser and clean up all resources. */
+    close(): Promise<void>;
+    /** Whether the browser is still connected */
+    get isConnected(): boolean;
+    /** Get the resolved config */
+    getConfig(): BrowsecraftConfig;
+}
+/**
+ * An isolated browser context. Pages created in different contexts
+ * don't share cookies, storage, or cache.
+ */
+declare class BrowserContext {
+    /** @internal */
+    private session;
+    /** @internal */
+    private config;
+    /** @internal */
+    private userContext;
+    /** @internal */
+    private pages;
+    constructor(session: BiDiSession, config: BrowsecraftConfig, userContext: string | null);
+    /** Create a new page in this context. */
+    newPage(): Promise<Page>;
+    /** Close this context and all its pages. */
+    close(): Promise<void>;
+}
+
+/** Fixtures available in every test */
+interface TestFixtures {
+    /** A fresh page in a new browser context. Auto-closed after the test. */
+    page: Page;
+    /** The browser context for this test. */
+    context: BrowserContext;
+    /** The browser instance (shared across tests in a worker). */
+    browser: Browser;
+}
+/** A single test case, registered by test() */
+interface TestCase {
+    /** Test title */
+    title: string;
+    /** The test function */
+    fn: (fixtures: TestFixtures) => Promise<void>;
+    /** Test options */
+    options: TestOptions;
+    /** File this test was defined in */
+    file?: string;
+    /** Suite/describe path (e.g., ['Login', 'form validation']) */
+    suitePath: string[];
+    /** Whether this test is skipped */
+    skip: boolean;
+    /** Whether only this test should run */
+    only: boolean;
+}
+/** Options for individual tests */
+interface TestOptions {
+    /** Override timeout for this specific test */
+    timeout?: number;
+    /** Number of retries for this specific test */
+    retries?: number;
+    /** Tags for filtering (e.g., ['smoke', 'regression']) */
+    tags?: string[];
+}
+/** Internal test registry -- the runner reads from here */
+declare const testRegistry: TestCase[];
+/**
+ * Define a browser test.
+ *
+ * ```ts
+ * import { test, expect } from 'browsecraft';
+ *
+ * test('user can log in', async ({ page }) => {
+ *   await page.goto('/login');
+ *   await page.fill('Email', 'user@test.com');
+ *   await page.fill('Password', 'secret');
+ *   await page.click('Sign In');
+ *   await expect(page).toHaveURL('/dashboard');
+ * });
+ * ```
+ */
+declare function test(title: string, fn: (fixtures: TestFixtures) => Promise<void>): void;
+declare function test(title: string, options: TestOptions, fn: (fixtures: TestFixtures) => Promise<void>): void;
+declare namespace test {
+    var skip: (title: string, fn: (fixtures: TestFixtures) => Promise<void>) => void;
+    var only: (title: string, fn: (fixtures: TestFixtures) => Promise<void>) => void;
+}
+/**
+ * Group related tests together.
+ *
+ * ```ts
+ * describe('Login', () => {
+ *   test('shows form', async ({ page }) => { ... });
+ *   test('validates email', async ({ page }) => { ... });
+ * });
+ * ```
+ */
+declare function describe(title: string, fn: () => void): void;
+declare namespace describe {
+    var skip: (title: string, fn: () => void) => void;
+    var only: (title: string, fn: () => void) => void;
+}
+/** Before/after hooks for a describe block */
+type HookFn = (fixtures: TestFixtures) => Promise<void>;
+/**
+ * Run before all tests in the current describe block.
+ */
+declare function beforeAll(fn: HookFn): void;
+/**
+ * Run after all tests in the current describe block.
+ */
+declare function afterAll(fn: HookFn): void;
+/**
+ * Run before each test in the current describe block.
+ */
+declare function beforeEach(fn: HookFn): void;
+/**
+ * Run after each test in the current describe block.
+ */
+declare function afterEach(fn: HookFn): void;
+/**
+ * Execute a single test case with proper fixture setup/teardown.
+ * This is called by the test runner.
+ */
+declare function runTest(testCase: TestCase, sharedBrowser?: Browser, userConfig?: UserConfig): Promise<TestResult>;
+/**
+ * Run afterAll hooks for the given suite path.
+ * Called by the runner after all tests in a suite have completed.
+ */
+declare function runAfterAllHooks(suitePath: string[], fixtures: TestFixtures): Promise<void>;
+/**
+ * Reset all hooks and registries (for test isolation between files).
+ */
+declare function resetTestState(): void;
+/** Result of running a single test */
+interface TestResult {
+    title: string;
+    suitePath: string[];
+    status: 'passed' | 'failed' | 'skipped';
+    duration: number;
+    error?: Error;
+    /** Path to screenshot file (if captured on failure) */
+    screenshotPath?: string;
+}
+
+/** Options shared by all assertion matchers */
+interface MatcherOptions {
+    /** Timeout in ms (default: 5000) */
+    timeout?: number;
+}
+/**
+ * Create assertions on Pages or ElementHandles.
+ * All matchers auto-retry until they pass or timeout.
+ *
+ * ```ts
+ * await expect(page).toHaveURL('/dashboard');
+ * await expect(page).toHaveTitle('My App');
+ * await expect(page.get('Welcome')).toBeVisible();
+ * await expect(page.get('Submit')).toHaveText('Submit Order');
+ * ```
+ */
+declare function expect(subject: Page): PageAssertions;
+declare function expect(subject: ElementHandle): ElementAssertions;
+/**
+ * Assertions for a Page. All matchers auto-retry.
+ */
+declare class PageAssertions {
+    private page;
+    private _not;
+    constructor(page: Page);
+    /** Negate the assertion */
+    get not(): PageAssertions;
+    /**
+     * Assert the page URL contains or matches the expected value.
+     *
+     * ```ts
+     * await expect(page).toHaveURL('/dashboard');
+     * await expect(page).toHaveURL(/dashboard/);
+     * ```
+     */
+    toHaveURL(expected: string | RegExp, options?: MatcherOptions): Promise<void>;
+    /**
+     * Assert the page title matches.
+     *
+     * ```ts
+     * await expect(page).toHaveTitle('Dashboard');
+     * await expect(page).toHaveTitle(/Dashboard/);
+     * ```
+     */
+    toHaveTitle(expected: string | RegExp, options?: MatcherOptions): Promise<void>;
+    /**
+     * Assert the page content (HTML body text) contains the expected text.
+     *
+     * ```ts
+     * await expect(page).toHaveContent('Welcome back');
+     * await expect(page).toHaveContent(/logged in as \w+/);
+     * ```
+     */
+    toHaveContent(expected: string | RegExp, options?: MatcherOptions): Promise<void>;
+}
+/**
+ * Assertions for an ElementHandle. All matchers auto-retry.
+ */
+declare class ElementAssertions {
+    private element;
+    private _not;
+    constructor(element: ElementHandle);
+    /** Negate the assertion */
+    get not(): ElementAssertions;
+    /**
+     * Assert the element is visible on the page.
+     *
+     * ```ts
+     * await expect(page.get('Welcome')).toBeVisible();
+     * await expect(page.get('Error')).not.toBeVisible();
+     * ```
+     */
+    toBeVisible(options?: MatcherOptions): Promise<void>;
+    /**
+     * Assert the element is hidden (not visible).
+     *
+     * ```ts
+     * await expect(page.get('Loading')).toBeHidden();
+     * ```
+     */
+    toBeHidden(options?: MatcherOptions): Promise<void>;
+    /**
+     * Assert the element's text content matches exactly.
+     *
+     * ```ts
+     * await expect(page.get('h1')).toHaveText('Welcome');
+     * await expect(page.get('.count')).toHaveText(/\d+ items/);
+     * ```
+     */
+    toHaveText(expected: string | RegExp, options?: MatcherOptions): Promise<void>;
+    /**
+     * Assert the element's text content contains the expected substring.
+     *
+     * ```ts
+     * await expect(page.get('.message')).toContainText('success');
+     * ```
+     */
+    toContainText(expected: string | RegExp, options?: MatcherOptions): Promise<void>;
+    /**
+     * Assert the number of matching elements.
+     *
+     * ```ts
+     * await expect(page.get('li')).toHaveCount(5);
+     * ```
+     */
+    toHaveCount(expected: number, options?: MatcherOptions): Promise<void>;
+    /**
+     * Assert the element has a specific attribute value.
+     *
+     * ```ts
+     * await expect(page.get('input')).toHaveAttribute('type', 'email');
+     * await expect(page.get('a')).toHaveAttribute('href', /login/);
+     * ```
+     */
+    toHaveAttribute(name: string, expected?: string | RegExp, options?: MatcherOptions): Promise<void>;
+    /**
+     * Assert an input/textarea/select has a specific value.
+     *
+     * ```ts
+     * await expect(page.get('Email')).toHaveValue('user@test.com');
+     * ```
+     */
+    toHaveValue(expected: string | RegExp, options?: MatcherOptions): Promise<void>;
+    /**
+     * Assert a checkbox/radio is checked.
+     *
+     * ```ts
+     * await expect(page.get('Terms')).toBeChecked();
+     * await expect(page.get('Newsletter')).not.toBeChecked();
+     * ```
+     */
+    toBeChecked(options?: MatcherOptions): Promise<void>;
+    /**
+     * Assert an element is enabled (not disabled).
+     *
+     * ```ts
+     * await expect(page.get('Submit')).toBeEnabled();
+     * ```
+     */
+    toBeEnabled(options?: MatcherOptions): Promise<void>;
+    /**
+     * Assert an element is disabled.
+     *
+     * ```ts
+     * await expect(page.get('Submit')).toBeDisabled();
+     * ```
+     */
+    toBeDisabled(options?: MatcherOptions): Promise<void>;
+    /**
+     * Assert an element has a specific CSS class.
+     *
+     * ```ts
+     * await expect(page.get('.alert')).toHaveClass('alert-success');
+     * ```
+     */
+    toHaveClass(expected: string | RegExp, options?: MatcherOptions): Promise<void>;
+    /**
+     * Assert an element has a specific CSS property value.
+     *
+     * ```ts
+     * await expect(page.get('.banner')).toHaveCSS('color', 'rgb(255, 0, 0)');
+     * await expect(page.get('.box')).toHaveCSS('display', 'flex');
+     * ```
+     */
+    toHaveCSS(property: string, expected: string | RegExp, options?: MatcherOptions): Promise<void>;
+    /**
+     * Assert an element has a specific id attribute.
+     *
+     * ```ts
+     * await expect(page.get('Submit')).toHaveId('submit-btn');
+     * ```
+     */
+    toHaveId(expected: string, options?: MatcherOptions): Promise<void>;
+    /**
+     * Assert an element has a specific placeholder text.
+     *
+     * ```ts
+     * await expect(page.get({ selector: '#email' })).toHavePlaceholder('Enter your email');
+     * ```
+     */
+    toHavePlaceholder(expected: string | RegExp, options?: MatcherOptions): Promise<void>;
+    /**
+     * Assert an element has a specific ARIA role.
+     *
+     * ```ts
+     * await expect(page.get('Submit')).toHaveRole('button');
+     * ```
+     */
+    toHaveRole(expected: string, options?: MatcherOptions): Promise<void>;
+}
+/**
+ * Error thrown when an assertion fails.
+ */
+declare class AssertionError extends Error {
+    readonly name = "AssertionError";
+    constructor(message: string);
+}
+
+export { type AIConfig, AssertionError, type BrowsecraftConfig, Browser, BrowserContext, type ClickOptions, ElementHandle, type ElementTarget, type FillOptions, type GotoOptions, type LocatorOptions, type MockResponse, Page, type TestCase, type TestFixtures, type TestOptions, type TestResult, type UserConfig, afterAll, afterEach, beforeAll, beforeEach, defineConfig, describe, expect, resetTestState, resolveConfig, runAfterAllHooks, runTest, test, testRegistry };