@solidxai/core 0.1.1 → 0.1.4

package/docs/test-data-workflow.md

@@ -18,7 +18,7 @@ The commands below are the canonical flow.
 
 Command:
 ```
-npx @solidxai/solidctl test-data --create-datasources
+npx @solidxai/solidctl test data --setup
 ```
 
 What this does:
@@ -33,7 +33,7 @@ What this does:
 
 Example output:
 ```
-▶ Running solid test-data
+▶ Running solid test data
 Creating test datasource environment file and manifest.
 Backed up .env to .env.backup.steady_wolf and applied new test datasource names to .env.
 Creating test database/schema "default_20260201234402_steady_wolf" on datasource "default"...
@@ -55,7 +55,7 @@ Creating test database/schema "default_20260201234402_steady_wolf" on datasource
   5) Tear down
 ============================================================
 
-✔ solid test-data completed
+✔ solid test data completed
 ```
 
 Rationale:
@@ -97,7 +97,7 @@ Rationale:
 
 Command:
 ```
-npx @solidxai/solidctl test-data --load-data
+npx @solidxai/solidctl test data --load
 ```
 
 What this does:
@@ -109,13 +109,13 @@ What this does:
 
 Example output:
 ```
-▶ Running solid test-data
+▶ Running solid test data
 Test data setup for all modules.
 Processing test data for module: solid-core
 ✔ Test data setup complete for module: solid-core
 Processing test data for module: venue
 ✔ Test data setup complete for module: venue
-✔ solid test-data completed
+✔ solid test data completed
 ```
 
 Rationale:
@@ -123,11 +123,51 @@ Rationale:
 
 ---
 
-## Step 4: Tear everything down
+
+## Step 4: Run Tests 
+```
+npx @solidxai/solidctl test run --module venue --api-base-url http://localhost:3000 --ui-base-url http://localhost:5173 --headless false
+```
+
+```
+npx @solidxai/solidctl test run --module venue --list-specs
+```
+
+What this does:
+- Loads `testing.scenarios` from the module metadata file.
+- Applies `--scenario-ids` or `--include-tags` filtering if provided.
+- Boots API and UI adapters with the supplied base URLs.
+- Registers any custom test specs listed in `testing.specs`.
+- Executes scenarios in order with fail‑fast behavior.
+
+Useful variants:
+```
+npx @solidxai/solidctl test run --module venue --scenario-ids api-authenticate-success,api-create-states
+```
+
+```
+npx @solidxai/solidctl test run --module venue --include-tags smoke
+```
+
+```
+npx @solidxai/solidctl test run --module venue --api-base-url http://localhost:3000 --headless true
+```
+
+```
+npx @solidxai/solidctl test run --module venue --headless false
+```
+
+Notes:
+- If your scenario depends on a previous scenario’s `saveAs` output (e.g., `loginSuccess`), ensure the auth scenario runs first.
+- For UI tests, `--ui-base-url` should point to a running frontend server.
+- `--list-specs` prints registered custom `test.spec` ids and exits.
+
+
+## Step 5: Tear everything down
 
 Command:
 ```
-npx @solidxai/solidctl test-data --delete-datasources
+npx @solidxai/solidctl test data --teardown
 ```
 
 What this does:
@@ -138,11 +178,11 @@ What this does:
 
 Example output:
 ```
-▶ Running solid test-data
+▶ Running solid test data
 Deleting test datasource environment and databases.
 Dropping test database/schema "default_20260201234402_steady_wolf" on datasource "default"...
 ✔ Test datasource env files and manifest deleted; test databases dropped.
-✔ solid test-data completed
+✔ solid test data completed
 ```
 
 Rationale:
@@ -154,7 +194,7 @@ Rationale:
 
 You can restrict test data loading to a subset of modules:
 ```
-npx @solidxai/solidctl test-data --load-data --modules-to-test venue,reports
+npx @solidxai/solidctl test data --load --modules-to-test venue,reports
 ```
 
 Only the listed modules are processed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidxai/core",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "This module is a NestJS module containing all the required core providers required by a Solid application",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -24,7 +24,8 @@
     "test:cov": "jest --coverage",
     "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
     "test:e2e": "jest --config ./test/jest-e2e.json",
-    "prepare": "npm run build"
+    "prepare": "npm run build",
+    "prepack": "npm run build"
   },
   "author": "Oswald Rodrigues <oswald@logicloop.io>",
   "license": "ISC",
@@ -118,6 +119,7 @@
     "@nestjs/testing": "^10.0.0",
     "@nestjs/typeorm": "^10.0.1",
     "@solidxai/code-builder": "^0.0.2",
+    "@playwright/test": "^1.50.0",
     "@types/express": "^4.17.17",
     "@types/hapi__joi": "^17.1.12",
     "@types/jest": "^29.5.2",

package/src/commands/run-tests.command.ts

@@ -0,0 +1,278 @@
+import { Logger } from '@nestjs/common';
+import { SubCommand, CommandRunner, Option } from 'nest-commander';
+import * as path from 'path';
+import { ModuleMetadataHelperService } from 'src/helpers/module-metadata-helper.service';
+import { ConsoleReporter } from 'src/testing/reporter/console-reporter';
+import { runFromMetadata } from 'src/testing/runner/run-from-metadata';
+import type { TestingMetadata } from 'src/testing/contracts/testing-metadata.types';
+import { SpecRegistry } from 'src/testing/core/spec-registry';
+
+interface TestRunCommandOptions {
+  module?: string;
+  moduleName?: string;
+  scenarioIds?: string;
+  includeTags?: string;
+  skipScenarioIds?: string;
+  reporter?: string;
+  apiBaseUrl?: string;
+  uiBaseUrl?: string;
+  headless?: boolean;
+  timeoutMs?: number;
+  retries?: number;
+  listSpecs?: boolean;
+  printApiLogs?: boolean;
+}
+
+@SubCommand({
+  name: 'run',
+  description: 'Run testing scenarios from module metadata.',
+})
+export class TestRunCommand extends CommandRunner {
+  private readonly logger = new Logger(TestRunCommand.name);
+
+  constructor(
+    private readonly moduleMetadataHelperService: ModuleMetadataHelperService,
+  ) {
+    super();
+  }
+
+  async run(passedParam: string[], options?: TestRunCommandOptions): Promise<void> {
+    try {
+      const moduleName = options?.moduleName ?? options?.module ?? passedParam?.[0];
+      if (!moduleName) {
+        this.logger.error('Module name is required. Use --module or pass it as the first argument.');
+        return;
+      }
+
+      const metadataPath = await this.moduleMetadataHelperService.getModuleMetadataFilePath(moduleName);
+      if (!metadataPath) {
+        this.logger.error(`Unable to resolve metadata path for module: ${moduleName}`);
+        return;
+      }
+
+      const metadata = await this.moduleMetadataHelperService.getModuleMetadataConfiguration(metadataPath);
+      if (!metadata?.testing) {
+        this.logger.error(`No testing configuration found in metadata: ${metadataPath}`);
+        return;
+      }
+
+      const listSpecs = options?.listSpecs ?? false;
+      const specEntries = Array.isArray(metadata.testing?.specs)
+        ? metadata.testing.specs
+        : [];
+
+      if (listSpecs) {
+        const registry = new SpecRegistry();
+        if (specEntries.length) {
+          loadSpecRegistrations(specEntries, metadataPath, registry);
+        }
+        printSpecList(registry.list());
+        return;
+      }
+      if (!metadata?.testing?.scenarios || !Array.isArray(metadata.testing.scenarios)) {
+        this.logger.error(`No testing.scenarios found in metadata: ${metadataPath}`);
+        return;
+      }
+
+      const scenarioIds = splitCsv(options?.scenarioIds);
+      const includeTags = splitCsv(options?.includeTags);
+      const skipScenarioIds = splitCsv(options?.skipScenarioIds);
+
+      const reporterName = options?.reporter ?? 'console';
+      if (reporterName !== 'console') {
+        this.logger.error(`Unsupported reporter: ${reporterName}. Use "console".`);
+        return;
+      }
+
+      const apiBaseUrl = options?.apiBaseUrl ?? process.env.BASE_URL;
+      const uiBaseUrl = options?.uiBaseUrl ?? process.env.FRONTEND_BASE_URL;
+      const headless = options?.headless ?? true;
+      const printApiLogs = options?.printApiLogs ?? false;
+
+      await runFromMetadata({
+        metadata: metadata as TestingMetadata,
+        scenarioIds,
+        includeTags,
+        skipScenarioIds,
+        reporter: new ConsoleReporter(),
+        api: apiBaseUrl ? { baseUrl: apiBaseUrl } : undefined,
+        ui: { baseUrl: uiBaseUrl, headless },
+        defaults: {
+          timeoutMs: options?.timeoutMs,
+          retries: options?.retries,
+        },
+        options: { printApiLogs },
+        specs: specEntries.length
+          ? (registry) => loadSpecRegistrations(specEntries, metadataPath, registry)
+          : undefined,
+      });
+    } catch (err: any) {
+      this.logger.error('Run tests command failed');
+      console.error('Run tests command failed');
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  @Option({
+    flags: '-m, --module [module name]',
+    description: 'Module name to load metadata from.',
+    required: false,
+  })
+  parseModule(val: string): string {
+    return val;
+  }
+
+  @Option({
+    flags: '--scenario-ids [ids]',
+    description: 'Comma-separated list of scenario ids to run.',
+    required: false,
+  })
+  parseScenarioIds(val: string): string {
+    return val;
+  }
+
+  @Option({
+    flags: '--include-tags [tags]',
+    description: 'Comma-separated list of tags; scenario must include all.',
+    required: false,
+  })
+  parseIncludeTags(val: string): string {
+    return val;
+  }
+
+  @Option({
+    flags: '--skip-scenario-ids [ids]',
+    description: 'Comma-separated list of scenario ids to skip.',
+    required: false,
+  })
+  parseSkipScenarioIds(val: string): string {
+    return val;
+  }
+
+  @Option({
+    flags: '--reporter [name]',
+    description: 'Reporter name (currently only "console").',
+    required: false,
+  })
+  parseReporter(val: string): string {
+    return val;
+  }
+
+  @Option({
+    flags: '--list-specs [true|false]',
+    description: 'List registered test specs and exit.',
+    required: false,
+  })
+  parseListSpecs(val?: string): boolean {
+    if (val === undefined) return true;
+    return val === 'false' ? false : true;
+  }
+
+  @Option({
+    flags: '--print-api-logs [true|false]',
+    description: 'Print full API request/response logs for api.request steps.',
+    required: false,
+  })
+  parsePrintApiLogs(val?: string): boolean {
+    if (val === undefined) return true;
+    return val === 'false' ? false : true;
+  }
+
+  @Option({
+    flags: '--api-base-url [url]',
+    description: 'API base URL (defaults to process.env.BASE_URL).',
+    required: false,
+  })
+  parseApiBaseUrl(val: string): string {
+    return val;
+  }
+
+  @Option({
+    flags: '--ui-base-url [url]',
+    description: 'UI base URL (defaults to process.env.FRONTEND_BASE_URL).',
+    required: false,
+  })
+  parseUiBaseUrl(val: string): string {
+    return val;
+  }
+
+  @Option({
+    flags: '--headless [true|false]',
+    description: 'Run UI browser in headless mode (default: true).',
+    required: false,
+  })
+  parseHeadless(val: string): boolean {
+    return val === 'false' ? false : true;
+  }
+
+  @Option({
+    flags: '--timeout-ms [number]',
+    description: 'Default scenario timeout in milliseconds.',
+    required: false,
+  })
+  parseTimeoutMs(val: string): number {
+    return Number(val);
+  }
+
+  @Option({
+    flags: '--retries [number]',
+    description: 'Default scenario retries.',
+    required: false,
+  })
+  parseRetries(val: string): number {
+    return Number(val);
+  }
+}
+
+function splitCsv(value?: string): string[] | undefined {
+  if (!value) return undefined;
+  const items = value
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+  return items.length ? items : undefined;
+}
+
+function resolveSpecPath(entry: string, metadataPath: string): string {
+  if (path.isAbsolute(entry)) {
+    return entry;
+  }
+  if (entry.startsWith('.')) {
+    return path.resolve(path.dirname(metadataPath), entry);
+  }
+  return path.resolve(process.cwd(), entry);
+}
+
+function loadSpecRegistrations(entries: string[], metadataPath: string, registry: SpecRegistry): void {
+  for (const entry of entries) {
+    const resolved = resolveSpecPath(entry, metadataPath);
+    let mod: any;
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      mod = require(resolved);
+    } catch (err: any) {
+      const message = err?.message ?? String(err);
+      throw new Error(
+        `Failed to load test spec module "${entry}" resolved to "${resolved}": ${message}`,
+      );
+    }
+    const register = mod?.registerTestSpecs ?? mod?.default ?? mod;
+    if (typeof register !== 'function') {
+      throw new Error(
+        `Test spec module "${entry}" did not export a register function (expected "registerTestSpecs" or default export).`,
+      );
+    }
+    register(registry);
+  }
+}
+function printSpecList(specIds: string[]): void {
+  if (!specIds.length) {
+    console.log('No test specs registered.');
+    return;
+  }
+  console.log('Registered test specs:');
+  for (const id of specIds) {
+    console.log(`- ${id}`);
+  }
+}

package/src/commands/test-data.command.ts

@@ -1,17 +1,17 @@
 import { Logger } from '@nestjs/common';
-import { Command, CommandRunner, Option } from 'nest-commander';
+import { SubCommand, CommandRunner, Option } from 'nest-commander';
 import { ModuleTestDataService } from 'src/seeders/module-test-data.service';
 
 interface TestDataCommandOptions {
-  loadData?: boolean;
+  load?: boolean;
   modulesToTest?: string;
-  createDatasources?: boolean;
-  deleteDatasources?: boolean;
+  setup?: boolean;
+  teardown?: boolean;
 }
 
-@Command({
-  name: 'test-data',
-  description: 'Seed test data from testData sections',
+@SubCommand({
+  name: 'data',
+  description: 'Seed test data from testing.data sections',
 })
 export class TestDataCommand extends CommandRunner {
   private readonly logger = new Logger(TestDataCommand.name);
@@ -22,38 +22,38 @@ export class TestDataCommand extends CommandRunner {
 
   async run(_passedParam: string[], options?: TestDataCommandOptions): Promise<void> {
     try {
-      const loadData = Boolean(options?.loadData);
-      const createDatasources = Boolean(options?.createDatasources);
-      const deleteDatasources = Boolean(options?.deleteDatasources);
+      const load = Boolean(options?.load);
+      const setup = Boolean(options?.setup);
+      const teardown = Boolean(options?.teardown);
 
-      const selectedModes = [loadData, createDatasources, deleteDatasources].filter(Boolean).length;
+      const selectedModes = [load, setup, teardown].filter(Boolean).length;
       if (selectedModes > 1) {
-        this.logger.error('Please specify only one of --load-data, --create-datasources, or --delete-datasources.');
-        console.log('Please specify only one of --load-data, --create-datasources, or --delete-datasources.');
+        this.logger.error('Please specify only one of --load, --setup, or --teardown.');
+        console.log('Please specify only one of --load, --setup, or --teardown.');
         return;
       }
 
-      if (!loadData && !createDatasources && !deleteDatasources) {
-        this.logger.error('Please specify one of --load-data, --create-datasources, or --delete-datasources.');
-        console.log('Please specify one of --load-data, --create-datasources, or --delete-datasources.');
+      if (!load && !setup && !teardown) {
+        this.logger.error('Please specify one of --load, --setup, or --teardown.');
+        console.log('Please specify one of --load, --setup, or --teardown.');
         return;
       }
 
-      if (deleteDatasources) {
+      if (teardown) {
         this.logger.log('Deleting test datasource environment and databases.');
         console.log('Deleting test datasource environment and databases.');
         await this.testDataService.deleteTestDatasources();
         return;
       }
 
-      if (createDatasources) {
+      if (setup) {
         this.logger.log('Creating test datasource environment file and manifest.');
         console.log('Creating test datasource environment file and manifest.');
         await this.testDataService.createTestDatasources();
         return;
       }
 
-      if (loadData) {
+      if (load) {
         const modulesToTest = options?.modulesToTest ? options.modulesToTest.split(',').map((m) => m.trim()).filter(Boolean) : null;
         if (modulesToTest?.length) {
           this.logger.log(`Test data setup for modules: ${modulesToTest.join(', ')}`);
@@ -77,26 +77,26 @@ export class TestDataCommand extends CommandRunner {
   }
 
   @Option({
-    flags: '--load-data',
-    description: 'Seed test data from testData sections',
+    flags: '--load',
+    description: 'Seed test data from testing.data sections',
   })
-  parseLoadData(): boolean {
+  parseLoad(): boolean {
     return true;
   }
 
   @Option({
-    flags: '--create-datasources',
+    flags: '--setup',
     description: 'Create a new .env.<dbRunName> and test datasource manifest',
   })
-  parseCreateDatasources(): boolean {
+  parseSetup(): boolean {
     return true;
   }
 
   @Option({
-    flags: '--delete-datasources',
+    flags: '--teardown',
     description: 'Delete test datasource env/manifest and drop test databases',
   })
-  parseDeleteDatasources(): boolean {
+  parseTeardown(): boolean {
     return true;
   }
 

package/src/commands/test.command.ts

@@ -0,0 +1,14 @@
+import { Command, CommandRunner } from 'nest-commander';
+import { TestDataCommand } from './test-data.command';
+import { TestRunCommand } from './run-tests.command';
+
+@Command({
+  name: 'test',
+  description: 'Testing utilities.',
+  subCommands: [TestRunCommand, TestDataCommand],
+})
+export class TestCommand extends CommandRunner {
+  async run(): Promise<void> {
+    console.log('Usage: solidctl test <run|data> [options]');
+  }
+}