@forklaunch/testing 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 forklaunch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/index.d.mts

@@ -0,0 +1,215 @@
+import { StartedTestContainer } from 'testcontainers';
+import { MikroORM } from '@mikro-orm/core';
+import Redis from 'ioredis';
+
+type DatabaseType = 'postgres' | 'postgresql' | 'mysql' | 'mariadb' | 'mongodb' | 'mongo' | 'mssql' | 'libsql' | 'sqlite' | 'better-sqlite';
+interface PostgresConfig {
+    user?: string;
+    password?: string;
+    database?: string;
+    command?: string[];
+}
+interface MySQLConfig {
+    user?: string;
+    password?: string;
+    database?: string;
+    rootPassword?: string;
+}
+interface MongoDBConfig {
+    user?: string;
+    password?: string;
+    database?: string;
+}
+interface MSSQLConfig {
+    user?: string;
+    password?: string;
+    database?: string;
+    saPassword?: string;
+}
+interface SQLiteConfig {
+    database?: string;
+}
+interface RedisConfig {
+    command?: string[];
+}
+type DatabaseConfig = PostgresConfig | MySQLConfig | MongoDBConfig | MSSQLConfig | SQLiteConfig;
+/**
+ * Manages test containers (PostgreSQL, MySQL, MongoDB, Redis, etc.) for E2E testing
+ */
+declare class TestContainerManager {
+    private containers;
+    /**
+     * Setup database container based on type
+     */
+    setupDatabaseContainer(type: DatabaseType, config?: DatabaseConfig): Promise<StartedTestContainer | null>;
+    /**
+     * Normalize database type aliases
+     */
+    private normalizeDatabaseType;
+    /**
+     * Setup PostgreSQL test container
+     */
+    setupPostgresContainer(config?: PostgresConfig): Promise<StartedTestContainer>;
+    /**
+     * Setup MySQL test container
+     */
+    setupMySQLContainer(config?: MySQLConfig): Promise<StartedTestContainer>;
+    /**
+     * Setup MongoDB test container
+     */
+    setupMongoDBContainer(config?: MongoDBConfig): Promise<StartedTestContainer>;
+    /**
+     * Setup Microsoft SQL Server test container
+     */
+    setupMSSQLContainer(config?: MSSQLConfig): Promise<StartedTestContainer>;
+    /**
+     * Setup Redis test container
+     */
+    setupRedisContainer(config?: RedisConfig): Promise<StartedTestContainer>;
+    /**
+     * Cleanup all containers
+     */
+    cleanup(): Promise<void>;
+}
+
+interface TestEnvConfig {
+    database: StartedTestContainer | null;
+    databaseType: DatabaseType;
+    redis?: StartedTestContainer;
+    hmacSecret?: string;
+    customVars?: Record<string, string>;
+}
+/**
+ * Setup test environment variables for a blueprint test
+ */
+declare function setupTestEnvironment(config: TestEnvConfig): void;
+
+interface MikroOrmTestConfig {
+    /**
+     * Path to the MikroORM config file (e.g., '../mikro-orm.config')
+     */
+    mikroOrmConfigPath: string;
+    /**
+     * Database type (postgres, mysql, mongodb, etc.)
+     */
+    databaseType: DatabaseType;
+    /**
+     * Whether to use migrations (true) or schema generation (false)
+     * - true: IAM blueprints (uses getMigrator().up())
+     * - false: Billing blueprints (uses getSchemaGenerator().createSchema())
+     */
+    useMigrations?: boolean;
+    /**
+     * Path to migrations directory (required if useMigrations is true)
+     */
+    migrationsPath?: string;
+    /**
+     * Database container instance (null for file-based databases like SQLite)
+     */
+    container: StartedTestContainer | null;
+}
+/**
+ * Setup MikroORM for testing with proper schema/migrations
+ */
+declare function setupTestORM(config: MikroOrmTestConfig): Promise<MikroORM>;
+/**
+ * Clear all data from the test database
+ */
+declare function clearTestDatabase(orm: MikroORM, redis?: Redis): Promise<void>;
+
+interface BlueprintTestConfig {
+    /**
+     * Path to the MikroORM config file (e.g., '../mikro-orm.config')
+     */
+    mikroOrmConfigPath: string;
+    /**
+     * Database type (postgres, mysql, mongodb, etc.)
+     * @default 'postgres'
+     */
+    databaseType?: DatabaseType;
+    /**
+     * Whether to use migrations (true) or schema generation (false)
+     */
+    useMigrations?: boolean;
+    /**
+     * Path to migrations directory (required if useMigrations is true)
+     */
+    migrationsPath?: string;
+    /**
+     * Whether the blueprint needs Redis
+     */
+    needsRedis?: boolean;
+    /**
+     * Custom environment variables to set
+     */
+    customEnvVars?: Record<string, string>;
+    /**
+     * Custom setup hook called after containers and ORM are initialized
+     */
+    onSetup?: (setup: TestSetupResult) => Promise<void>;
+}
+interface TestSetupResult {
+    container: StartedTestContainer | null;
+    redisContainer?: StartedTestContainer;
+    orm: MikroORM;
+    redis?: Redis;
+}
+/**
+ * Complete test harness for blueprint E2E testing
+ *
+ * Handles container setup, environment configuration, and database initialization
+ *
+ * @example
+ * ```typescript
+ * const harness = new BlueprintTestHarness({
+ *   mikroOrmConfigPath: '../mikro-orm.config',
+ *   useMigrations: false,
+ *   needsRedis: true,
+ *   customEnvVars: {
+ *     STRIPE_API_KEY: 'sk_test_...'
+ *   }
+ * });
+ *
+ * const setup = await harness.setup();
+ * // ... run tests
+ * await harness.cleanup();
+ * ```
+ */
+declare class BlueprintTestHarness {
+    private config;
+    private containers;
+    private result?;
+    constructor(config: BlueprintTestConfig);
+    /**
+     * Setup all test infrastructure (containers, ORM, Redis)
+     */
+    setup(): Promise<TestSetupResult>;
+    /**
+     * Cleanup all test infrastructure
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Clear all data from the database
+     */
+    clearDatabase(): Promise<void>;
+}
+
+/**
+ * Standard mock authentication tokens for testing
+ */
+declare const TEST_TOKENS: {
+    /**
+     * Mock Bearer token for testing
+     */
+    readonly AUTH: "Bearer test-token";
+    /**
+     * Mock valid HMAC token for testing
+     */
+    readonly HMAC: "HMAC keyId=test-key ts=1234567890 nonce=test-nonce signature=test-signature";
+    /**
+     * Mock invalid HMAC token for testing authentication failures
+     */
+    readonly HMAC_INVALID: "HMAC keyId=invalid-key ts=1234567890 nonce=invalid-nonce signature=invalid-signature";
+};
+
+export { type BlueprintTestConfig, BlueprintTestHarness, type DatabaseConfig, type DatabaseType, type MSSQLConfig, type MikroOrmTestConfig, type MongoDBConfig, type MySQLConfig, type PostgresConfig, type RedisConfig, type SQLiteConfig, TEST_TOKENS, TestContainerManager, type TestEnvConfig, type TestSetupResult, clearTestDatabase, setupTestEnvironment, setupTestORM };

package/lib/index.d.ts

@@ -0,0 +1,215 @@
+import { StartedTestContainer } from 'testcontainers';
+import { MikroORM } from '@mikro-orm/core';
+import Redis from 'ioredis';
+
+type DatabaseType = 'postgres' | 'postgresql' | 'mysql' | 'mariadb' | 'mongodb' | 'mongo' | 'mssql' | 'libsql' | 'sqlite' | 'better-sqlite';
+interface PostgresConfig {
+    user?: string;
+    password?: string;
+    database?: string;
+    command?: string[];
+}
+interface MySQLConfig {
+    user?: string;
+    password?: string;
+    database?: string;
+    rootPassword?: string;
+}
+interface MongoDBConfig {
+    user?: string;
+    password?: string;
+    database?: string;
+}
+interface MSSQLConfig {
+    user?: string;
+    password?: string;
+    database?: string;
+    saPassword?: string;
+}
+interface SQLiteConfig {
+    database?: string;
+}
+interface RedisConfig {
+    command?: string[];
+}
+type DatabaseConfig = PostgresConfig | MySQLConfig | MongoDBConfig | MSSQLConfig | SQLiteConfig;
+/**
+ * Manages test containers (PostgreSQL, MySQL, MongoDB, Redis, etc.) for E2E testing
+ */
+declare class TestContainerManager {
+    private containers;
+    /**
+     * Setup database container based on type
+     */
+    setupDatabaseContainer(type: DatabaseType, config?: DatabaseConfig): Promise<StartedTestContainer | null>;
+    /**
+     * Normalize database type aliases
+     */
+    private normalizeDatabaseType;
+    /**
+     * Setup PostgreSQL test container
+     */
+    setupPostgresContainer(config?: PostgresConfig): Promise<StartedTestContainer>;
+    /**
+     * Setup MySQL test container
+     */
+    setupMySQLContainer(config?: MySQLConfig): Promise<StartedTestContainer>;
+    /**
+     * Setup MongoDB test container
+     */
+    setupMongoDBContainer(config?: MongoDBConfig): Promise<StartedTestContainer>;
+    /**
+     * Setup Microsoft SQL Server test container
+     */
+    setupMSSQLContainer(config?: MSSQLConfig): Promise<StartedTestContainer>;
+    /**
+     * Setup Redis test container
+     */
+    setupRedisContainer(config?: RedisConfig): Promise<StartedTestContainer>;
+    /**
+     * Cleanup all containers
+     */
+    cleanup(): Promise<void>;
+}
+
+interface TestEnvConfig {
+    database: StartedTestContainer | null;
+    databaseType: DatabaseType;
+    redis?: StartedTestContainer;
+    hmacSecret?: string;
+    customVars?: Record<string, string>;
+}
+/**
+ * Setup test environment variables for a blueprint test
+ */
+declare function setupTestEnvironment(config: TestEnvConfig): void;
+
+interface MikroOrmTestConfig {
+    /**
+     * Path to the MikroORM config file (e.g., '../mikro-orm.config')
+     */
+    mikroOrmConfigPath: string;
+    /**
+     * Database type (postgres, mysql, mongodb, etc.)
+     */
+    databaseType: DatabaseType;
+    /**
+     * Whether to use migrations (true) or schema generation (false)
+     * - true: IAM blueprints (uses getMigrator().up())
+     * - false: Billing blueprints (uses getSchemaGenerator().createSchema())
+     */
+    useMigrations?: boolean;
+    /**
+     * Path to migrations directory (required if useMigrations is true)
+     */
+    migrationsPath?: string;
+    /**
+     * Database container instance (null for file-based databases like SQLite)
+     */
+    container: StartedTestContainer | null;
+}
+/**
+ * Setup MikroORM for testing with proper schema/migrations
+ */
+declare function setupTestORM(config: MikroOrmTestConfig): Promise<MikroORM>;
+/**
+ * Clear all data from the test database
+ */
+declare function clearTestDatabase(orm: MikroORM, redis?: Redis): Promise<void>;
+
+interface BlueprintTestConfig {
+    /**
+     * Path to the MikroORM config file (e.g., '../mikro-orm.config')
+     */
+    mikroOrmConfigPath: string;
+    /**
+     * Database type (postgres, mysql, mongodb, etc.)
+     * @default 'postgres'
+     */
+    databaseType?: DatabaseType;
+    /**
+     * Whether to use migrations (true) or schema generation (false)
+     */
+    useMigrations?: boolean;
+    /**
+     * Path to migrations directory (required if useMigrations is true)
+     */
+    migrationsPath?: string;
+    /**
+     * Whether the blueprint needs Redis
+     */
+    needsRedis?: boolean;
+    /**
+     * Custom environment variables to set
+     */
+    customEnvVars?: Record<string, string>;
+    /**
+     * Custom setup hook called after containers and ORM are initialized
+     */
+    onSetup?: (setup: TestSetupResult) => Promise<void>;
+}
+interface TestSetupResult {
+    container: StartedTestContainer | null;
+    redisContainer?: StartedTestContainer;
+    orm: MikroORM;
+    redis?: Redis;
+}
+/**
+ * Complete test harness for blueprint E2E testing
+ *
+ * Handles container setup, environment configuration, and database initialization
+ *
+ * @example
+ * ```typescript
+ * const harness = new BlueprintTestHarness({
+ *   mikroOrmConfigPath: '../mikro-orm.config',
+ *   useMigrations: false,
+ *   needsRedis: true,
+ *   customEnvVars: {
+ *     STRIPE_API_KEY: 'sk_test_...'
+ *   }
+ * });
+ *
+ * const setup = await harness.setup();
+ * // ... run tests
+ * await harness.cleanup();
+ * ```
+ */
+declare class BlueprintTestHarness {
+    private config;
+    private containers;
+    private result?;
+    constructor(config: BlueprintTestConfig);
+    /**
+     * Setup all test infrastructure (containers, ORM, Redis)
+     */
+    setup(): Promise<TestSetupResult>;
+    /**
+     * Cleanup all test infrastructure
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Clear all data from the database
+     */
+    clearDatabase(): Promise<void>;
+}
+
+/**
+ * Standard mock authentication tokens for testing
+ */
+declare const TEST_TOKENS: {
+    /**
+     * Mock Bearer token for testing
+     */
+    readonly AUTH: "Bearer test-token";
+    /**
+     * Mock valid HMAC token for testing
+     */
+    readonly HMAC: "HMAC keyId=test-key ts=1234567890 nonce=test-nonce signature=test-signature";
+    /**
+     * Mock invalid HMAC token for testing authentication failures
+     */
+    readonly HMAC_INVALID: "HMAC keyId=invalid-key ts=1234567890 nonce=invalid-nonce signature=invalid-signature";
+};
+
+export { type BlueprintTestConfig, BlueprintTestHarness, type DatabaseConfig, type DatabaseType, type MSSQLConfig, type MikroOrmTestConfig, type MongoDBConfig, type MySQLConfig, type PostgresConfig, type RedisConfig, type SQLiteConfig, TEST_TOKENS, TestContainerManager, type TestEnvConfig, type TestSetupResult, clearTestDatabase, setupTestEnvironment, setupTestORM };