Velocious Full-Stack Framework

Common errors

• Error: Cannot find module 'velocious' or Cannot find module 'velocious/build/src/testing/test.js'

  cause Incorrect import path or the package was not installed correctly.
  fix Ensure `npm install velocious` has completed successfully. Verify the import paths are exact, especially for internal modules like `velocious/build/src/testing/test.js`.

• No tests found for the given criteria

  cause Incorrect test file naming convention, tag filtering, or test path specification.
  fix Browser tests must be `*.browser-test.js` or `*.browser-spec.js`. Check `npx velocious test --tag` and `npx velocious test --exclude-tag` arguments, and ensure the file path is correct. Use `--groups` and `--group-number` carefully for parallel runs.

• ReferenceError: configuration is not defined

  cause The application's configuration object was not properly imported or initialized using `configuration.setCurrent()` early enough in the application startup.
  fix Make sure `src/config/configuration.js` exists and exports a default configuration, or explicitly import your configuration file and call `configuration.setCurrent(yourConfigObject)` at the very beginning of your application.

Warnings

• gotcha Velocious uses specific internal paths for importing testing utilities like `configureTests` and `testEvents`. Importing these directly from the root 'velocious' package will fail or result in undefined behavior.
  Fix: Always use the full path: `import { configureTests } from 'velocious/build/src/testing/test.js'` and `import { testEvents } from 'velocious/build/src/testing/test.js'`.
• gotcha Application configuration is expected in `src/config/configuration.js` by default. If placed elsewhere, it must be explicitly imported and set via `configuration.setCurrent()` early in the application bootstrap process.
  Fix: Ensure your configuration is at the default path or explicitly call `configuration.setCurrent(yourConfigObject)` after importing it.
• gotcha When running tests, Velocious captures console output during failures. These logs are saved to `tmp/screenshots` alongside other failure artifacts. Developers might overlook checking this directory for detailed debugging information.
  Fix: After a failed test run, always inspect `tmp/screenshots` for console logs, screenshots, and browser logs associated with the failures.

Install

• npm install velocious npm
• yarn add velocious yarn
• pnpm add velocious pnpm

Imports

• configureTesting
  wrong:

  import { configureTests } from 'velocious'

  correct:

  import { configureTests } from 'velocious/build/src/testing/test.js'

  Configuration for testing needs to be imported from a specific internal path, not directly from the main package export. The `configureTests` function is used for global test settings like excluding tags.
• testEvents
  wrong:

  import { testEvents } from 'velocious'

  correct:

  import { testEvents } from 'velocious/build/src/testing/test.js'

  Event emitter for test lifecycle hooks (e.g., retries) is also found at the internal testing module path. This allows for custom actions during test execution.
• configuration
  wrong:

  import { configuration } from 'velocious'

  correct:

  import configuration from 'src/config/configuration.js'

  Application configuration is typically managed by a default export from a `src/config/configuration.js` file, which needs to be explicitly set as the current configuration using `configuration.setCurrent()`.

Quickstart

Demonstrates project initialization, basic test structure with tagging, retries, and configuring test behaviors, including event listeners for test retries.

import { configureTests } from 'velocious/build/src/testing/test.js';
import { testEvents } from 'velocious/build/src/testing/test.js';

// Initialize a new Velocious project
// This creates basic project structure and config files.
// npx velocious init

// Example test configuration
export default async function configureTesting() {
  configureTests({ excludeTags: ["mssql"] });
}

// Example of test suite setup with tagging and retries
describe("User Management", {tags: ["api", "db"]}, () => {
  beforeAll(async () => {
    // Setup database or other services before all tests in this suite
    console.log("Setting up user management suite...");
  });

  it("creates a new user successfully", {tags: ["fast", "write"]}, async () => {
    // Simulate user creation logic
    await new Promise(resolve => setTimeout(resolve, 50));
    expect(true).toBe(true);
  });

  it("handles duplicate username registration", {retry: 1}, async () => {
    // Simulate error handling for duplicates
    await new Promise(resolve => setTimeout(resolve, 30));
    expect(false).toBe(false);
  });

  afterAll(async () => {
    // Teardown services after all tests
    console.log("Tearing down user management suite.");
  });
});

// Listen for test retry events
testEvents.on("testRetrying", ({ testDescription, nextAttempt }) => {
  console.log(`Retrying "${testDescription}" (attempt ${nextAttempt})`);
});

testEvents.on("testRetried", ({ testDescription, attemptNumber }) => {
  console.log(`Retry attempt finished for "${testDescription}" (attempt ${attemptNumber})`);
});

// To run these tests: npx velocious test spec/path/to/your-test-spec.js