@esimplicity/stack-tests 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,540 @@
+import * as playwright_bdd from 'playwright-bdd';
+export { test as baseTest } from 'playwright-bdd';
+import * as _playwright_test from '@playwright/test';
+import { APIResponse, PlaywrightTestArgs, PlaywrightWorkerArgs, APIRequestContext, Page } from '@playwright/test';
+export { registerApiAssertionSteps, registerApiAuthSteps, registerApiHttpSteps, registerApiSteps, registerHybridSteps, registerHybridSuite, registerSharedCleanupSteps, registerSharedSteps, registerSharedVarSteps, registerTuiBasicSteps, registerTuiSteps, registerTuiWizardSteps, registerUiBasicSteps, registerUiSteps, registerWizardSteps } from './steps/index.js';
+
+type CleanupItem = {
+    method: 'DELETE' | 'POST' | 'PATCH' | 'PUT';
+    path: string;
+    headers?: Record<string, string>;
+};
+type World = {
+    vars: Record<string, string>;
+    headers: Record<string, string>;
+    cleanup: CleanupItem[];
+    skipCleanup?: boolean;
+    lastResponse?: APIResponse;
+    lastStatus?: number;
+    lastText?: string;
+    lastJson?: unknown;
+    lastHeaders?: Record<string, string>;
+    lastContentType?: string;
+};
+declare function initWorld(): World;
+
+type ApiResult = {
+    status: number;
+    text: string;
+    json?: unknown;
+    headers: Record<string, string>;
+    contentType?: string;
+    response: APIResponse;
+};
+type ApiMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+interface ApiPort {
+    sendJson(method: ApiMethod, path: string, body?: unknown, headers?: Record<string, string>): Promise<ApiResult>;
+    sendForm(method: 'POST' | 'PUT' | 'PATCH', path: string, form: Record<string, string>, headers?: Record<string, string>): Promise<ApiResult>;
+}
+
+type UiClickMode = 'click' | 'dispatch click' | 'force click' | 'force dispatch click';
+type UiInputMode = 'type' | 'fill' | 'choose';
+type UiUrlAssertMode = 'contains' | 'doesntContain' | 'equals';
+type UiLocatorMethod = 'text' | 'label' | 'placeholder' | 'role' | 'test ID' | 'alternative text' | 'title' | 'locator';
+type UiElementState = 'visible' | 'hidden' | 'editable' | 'disabled' | 'enabled' | 'read-only';
+interface UiPort {
+    goto(path: string): Promise<void>;
+    clickButton(name: string): Promise<void>;
+    clickLink(name: string): Promise<void>;
+    fillPlaceholder(placeholder: string, value: string): Promise<void>;
+    fillLabel(label: string, value: string): Promise<void>;
+    expectText(text: string): Promise<void>;
+    expectUrlContains(part: string): Promise<void>;
+    goBack(): Promise<void>;
+    reload(): Promise<void>;
+    waitSeconds(seconds: number): Promise<void>;
+    waitForPageLoad(): Promise<void>;
+    getCurrentUrl(): Promise<string>;
+    zoomTo(scale: number): Promise<void>;
+    typeText(text: string): Promise<void>;
+    pressKey(key: string): Promise<void>;
+    clickElementThatContains(clickMode: UiClickMode, elementType: string, text: string): Promise<void>;
+    clickElementWith(clickMode: UiClickMode, ordinal: string, text: string, method: UiLocatorMethod): Promise<void>;
+    fillDropdown(value: string, dropdownLabel: string): Promise<void>;
+    inputInElement(action: UiInputMode, value: string, ordinal: string, text: string, method: UiLocatorMethod): Promise<void>;
+    expectUrl(mode: UiUrlAssertMode, expected: string): Promise<void>;
+    expectNewTabUrl(mode: UiUrlAssertMode, expected: string): Promise<void>;
+    expectElementWithTextVisible(elementType: string, text: string, shouldBeVisible: boolean): Promise<void>;
+    expectElementState(ordinal: string, text: string, method: UiLocatorMethod, state: UiElementState): Promise<void>;
+    expectElementStateWithin(ordinal: string, text: string, method: UiLocatorMethod, state: UiElementState, seconds: number): Promise<void>;
+}
+
+interface AuthPort {
+    apiLoginAsAdmin(world: World): Promise<void>;
+    apiLoginAsUser(world: World): Promise<void>;
+    apiSetBearer(world: World, token: string): void;
+    uiLoginAsAdmin(world: World): Promise<void>;
+    uiLoginAsUser(world: World): Promise<void>;
+}
+
+interface CleanupPort {
+    registerFromVar(world: World, varName: string, id: unknown, meta?: unknown): void;
+}
+
+/**
+ * TUI Port Interface
+ *
+ * Defines the contract for terminal user interface testing operations.
+ * Aligned with UiPort patterns for consistency across testing approaches.
+ */
+/** Keyboard modifier keys for key combinations */
+type TuiKeyModifiers = {
+    ctrl?: boolean;
+    alt?: boolean;
+    shift?: boolean;
+    meta?: boolean;
+};
+/** Options for wait operations */
+type TuiWaitOptions = {
+    /** Maximum time to wait in milliseconds */
+    timeout?: number;
+    /** Polling interval in milliseconds */
+    interval?: number;
+};
+/** Captured screen state */
+type TuiScreenCapture = {
+    /** Full screen text content */
+    text: string;
+    /** Screen content split by lines */
+    lines: string[];
+    /** Timestamp when capture was taken */
+    timestamp: number;
+    /** Terminal dimensions */
+    size: {
+        cols: number;
+        rows: number;
+    };
+};
+/** Result of snapshot comparison */
+type TuiSnapshotResult = {
+    /** Whether the snapshot matched */
+    pass: boolean;
+    /** Diff output if snapshot didn't match */
+    diff?: string;
+    /** Path to the snapshot file */
+    snapshotPath?: string;
+};
+/** Mouse button types */
+type TuiMouseButton = 'left' | 'right' | 'middle';
+/** Mouse event types */
+type TuiMouseEventType = 'click' | 'down' | 'up' | 'drag' | 'scroll';
+/** Mouse event configuration */
+type TuiMouseEvent = {
+    type: TuiMouseEventType;
+    position: {
+        x: number;
+        y: number;
+    };
+    button?: TuiMouseButton;
+};
+/** Configuration for TUI adapter initialization */
+type TuiConfig = {
+    /** Command to start the TUI application (e.g., ['node', 'cli.js']) */
+    command: string[];
+    /** Terminal size (defaults to 80x24) */
+    size?: {
+        cols: number;
+        rows: number;
+    };
+    /** Working directory for the command */
+    cwd?: string;
+    /** Environment variables */
+    env?: Record<string, string>;
+    /** Enable debug output */
+    debug?: boolean;
+    /** Directory for snapshot storage */
+    snapshotDir?: string;
+    /** Shell to use (defaults to system shell) */
+    shell?: string;
+};
+/**
+ * Port interface for terminal user interface testing.
+ *
+ * This interface follows the same patterns as UiPort to enable:
+ * - Consistent step definitions across UI and TUI tests
+ * - Easy mental model for test authors
+ * - Potential for shared/hybrid testing scenarios
+ */
+interface TuiPort {
+    /**
+     * Start the TUI application.
+     * Creates a new terminal session and launches the configured command.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the TUI application.
+     * Terminates the terminal session and cleans up resources.
+     */
+    stop(): Promise<void>;
+    /**
+     * Restart the TUI application.
+     * Equivalent to stop() followed by start().
+     */
+    restart(): Promise<void>;
+    /**
+     * Check if the TUI application is currently running.
+     */
+    isRunning(): boolean;
+    /**
+     * Type text into the terminal.
+     * Similar to UiPort.typeText - sends characters one by one.
+     * @param text - The text to type
+     * @param options - Optional typing options
+     */
+    typeText(text: string, options?: {
+        delay?: number;
+    }): Promise<void>;
+    /**
+     * Press a keyboard key, optionally with modifiers.
+     * Similar to UiPort.pressKey.
+     * @param key - Key name (e.g., 'enter', 'tab', 'up', 'down', 'f1')
+     * @param modifiers - Optional modifier keys
+     */
+    pressKey(key: string, modifiers?: TuiKeyModifiers): Promise<void>;
+    /**
+     * Send raw text without any interpretation.
+     * Useful for pasting content or sending special sequences.
+     * @param text - Raw text to send
+     */
+    sendText(text: string): Promise<void>;
+    /**
+     * Fill a labeled field in the TUI.
+     * Navigates to the field and enters the value.
+     * Similar to UiPort.fillLabel.
+     * @param fieldLabel - The label or identifier of the field
+     * @param value - The value to enter
+     */
+    fillField(fieldLabel: string, value: string): Promise<void>;
+    /**
+     * Select an option/menu item.
+     * Similar to UiPort.clickButton conceptually.
+     * @param option - The option text to select
+     */
+    selectOption(option: string): Promise<void>;
+    /**
+     * Send a mouse event to the terminal.
+     * Only works if the TUI application supports mouse input.
+     * @param event - Mouse event configuration
+     */
+    sendMouse(event: TuiMouseEvent): Promise<void>;
+    /**
+     * Click at a specific position.
+     * @param x - Column position (0-based)
+     * @param y - Row position (0-based)
+     * @param button - Mouse button (defaults to 'left')
+     */
+    click(x: number, y: number, button?: TuiMouseButton): Promise<void>;
+    /**
+     * Click on text content in the terminal.
+     * Finds the text and clicks on its position.
+     * @param text - The text to find and click
+     */
+    clickOnText(text: string): Promise<void>;
+    /**
+     * Assert that text is visible on the screen.
+     * Waits for the text to appear within timeout.
+     * Similar to UiPort.expectText.
+     * @param text - The expected text
+     * @param options - Wait options
+     */
+    expectText(text: string, options?: TuiWaitOptions): Promise<void>;
+    /**
+     * Assert that text matching a pattern is visible.
+     * @param pattern - Regular expression to match
+     * @param options - Wait options
+     */
+    expectPattern(pattern: RegExp, options?: TuiWaitOptions): Promise<void>;
+    /**
+     * Assert that text is NOT visible on the screen.
+     * @param text - The text that should not be present
+     */
+    expectNotText(text: string): Promise<void>;
+    /**
+     * Assert the screen contains specific text (immediate check, no wait).
+     * @param text - The expected text
+     */
+    assertScreenContains(text: string): Promise<void>;
+    /**
+     * Assert the screen matches a regular expression.
+     * @param pattern - Regular expression to match against screen content
+     */
+    assertScreenMatches(pattern: RegExp): Promise<void>;
+    /**
+     * Wait for text to appear on screen.
+     * @param text - Text to wait for
+     * @param options - Wait options
+     */
+    waitForText(text: string, options?: TuiWaitOptions): Promise<void>;
+    /**
+     * Wait for text matching pattern to appear.
+     * @param pattern - Regular expression to match
+     * @param options - Wait options
+     */
+    waitForPattern(pattern: RegExp, options?: TuiWaitOptions): Promise<void>;
+    /**
+     * Wait for the application to be ready.
+     * Implementation-specific (e.g., wait for prompt, initial screen).
+     */
+    waitForReady(): Promise<void>;
+    /**
+     * Wait for a specific duration.
+     * Similar to UiPort.waitSeconds.
+     * @param seconds - Duration to wait in seconds
+     */
+    waitSeconds(seconds: number): Promise<void>;
+    /**
+     * Capture the current screen state.
+     * @returns Screen capture with text content and metadata
+     */
+    captureScreen(): Promise<TuiScreenCapture>;
+    /**
+     * Get the current screen text content.
+     * @returns Plain text representation of the screen
+     */
+    getScreenText(): Promise<string>;
+    /**
+     * Get screen content as lines.
+     * @returns Array of screen lines
+     */
+    getScreenLines(): Promise<string[]>;
+    /**
+     * Take a snapshot of the current screen state.
+     * Saves to the configured snapshot directory.
+     * @param name - Snapshot identifier
+     */
+    takeSnapshot(name: string): Promise<void>;
+    /**
+     * Compare current screen against a saved snapshot.
+     * @param name - Snapshot identifier to compare against
+     * @returns Comparison result with pass/fail and diff
+     */
+    matchSnapshot(name: string): Promise<TuiSnapshotResult>;
+    /**
+     * Clear the terminal screen.
+     */
+    clear(): Promise<void>;
+    /**
+     * Resize the terminal.
+     * @param size - New dimensions
+     */
+    resize(size: {
+        cols: number;
+        rows: number;
+    }): Promise<void>;
+    /**
+     * Get the current terminal size.
+     */
+    getSize(): {
+        cols: number;
+        rows: number;
+    };
+    /**
+     * Get the current configuration.
+     */
+    getConfig(): TuiConfig;
+}
+
+type CreateContext = PlaywrightTestArgs & PlaywrightWorkerArgs & {
+    apiRequest: APIRequestContext;
+    page: Page;
+};
+/**
+ * Factory function type for creating a TUI adapter.
+ * Returns undefined if TUI testing is not configured.
+ */
+type TuiFactory = () => TuiPort | undefined;
+type CreateBddTestOptions = {
+    createApi?: (ctx: CreateContext) => ApiPort;
+    createUi?: (ctx: CreateContext) => UiPort;
+    createAuth?: (ctx: CreateContext & {
+        api: ApiPort;
+        ui: UiPort;
+    }) => AuthPort;
+    createCleanup?: (ctx: CreateContext) => CleanupPort;
+    /**
+     * Factory function for creating a TUI adapter.
+     * Unlike other adapters, this is a simple factory that doesn't receive context,
+     * as TUI testing operates independently of Playwright's browser context.
+     *
+     * @example
+     * ```typescript
+     * createTui: () => new TuiTesterAdapter({
+     *   command: ['node', 'dist/cli.js'],
+     *   size: { cols: 100, rows: 30 },
+     * }),
+     * ```
+     */
+    createTui?: TuiFactory;
+    worldFactory?: () => World;
+};
+declare function createBddTest(options?: CreateBddTestOptions): _playwright_test.TestType<PlaywrightTestArgs & _playwright_test.PlaywrightTestOptions & playwright_bdd.BddTestFixtures & {
+    world: World;
+    api: ApiPort;
+    ui: UiPort;
+    auth: AuthPort;
+    cleanup: CleanupPort;
+    tui: TuiPort | undefined;
+    apiRequest: APIRequestContext;
+}, PlaywrightWorkerArgs & _playwright_test.PlaywrightWorkerOptions & playwright_bdd.BddWorkerFixtures>;
+
+declare function interpolate(template: string, vars: Record<string, string>): string;
+declare function tryParseJson(text: string): unknown;
+declare function selectPath(root: unknown, path: string): unknown;
+declare function parseExpected(input: string, world: World): unknown;
+declare function assertMasked(val: unknown): void;
+declare function registerCleanup(world: World, item: {
+    method?: 'DELETE' | 'POST' | 'PATCH' | 'PUT';
+    path: string;
+}): void;
+
+declare class PlaywrightApiAdapter implements ApiPort {
+    private readonly request;
+    constructor(request: APIRequestContext);
+    sendJson(method: ApiMethod, path: string, body?: unknown, headers?: Record<string, string>): Promise<ApiResult>;
+    sendForm(method: 'POST' | 'PUT' | 'PATCH', path: string, form: Record<string, string>, headers?: Record<string, string>): Promise<ApiResult>;
+}
+
+declare class PlaywrightUiAdapter implements UiPort {
+    private readonly page;
+    constructor(page: Page);
+    goto(path: string): Promise<void>;
+    clickButton(name: string): Promise<void>;
+    clickLink(name: string): Promise<void>;
+    fillPlaceholder(placeholder: string, value: string): Promise<void>;
+    fillLabel(label: string, value: string): Promise<void>;
+    expectText(text: string): Promise<void>;
+    expectUrlContains(part: string): Promise<void>;
+    goBack(): Promise<void>;
+    reload(): Promise<void>;
+    waitSeconds(seconds: number): Promise<void>;
+    waitForPageLoad(): Promise<void>;
+    getCurrentUrl(): Promise<string>;
+    zoomTo(scale: number): Promise<void>;
+    typeText(text: string): Promise<void>;
+    pressKey(key: string): Promise<void>;
+    clickElementThatContains(clickMode: UiClickMode, elementType: string, text: string): Promise<void>;
+    clickElementWith(clickMode: UiClickMode, ordinal: string, text: string, method: UiLocatorMethod): Promise<void>;
+    fillDropdown(value: string, dropdownLabel: string): Promise<void>;
+    inputInElement(action: UiInputMode, value: string, ordinal: string, text: string, method: UiLocatorMethod): Promise<void>;
+    expectUrl(mode: UiUrlAssertMode, expected: string): Promise<void>;
+    expectNewTabUrl(mode: UiUrlAssertMode, expected: string): Promise<void>;
+    expectElementWithTextVisible(elementType: string, text: string, shouldBeVisible: boolean): Promise<void>;
+    expectElementState(ordinal: string, text: string, method: UiLocatorMethod, state: UiElementState): Promise<void>;
+    expectElementStateWithin(ordinal: string, text: string, method: UiLocatorMethod, state: UiElementState, seconds: number): Promise<void>;
+    private parseOrdinal;
+    private locatorBy;
+    private performClick;
+    private expectState;
+    private assertUrlAgainst;
+}
+
+declare class UniversalAuthAdapter implements AuthPort {
+    private readonly deps;
+    constructor(deps: {
+        api: ApiPort;
+        ui: UiPort;
+    });
+    apiSetBearer(world: World, token: string): void;
+    apiLoginAsAdmin(world: World): Promise<void>;
+    apiLoginAsUser(world: World): Promise<void>;
+    private apiLogin;
+    uiLoginAsAdmin(world: World): Promise<void>;
+    uiLoginAsUser(world: World): Promise<void>;
+    private uiLogin;
+}
+
+type CleanupRule = {
+    varMatch: string;
+    method?: 'DELETE' | 'POST' | 'PATCH' | 'PUT';
+    path: string;
+};
+declare class DefaultCleanupAdapter implements CleanupPort {
+    private readonly rules;
+    private readonly allowHeuristic;
+    constructor(input?: {
+        rules?: CleanupRule[];
+        allowHeuristic?: boolean;
+    });
+    registerFromVar(world: World, varName: string, id: unknown, meta?: unknown): void;
+}
+
+/**
+ * TUI Tester Adapter
+ *
+ * Implements TuiPort using the tui-tester library (https://github.com/luxquant/tui-tester).
+ * Provides end-to-end testing capabilities for terminal user interfaces via tmux.
+ */
+
+declare class TuiTesterAdapter implements TuiPort {
+    private tester;
+    private config;
+    private running;
+    private tuiTesterModule;
+    constructor(config: TuiConfig);
+    /**
+     * Lazily load the tui-tester module to support optional dependency
+     */
+    private loadTuiTester;
+    /**
+     * Get the tester instance, throwing if not started
+     */
+    private getTester;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    restart(): Promise<void>;
+    isRunning(): boolean;
+    typeText(text: string, options?: {
+        delay?: number;
+    }): Promise<void>;
+    pressKey(key: string, modifiers?: TuiKeyModifiers): Promise<void>;
+    sendText(text: string): Promise<void>;
+    fillField(fieldLabel: string, value: string): Promise<void>;
+    selectOption(option: string): Promise<void>;
+    sendMouse(event: TuiMouseEvent): Promise<void>;
+    click(x: number, y: number, button?: TuiMouseButton): Promise<void>;
+    clickOnText(text: string): Promise<void>;
+    expectText(text: string, options?: TuiWaitOptions): Promise<void>;
+    expectPattern(pattern: RegExp, options?: TuiWaitOptions): Promise<void>;
+    expectNotText(text: string): Promise<void>;
+    assertScreenContains(text: string): Promise<void>;
+    assertScreenMatches(pattern: RegExp): Promise<void>;
+    waitForText(text: string, options?: TuiWaitOptions): Promise<void>;
+    waitForPattern(pattern: RegExp, options?: TuiWaitOptions): Promise<void>;
+    waitForReady(): Promise<void>;
+    waitSeconds(seconds: number): Promise<void>;
+    captureScreen(): Promise<TuiScreenCapture>;
+    getScreenText(): Promise<string>;
+    getScreenLines(): Promise<string[]>;
+    takeSnapshot(name: string): Promise<void>;
+    matchSnapshot(name: string): Promise<TuiSnapshotResult>;
+    clear(): Promise<void>;
+    resize(size: {
+        cols: number;
+        rows: number;
+    }): Promise<void>;
+    getSize(): {
+        cols: number;
+        rows: number;
+    };
+    getConfig(): TuiConfig;
+}
+
+type TagsForProjectInput = {
+    projectTag: string;
+    extraTags?: string;
+    defaultExcludes?: string;
+};
+declare function tagsForProject({ projectTag, extraTags, defaultExcludes }: TagsForProjectInput): string;
+declare function resolveExtraTags(raw?: string | null): string | undefined;
+
+export { type ApiMethod, type ApiPort, type ApiResult, type AuthPort, type CleanupItem, type CleanupPort, type CleanupRule, type CreateBddTestOptions, DefaultCleanupAdapter, PlaywrightApiAdapter, PlaywrightUiAdapter, type TuiConfig, type TuiFactory, type TuiKeyModifiers, type TuiMouseButton, type TuiMouseEvent, type TuiMouseEventType, type TuiPort, type TuiScreenCapture, type TuiSnapshotResult, TuiTesterAdapter, type TuiWaitOptions, type UiClickMode, type UiElementState, type UiInputMode, type UiLocatorMethod, type UiPort, type UiUrlAssertMode, UniversalAuthAdapter, type World, assertMasked, createBddTest, initWorld, interpolate, parseExpected, registerCleanup, resolveExtraTags, selectPath, tagsForProject, tryParseJson };