@ochorocho/playwright-db-connector 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,313 @@
+import * as _playwright_test from '@playwright/test';
+import { Knex } from 'knex';
+
+/**
+ * Database client identifiers supported by the plugin.
+ */
+type DatabaseClient = 'pg' | 'mysql2' | 'better-sqlite3' | 'sqlite3';
+/**
+ * Connection configuration for server-based databases (PostgreSQL, MySQL, MariaDB).
+ */
+interface ServerConnectionConfig {
+    host: string;
+    port?: number;
+    user: string;
+    password: string;
+    database: string;
+    ssl?: boolean | Record<string, unknown>;
+}
+/**
+ * Connection configuration for SQLite databases.
+ */
+interface SqliteConnectionConfig {
+    filename: string;
+}
+/**
+ * Union type for all supported connection configurations.
+ * Also accepts a raw connection string (e.g., postgres://user:pass@host/db).
+ */
+type ConnectionConfig = ServerConnectionConfig | SqliteConnectionConfig | string;
+/**
+ * Pool configuration options.
+ */
+interface PoolConfig {
+    min?: number;
+    max?: number;
+    idleTimeoutMillis?: number;
+}
+/**
+ * Cleanup strategy after each test.
+ * - 'transaction': Wrap each test in a transaction and rollback (fastest, default).
+ * - 'truncate': TRUNCATE all tables that were modified.
+ * - 'delete': DELETE rows that were inserted by haveInDatabase.
+ * - 'none': No automatic cleanup (user manages state).
+ */
+type CleanupStrategy = 'transaction' | 'truncate' | 'delete' | 'none';
+/**
+ * Top-level configuration object for the db fixture.
+ * Users provide this in playwright.config.ts via `use: { dbConfig: { ... } }`.
+ */
+interface DbConnectorConfig {
+    /** Database client identifier */
+    client: DatabaseClient;
+    /** Connection details */
+    connection: ConnectionConfig;
+    /** Connection pool settings (ignored for SQLite) */
+    pool?: PoolConfig;
+    /** How to clean up test data after each test. Default: 'transaction' */
+    cleanupStrategy?: CleanupStrategy;
+    /** SQL file path(s) to execute before the test suite starts (worker-scoped) */
+    seedFiles?: string | string[];
+    /** CSV file path(s) in TYPO3 format to import before the test suite starts (worker-scoped) */
+    seedCsvFiles?: string | string[];
+    /** Name of the primary key column. Default: 'id'. TYPO3 uses 'uid'. */
+    primaryKeyColumn?: string;
+    /** Additional knex configuration (escape hatch) */
+    knexConfig?: Partial<Knex.Config>;
+}
+/**
+ * A record of column-value pairs used for WHERE clauses.
+ */
+type WhereCriteria = Record<string, unknown>;
+/**
+ * A record of column-value pairs for INSERT or UPDATE operations.
+ */
+type RecordData = Record<string, unknown>;
+/**
+ * An insert tracked for automatic cleanup.
+ */
+interface TrackedInsert {
+    table: string;
+    primaryKey: string;
+    primaryKeyValues: unknown[];
+}
+/**
+ * The main API surface exposed to Playwright tests as the `db` fixture.
+ */
+interface DatabaseConnector {
+    /** Assert that at least one record matching criteria exists. */
+    seeInDatabase(table: string, criteria: WhereCriteria): Promise<void>;
+    /** Assert that no records matching criteria exist. */
+    dontSeeInDatabase(table: string, criteria: WhereCriteria): Promise<void>;
+    /** Assert that exactly `expectedCount` records match criteria. */
+    seeNumRecords(expectedCount: number, table: string, criteria?: WhereCriteria): Promise<void>;
+    /** Retrieve a single column value from the first matching record. */
+    grabFromDatabase<T = unknown>(table: string, column: string, criteria?: WhereCriteria): Promise<T | undefined>;
+    /** Retrieve all values of a single column from matching records. */
+    grabColumnFromDatabase<T = unknown>(table: string, column: string, criteria?: WhereCriteria): Promise<T[]>;
+    /** Retrieve all matching records as an array of objects. */
+    grabEntriesFromDatabase(table: string, criteria?: WhereCriteria): Promise<RecordData[]>;
+    /** Retrieve the count of matching records. */
+    grabNumRecords(table: string, criteria?: WhereCriteria): Promise<number>;
+    /** Insert a record. Tracked for auto-cleanup. Returns the primary key value. */
+    haveInDatabase(table: string, data: RecordData): Promise<unknown>;
+    /** Update records matching criteria. Returns number of affected rows. */
+    updateInDatabase(table: string, data: RecordData, criteria: WhereCriteria): Promise<number>;
+    /** Delete records matching criteria. Returns number of deleted rows. */
+    deleteFromDatabase(table: string, criteria: WhereCriteria): Promise<number>;
+    /** Execute a raw SQL query with parameter bindings. */
+    query<T = RecordData[]>(sql: string, bindings?: readonly unknown[]): Promise<T>;
+    /** Execute a callback within an explicit transaction (or savepoint if already in one). */
+    transaction<T>(callback: (trx: DatabaseConnector) => Promise<T>): Promise<T>;
+    /** Load and execute a SQL file against the database. */
+    loadSqlFile(filePath: string): Promise<void>;
+    /**
+     * Import a CSV dataset file (TYPO3 testing framework format).
+     *
+     * Format: table name in first column, column headers following on the same row,
+     * data rows start with an empty first field. Multiple tables per file supported.
+     *
+     * Example:
+     * ```csv
+     * "users","uid","name","email"
+     * ,1,"Alice","alice@example.com"
+     * ```
+     */
+    importCsvFile(filePath: string): Promise<void>;
+    /**
+     * Assert that the database matches the expected data in a CSV file.
+     * Looks up each row by its first column (primary key) and compares all values.
+     * Throws with a detailed diff on mismatch.
+     */
+    assertCsvDataSet(filePath: string): Promise<void>;
+    /** Access the underlying knex instance for advanced usage. */
+    readonly knex: Knex;
+}
+/**
+ * Test-scoped fixtures provided by the plugin.
+ */
+interface DbTestFixtures {
+    db: DatabaseConnector;
+}
+/**
+ * Worker-scoped fixtures provided by the plugin.
+ */
+interface DbWorkerFixtures {
+    dbConfig: DbConnectorConfig;
+    _dbKnexPool: Knex;
+}
+
+declare const test: _playwright_test.TestType<_playwright_test.PlaywrightTestArgs & _playwright_test.PlaywrightTestOptions & DbTestFixtures, _playwright_test.PlaywrightWorkerArgs & _playwright_test.PlaywrightWorkerOptions & DbWorkerFixtures>;
+
+declare const expect: _playwright_test.Expect<{
+    toHaveRecord(this: _playwright_test.ExpectMatcherState, db: DatabaseConnector, table: string, criteria: WhereCriteria): Promise<{
+        pass: false;
+        message: () => string;
+        name: string;
+        expected?: undefined;
+        actual?: undefined;
+    } | {
+        pass: boolean;
+        message: () => string;
+        name: string;
+        expected: string | number;
+        actual: number;
+    }>;
+    toHaveRecordCount(this: _playwright_test.ExpectMatcherState, db: DatabaseConnector, expectedCount: number, table: string, criteria?: WhereCriteria): Promise<{
+        pass: false;
+        message: () => string;
+        name: string;
+        expected?: undefined;
+        actual?: undefined;
+    } | {
+        pass: boolean;
+        message: () => string;
+        name: string;
+        expected: number;
+        actual: number;
+    }>;
+}>;
+
+declare class CleanupTracker {
+    private inserts;
+    track(table: string, primaryKey: string, primaryKeyValues: unknown[]): void;
+    /**
+     * Delete tracked rows in reverse insertion order (respects foreign keys).
+     */
+    cleanupByDelete(queryable: Knex): Promise<void>;
+    /**
+     * Truncate all tables that received inserts. Dialect-aware.
+     */
+    cleanupByTruncate(queryable: Knex, client: DatabaseClient): Promise<void>;
+    clear(): void;
+    get trackedInserts(): ReadonlyArray<TrackedInsert>;
+}
+
+declare class DatabaseConnectorImpl implements DatabaseConnector {
+    private readonly queryable;
+    private readonly tracker;
+    private readonly client;
+    private readonly primaryKeyColumn;
+    constructor(queryable: Knex | Knex.Transaction, tracker: CleanupTracker, client: DatabaseClient, primaryKeyColumn?: string);
+    get knex(): Knex;
+    seeInDatabase(table: string, criteria: WhereCriteria): Promise<void>;
+    dontSeeInDatabase(table: string, criteria: WhereCriteria): Promise<void>;
+    seeNumRecords(expectedCount: number, table: string, criteria?: WhereCriteria): Promise<void>;
+    grabFromDatabase<T = unknown>(table: string, column: string, criteria?: WhereCriteria): Promise<T | undefined>;
+    grabColumnFromDatabase<T = unknown>(table: string, column: string, criteria?: WhereCriteria): Promise<T[]>;
+    grabEntriesFromDatabase(table: string, criteria?: WhereCriteria): Promise<RecordData[]>;
+    grabNumRecords(table: string, criteria?: WhereCriteria): Promise<number>;
+    haveInDatabase(table: string, data: RecordData): Promise<unknown>;
+    updateInDatabase(table: string, data: RecordData, criteria: WhereCriteria): Promise<number>;
+    deleteFromDatabase(table: string, criteria: WhereCriteria): Promise<number>;
+    query<T = RecordData[]>(sql: string, bindings?: readonly unknown[]): Promise<T>;
+    transaction<T>(callback: (trx: DatabaseConnector) => Promise<T>): Promise<T>;
+    loadSqlFile(filePath: string): Promise<void>;
+    importCsvFile(filePath: string): Promise<void>;
+    assertCsvDataSet(filePath: string): Promise<void>;
+}
+
+declare class SqlLoader {
+    /**
+     * Read a SQL file and execute its statements against the database.
+     */
+    static executeFile(db: Knex, filePath: string): Promise<void>;
+    /**
+     * Execute a SQL string containing one or more semicolon-separated statements.
+     */
+    static executeStatements(db: Knex, sql: string): Promise<void>;
+    /**
+     * Split a SQL string on semicolons while respecting:
+     * - Single-quoted strings ('it''s ok')
+     * - Double-quoted identifiers ("table")
+     * - Single-line comments (-- comment)
+     * - Multi-line comments (/* comment *​/)
+     */
+    static splitStatements(sql: string): string[];
+}
+
+/**
+ * Parsed representation of a CSV dataset: table name → array of row objects.
+ */
+type CsvDataSet = Map<string, RecordData[]>;
+/**
+ * Loads and asserts CSV datasets using the TYPO3 testing framework format.
+ *
+ * Format:
+ * - A row starting with a quoted table name begins a new table section.
+ *   The remaining values on that row are the column headers.
+ * - Subsequent rows (starting with a comma / empty first field) are data rows.
+ * - `\NULL` represents a SQL NULL value.
+ * - Multiple tables can appear in one file.
+ *
+ * Example:
+ * ```csv
+ * "users","uid","name","email","active"
+ * ,1,"Alice","alice@example.com",1
+ * ,2,"Bob","bob@example.com",1
+ * "posts","uid","user_id","title"
+ * ,1,1,"Hello World"
+ * ```
+ */
+declare class CsvLoader {
+    /**
+     * Parse a CSV file into a CsvDataSet.
+     */
+    static parseFile(filePath: string): CsvDataSet;
+    /**
+     * Parse CSV content string into a CsvDataSet.
+     */
+    static parse(content: string): CsvDataSet;
+    /**
+     * Import a CSV file into the database.
+     * Inserts all rows from the dataset into their respective tables.
+     */
+    static importFile(db: Knex, filePath: string): Promise<void>;
+    /**
+     * Import a parsed CsvDataSet into the database.
+     */
+    static importDataSet(db: Knex, dataset: CsvDataSet): Promise<void>;
+    /**
+     * Assert that the database contains exactly the data described in a CSV file.
+     * For each table/row in the CSV, looks up the row by its first column (typically
+     * the primary key) and compares all other column values.
+     *
+     * Throws DatabaseAssertionError with a detailed diff on mismatch.
+     */
+    static assertFile(db: Knex, filePath: string): Promise<void>;
+    /**
+     * Assert that the database matches a parsed CsvDataSet.
+     */
+    static assertDataSet(db: Knex, dataset: CsvDataSet): Promise<void>;
+    /**
+     * Parse a single CSV line into an array of field values.
+     * Handles quoted fields and escaped quotes (double-double-quotes).
+     */
+    static parseLine(line: string): string[];
+    /**
+     * Convert a CSV field value to a JavaScript value.
+     * - `\NULL` → null
+     * - numeric strings → number
+     * - everything else → string
+     */
+    private static convertValue;
+}
+
+declare class DatabaseDriverNotFoundError extends Error {
+    constructor(client: string);
+}
+declare class DatabaseAssertionError extends Error {
+    constructor(message: string);
+}
+
+export { type CleanupStrategy, CleanupTracker, type ConnectionConfig, type CsvDataSet, CsvLoader, DatabaseAssertionError, type DatabaseClient, type DatabaseConnector, DatabaseConnectorImpl, DatabaseDriverNotFoundError, type DbConnectorConfig, type DbTestFixtures, type DbWorkerFixtures, type PoolConfig, type RecordData, type ServerConnectionConfig, SqlLoader, type SqliteConnectionConfig, type WhereCriteria, expect, test };