@supernal/interface 1.0.9 → 1.0.12

package/dist/esm/src/testing/graph-tester/core/types.d.ts

@@ -0,0 +1,331 @@
+/**
+ * Core types for the graph-based testing framework.
+ *
+ * This file is the contract between all packages - changes require consensus.
+ *
+ * @packageDocumentation
+ */
+import type { Page } from '@playwright/test';
+/**
+ * Context provided to test functions during execution.
+ * Contains route information and optional metadata.
+ */
+export interface TestContext {
+    /** The route being tested (e.g., '/', '/dashboard', '/blog/:slug') */
+    route: string;
+    /** Unique identifier for this navigation context (enterprise only) */
+    contextId?: string;
+    /** Additional metadata about the route (tools, parent/child, custom data) */
+    metadata?: RouteMetadata;
+    /** Base URL for the application under test */
+    baseUrl?: string;
+    /** Current viewport being tested (for responsive testing) */
+    viewport?: ViewportConfig;
+}
+/**
+ * Metadata associated with a route.
+ * Enterprise users get richer metadata via NavigationGraph.
+ */
+export interface RouteMetadata {
+    /** Human-readable name for the route */
+    name?: string;
+    /** Tools available on this route (enterprise only) */
+    tools?: string[];
+    /** Parent route in navigation hierarchy (enterprise only) */
+    parent?: string;
+    /** Child routes (enterprise only) */
+    children?: string[];
+    /** Navigation paths to other routes (enterprise only) */
+    navigationPaths?: NavigationPath[];
+    /** Custom user-defined metadata */
+    [key: string]: any;
+}
+/**
+ * Navigation path between routes (enterprise only).
+ */
+export interface NavigationPath {
+    /** Target route */
+    target: string;
+    /** Navigation method (link, button, programmatic) */
+    method: 'link' | 'button' | 'programmatic' | 'other';
+    /** Element selector that triggers navigation (if applicable) */
+    selector?: string;
+}
+/**
+ * Result of a test function execution.
+ */
+export interface TestResult {
+    /** Whether the test passed */
+    passed: boolean;
+    /** Duration in milliseconds */
+    duration: number;
+    /** Errors encountered during testing */
+    errors: TestError[];
+    /** Additional test-specific metadata (screenshots, metrics, violations, etc.) */
+    metadata: Record<string, any>;
+    /** Test mode that produced this result */
+    mode?: TestMode;
+    /** Route that was tested */
+    route?: string;
+}
+/**
+ * Error encountered during testing.
+ */
+export interface TestError {
+    /** Error severity */
+    severity: 'critical' | 'warning' | 'info';
+    /** Error message */
+    message: string;
+    /** Location where error occurred (file:line, selector, etc.) */
+    location?: string;
+    /** Stack trace (if available) */
+    stack?: string;
+    /** Additional error context */
+    context?: Record<string, any>;
+}
+/**
+ * Descriptor for a route to be tested.
+ * Open-source users provide these manually.
+ * Enterprise users get these automatically via NavigationGraph.
+ */
+export interface RouteDescriptor {
+    /** The route path */
+    route: string;
+    /** Unique identifier (enterprise only) */
+    contextId?: string;
+    /** Route metadata */
+    metadata?: RouteMetadata;
+}
+/**
+ * Configuration for route discovery.
+ */
+export interface RouteDiscoveryConfig {
+    /** Discovery strategy ('manual', 'navigation-graph', 'custom') */
+    strategy: 'manual' | 'navigation-graph' | 'custom';
+    /** Routes to include (glob patterns) */
+    include?: string[];
+    /** Routes to exclude (glob patterns) */
+    exclude?: string[];
+    /** Custom discovery function */
+    discoveryFn?: () => Promise<RouteDescriptor[]>;
+}
+/**
+ * Available test modes.
+ */
+export type TestMode = 'visual' | 'performance' | 'accessibility' | 'seo' | string;
+/**
+ * Configuration for a test mode.
+ */
+export interface TestModeConfig {
+    /** Mode identifier */
+    mode: TestMode;
+    /** Whether this mode is enabled */
+    enabled?: boolean;
+    /** Mode-specific options */
+    options?: Record<string, any>;
+}
+/**
+ * Configuration for GraphTester.
+ */
+export interface GraphTesterConfig {
+    /** Base URL for the application under test */
+    baseUrl: string;
+    /** Routes to test (manual mode) or discovery config */
+    routes?: RouteDescriptor[] | RouteDiscoveryConfig;
+    /** Test modes to run */
+    modes: TestMode[] | TestModeConfig[];
+    /** Output configuration */
+    output?: OutputConfig;
+    /** Execution configuration */
+    execution?: ExecutionConfig;
+    /** Browser configuration */
+    browser?: BrowserConfig;
+}
+/**
+ * Output configuration.
+ */
+export interface OutputConfig {
+    /** Output directory */
+    dir: string;
+    /** Output formats ('json', 'html', 'markdown', 'csv') */
+    formats?: ('json' | 'html' | 'markdown' | 'csv')[];
+    /** Whether to include screenshots */
+    includeScreenshots?: boolean;
+    /** Whether to include detailed logs */
+    includeDetailedLogs?: boolean;
+}
+/**
+ * Execution configuration.
+ */
+export interface ExecutionConfig {
+    /** Number of parallel workers */
+    parallel?: number;
+    /** Timeout per test (ms) */
+    timeout?: number;
+    /** Number of retries on failure */
+    retries?: number;
+    /** Whether to fail fast on first error */
+    failFast?: boolean;
+}
+/**
+ * Viewport configuration for responsive testing.
+ */
+export interface ViewportConfig {
+    /** Viewport name (e.g., 'desktop', 'tablet', 'mobile') */
+    name: string;
+    /** Width in pixels */
+    width: number;
+    /** Height in pixels */
+    height: number;
+    /** Device scale factor (default: 1) */
+    deviceScaleFactor?: number;
+    /** Whether this is a mobile device (default: false) */
+    isMobile?: boolean;
+    /** Whether device has touch support (default: false) */
+    hasTouch?: boolean;
+    /** User agent override */
+    userAgent?: string;
+}
+/**
+ * Predefined viewport presets.
+ */
+export declare const ViewportPresets: {
+    readonly Desktop: {
+        readonly name: "desktop";
+        readonly width: 1920;
+        readonly height: 1080;
+    };
+    readonly DesktopSmall: {
+        readonly name: "desktop-small";
+        readonly width: 1366;
+        readonly height: 768;
+    };
+    readonly Laptop: {
+        readonly name: "laptop";
+        readonly width: 1280;
+        readonly height: 720;
+    };
+    readonly TabletLandscape: {
+        readonly name: "tablet-landscape";
+        readonly width: 1024;
+        readonly height: 768;
+        readonly isMobile: true;
+        readonly hasTouch: true;
+    };
+    readonly TabletPortrait: {
+        readonly name: "tablet-portrait";
+        readonly width: 768;
+        readonly height: 1024;
+        readonly isMobile: true;
+        readonly hasTouch: true;
+    };
+    readonly MobileLarge: {
+        readonly name: "mobile-large";
+        readonly width: 414;
+        readonly height: 896;
+        readonly isMobile: true;
+        readonly hasTouch: true;
+    };
+    readonly Mobile: {
+        readonly name: "mobile";
+        readonly width: 375;
+        readonly height: 812;
+        readonly isMobile: true;
+        readonly hasTouch: true;
+    };
+    readonly MobileSmall: {
+        readonly name: "mobile-small";
+        readonly width: 320;
+        readonly height: 568;
+        readonly isMobile: true;
+        readonly hasTouch: true;
+    };
+};
+/**
+ * Browser configuration.
+ */
+export interface BrowserConfig {
+    /** Browser type ('chromium', 'firefox', 'webkit') */
+    browserType?: 'chromium' | 'firefox' | 'webkit';
+    /** Single viewport size (legacy - use viewports for responsive testing) */
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /** Multiple viewports for responsive testing */
+    viewports?: ViewportConfig[];
+    /** Whether to run headless */
+    headless?: boolean;
+    /** Additional launch options */
+    launchOptions?: Record<string, any>;
+}
+/**
+ * Aggregated results from all test executions.
+ */
+export interface AggregatedTestResults {
+    /** Total number of routes tested */
+    routeCount: number;
+    /** Total number of tests run */
+    testCount: number;
+    /** Number of passed tests */
+    passedCount: number;
+    /** Number of failed tests */
+    failedCount: number;
+    /** Pass rate percentage */
+    passRate: number;
+    /** Total duration (ms) */
+    totalDuration: number;
+    /** Results grouped by route */
+    resultsByRoute: Map<string, TestResult[]>;
+    /** Results grouped by mode */
+    resultsByMode: Map<TestMode, TestResult[]>;
+    /** All errors */
+    errors: TestError[];
+    /** Timestamp */
+    timestamp: Date;
+    /** Configuration used */
+    config: GraphTesterConfig;
+}
+/**
+ * Reporter interface.
+ */
+export interface Reporter {
+    /** Generate report from aggregated results */
+    generate(results: AggregatedTestResults): Promise<void>;
+    /** Reporter name */
+    name: string;
+}
+/**
+ * Report format options.
+ */
+export type ReportFormat = 'json' | 'html' | 'markdown' | 'csv';
+/**
+ * Test function execution options.
+ */
+export interface ExecuteOptions {
+    /** Playwright page instance */
+    page: Page;
+    /** Test context */
+    context: TestContext;
+    /** Timeout (ms) */
+    timeout?: number;
+}
+/**
+ * Test function setup options.
+ */
+export interface SetupOptions {
+    /** Playwright page instance */
+    page: Page;
+    /** Test context */
+    context?: TestContext;
+}
+/**
+ * Test function teardown options.
+ */
+export interface TeardownOptions {
+    /** Playwright page instance */
+    page: Page;
+    /** Test context */
+    context?: TestContext;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/src/testing/graph-tester/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../src/testing/graph-tester/core/types.ts"],"names":[],"mappings":"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"}

package/dist/esm/src/testing/graph-tester/core/types.js

@@ -0,0 +1,21 @@
+/**
+ * Core types for the graph-based testing framework.
+ *
+ * This file is the contract between all packages - changes require consensus.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Predefined viewport presets.
+ */
+export const ViewportPresets = {
+    Desktop: { name: 'desktop', width: 1920, height: 1080 },
+    DesktopSmall: { name: 'desktop-small', width: 1366, height: 768 },
+    Laptop: { name: 'laptop', width: 1280, height: 720 },
+    TabletLandscape: { name: 'tablet-landscape', width: 1024, height: 768, isMobile: true, hasTouch: true },
+    TabletPortrait: { name: 'tablet-portrait', width: 768, height: 1024, isMobile: true, hasTouch: true },
+    MobileLarge: { name: 'mobile-large', width: 414, height: 896, isMobile: true, hasTouch: true },
+    Mobile: { name: 'mobile', width: 375, height: 812, isMobile: true, hasTouch: true },
+    MobileSmall: { name: 'mobile-small', width: 320, height: 568, isMobile: true, hasTouch: true },
+};
+//# sourceMappingURL=types.js.map

package/dist/esm/src/testing/graph-tester/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../../src/testing/graph-tester/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAyPH;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;IACvD,YAAY,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;IACjE,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;IACpD,eAAe,EAAE,EAAE,IAAI,EAAE,kBAAkB,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;IACvG,cAAc,EAAE,EAAE,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;IACrG,WAAW,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;IAC9F,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;IACnF,WAAW,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;CACtF,CAAC"}

package/dist/esm/src/testing/graph-tester/fixtures/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Fixtures exports.
+ *
+ * @packageDocumentation
+ */
+export { test, expect, cleanupPortPool } from './portPool';
+export type { PortPoolFixture } from './portPool';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/src/testing/graph-tester/fixtures/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/testing/graph-tester/fixtures/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC3D,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/dist/esm/src/testing/graph-tester/fixtures/index.js

@@ -0,0 +1,7 @@
+/**
+ * Fixtures exports.
+ *
+ * @packageDocumentation
+ */
+export { test, expect, cleanupPortPool } from './portPool.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/src/testing/graph-tester/fixtures/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../src/testing/graph-tester/fixtures/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/dist/esm/src/testing/graph-tester/fixtures/portPool.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Port pool fixture for parallel testing.
+ *
+ * Automatically assigns unique ports to each test worker to avoid conflicts.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Port pool fixture interface.
+ */
+export interface PortPoolFixture {
+    /** Assigned port for this test */
+    port: number;
+    /** Base URL with assigned port */
+    baseURL: string;
+}
+/**
+ * Playwright test fixture with automatic port assignment.
+ *
+ * @example
+ * ```typescript
+ * import { test, expect } from '@supernal/interface/testing/graph-tester/fixtures';
+ *
+ * test('visual regression', async ({ page, port, baseURL }) => {
+ *   console.log(`Test running on port ${port}`);
+ *   await page.goto(baseURL);
+ *   // Test automatically gets unique port!
+ * });
+ * ```
+ */
+export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & PortPoolFixture, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
+/**
+ * Re-export expect from Playwright.
+ */
+export declare const expect: import("@playwright/test").Expect<{}>;
+/**
+ * Cleanup port pool (call at end of test suite).
+ */
+export declare function cleanupPortPool(): Promise<void>;
+//# sourceMappingURL=portPool.d.ts.map

package/dist/esm/src/testing/graph-tester/fixtures/portPool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portPool.d.ts","sourceRoot":"","sources":["../../../../../../src/testing/graph-tester/fixtures/portPool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IAEb,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;CACjB;AA2GD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,IAAI,+PAUf,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,MAAM,uCAAa,CAAC;AAEjC;;GAEG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAErD"}

package/dist/esm/src/testing/graph-tester/fixtures/portPool.js

@@ -0,0 +1,147 @@
+/**
+ * Port pool fixture for parallel testing.
+ *
+ * Automatically assigns unique ports to each test worker to avoid conflicts.
+ *
+ * @packageDocumentation
+ */
+import { test as base, expect as baseExpect } from '@playwright/test';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+/**
+ * Port pool manager (singleton across workers).
+ */
+class PortPoolManager {
+    constructor(startPort = 3020, poolSize = 10) {
+        this.availablePorts = [];
+        this.usedPorts = new Set();
+        this.lockFile = path.join(os.tmpdir(), 'supernal-port-pool.lock');
+        this.lockFd = null;
+        // Initialize pool: 3020-3029 by default
+        for (let i = 0; i < poolSize; i++) {
+            this.availablePorts.push(startPort + i);
+        }
+    }
+    /**
+     * Acquire a port from the pool (with cross-worker coordination).
+     */
+    async acquirePort() {
+        await this.acquireLock();
+        try {
+            if (this.availablePorts.length === 0) {
+                throw new Error('No available ports in pool. Increase pool size or reduce parallel workers.');
+            }
+            const port = this.availablePorts.shift();
+            this.usedPorts.add(port);
+            return port;
+        }
+        finally {
+            await this.releaseLock();
+        }
+    }
+    /**
+     * Release a port back to the pool.
+     */
+    async releasePort(port) {
+        await this.acquireLock();
+        try {
+            if (this.usedPorts.has(port)) {
+                this.usedPorts.delete(port);
+                this.availablePorts.push(port);
+            }
+        }
+        finally {
+            await this.releaseLock();
+        }
+    }
+    /**
+     * Acquire file-based lock for cross-worker coordination.
+     */
+    async acquireLock() {
+        const maxRetries = 100;
+        const retryDelay = 50; // ms
+        for (let i = 0; i < maxRetries; i++) {
+            try {
+                // Try to create lock file with exclusive flag
+                this.lockFd = fs.openSync(this.lockFile, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_RDWR);
+                return; // Lock acquired
+            }
+            catch (error) {
+                if (error.code === 'EEXIST') {
+                    // Lock file exists, wait and retry
+                    await new Promise((resolve) => setTimeout(resolve, retryDelay));
+                }
+                else {
+                    throw error;
+                }
+            }
+        }
+        throw new Error('Failed to acquire port pool lock after retries');
+    }
+    /**
+     * Release file-based lock.
+     */
+    async releaseLock() {
+        if (this.lockFd !== null) {
+            try {
+                fs.closeSync(this.lockFd);
+                fs.unlinkSync(this.lockFile);
+            }
+            catch (error) {
+                // Ignore errors (file might already be deleted)
+            }
+            this.lockFd = null;
+        }
+    }
+    /**
+     * Cleanup all resources.
+     */
+    async cleanup() {
+        try {
+            if (fs.existsSync(this.lockFile)) {
+                fs.unlinkSync(this.lockFile);
+            }
+        }
+        catch {
+            // Ignore
+        }
+    }
+}
+// Global port pool instance
+const portPool = new PortPoolManager();
+/**
+ * Playwright test fixture with automatic port assignment.
+ *
+ * @example
+ * ```typescript
+ * import { test, expect } from '@supernal/interface/testing/graph-tester/fixtures';
+ *
+ * test('visual regression', async ({ page, port, baseURL }) => {
+ *   console.log(`Test running on port ${port}`);
+ *   await page.goto(baseURL);
+ *   // Test automatically gets unique port!
+ * });
+ * ```
+ */
+export const test = base.extend({
+    port: async ({}, use) => {
+        const port = await portPool.acquirePort();
+        await use(port);
+        await portPool.releasePort(port);
+    },
+    baseURL: async ({ port }, use) => {
+        await use(`http://localhost:${port}`);
+    },
+});
+/**
+ * Re-export expect from Playwright.
+ */
+export const expect = baseExpect;
+/**
+ * Cleanup port pool (call at end of test suite).
+ */
+export async function cleanupPortPool() {
+    await portPool.cleanup();
+}
+//# sourceMappingURL=portPool.js.map

package/dist/esm/src/testing/graph-tester/fixtures/portPool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"portPool.js","sourceRoot":"","sources":["../../../../../../src/testing/graph-tester/fixtures/portPool.ts"],"names":[],"mappings":"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"}

package/dist/esm/src/testing/graph-tester/index.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Graph-Based Testing Framework
+ *
+ * A comprehensive testing framework that systematically applies different testing functions
+ * (visual regression, performance, accessibility, SEO) to all routes in your application.
+ *
+ * ## Features
+ *
+ * - **Screenshot Annotation**: Capture screenshots with element bounding boxes, testids, and interaction capabilities
+ * - **Multiple Test Modes**: Visual regression, performance, accessibility, SEO
+ * - **AI-Ready Output**: JSON + PNG format optimized for multimodal AI analysis
+ * - **Multi-Format Reporting**: HTML (interactive), JSON (CI/CD), Markdown (docs)
+ * - **Parallel Testing**: Port pool fixture for running tests in parallel
+ * - **Pluggable Architecture**: Create custom test modes by extending TestFunction
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { GraphTester, VisualRegressionMode, JSONReporter } from '@supernal/interface/testing/graph-tester';
+ *
+ * const tester = new GraphTester({
+ *   baseUrl: 'http://localhost:3000',
+ *   routes: [
+ *     { route: '/', metadata: { name: 'Home' } },
+ *     { route: '/dashboard', metadata: { name: 'Dashboard' } }
+ *   ],
+ *   modes: ['visual'],
+ *   output: {
+ *     dir: './test-results',
+ *     formats: ['json', 'html']
+ *   }
+ * });
+ *
+ * // Register test modes
+ * tester.registerTestFunction(new VisualRegressionMode({
+ *   outputDir: './screenshots',
+ *   annotate: true,
+ *   generateHTML: true
+ * }));
+ *
+ * // Run tests
+ * const results = await tester.runTests();
+ * console.log(`Pass rate: ${results.passRate}%`);
+ *
+ * // Generate reports
+ * const reporter = new JSONReporter({ outputDir: './test-results' });
+ * await reporter.generate(results);
+ * ```
+ *
+ * ## Enterprise Features
+ *
+ * For automatic route discovery via NavigationGraph, CLI commands, and AI analysis,
+ * see `@supernalintelligence/interface-enterprise/testing/graph-tester`.
+ *
+ * @packageDocumentation
+ */
+export { TestFunction, isTestFunction } from './core/TestFunction';
+export { GraphTester } from './core/GraphTester';
+export type * from './core/types';
+export { ViewportPresets } from './core/types';
+export { ScreenshotAnnotator } from './screenshot/ScreenshotAnnotator';
+export type { ScreenshotAnnotatorConfig } from './screenshot/ScreenshotAnnotator';
+export { HTMLAnnotationRenderer } from './screenshot/HTMLAnnotationRenderer';
+export { CanvasAnnotationRenderer } from './screenshot/CanvasAnnotationRenderer';
+export type * from './screenshot/types';
+export { VisualRegressionMode } from './modes/VisualRegressionMode';
+export type { VisualRegressionConfig } from './modes/VisualRegressionMode';
+export { PerformanceMode } from './modes/PerformanceMode';
+export type { PerformanceConfig } from './modes/PerformanceMode';
+export { AccessibilityMode } from './modes/AccessibilityMode';
+export type { AccessibilityConfig } from './modes/AccessibilityMode';
+export { SEOMode } from './modes/SEOMode';
+export type { SEOConfig } from './modes/SEOMode';
+export { UnifiedReporter } from './reporters/UnifiedReporter';
+export type { UnifiedReporterConfig } from './reporters/UnifiedReporter';
+export { JSONReporter } from './reporters/JSONReporter';
+export type { JSONReporterConfig } from './reporters/JSONReporter';
+export { HTMLReporter } from './reporters/HTMLReporter';
+export type { HTMLReporterConfig } from './reporters/HTMLReporter';
+export { MarkdownReporter } from './reporters/MarkdownReporter';
+export type { MarkdownReporterConfig } from './reporters/MarkdownReporter';
+export { test as testWithPortPool, expect, cleanupPortPool } from './fixtures/portPool';
+export type { PortPoolFixture } from './fixtures/portPool';
+//# sourceMappingURL=index.d.ts.map