Execution

Runner

The Runner orchestrates suite execution. Its constructor takes a RunnerOptions object with properties for the run ID, data directory, suite definition, step registry, log adapter, and more. Once configured, call run() to start execution.

const runner = new Runner({
  id: 'run-001',
  dataDirectory: './test-data',
  suite: suiteDefinition,
  stepRegistry: registry,
  logAdapter: new LogAdapterConsole({ levelName: 'info' }),
  maxParallelSteps: 20,
  parallelExecution: true,
  testMode: false
})
await runner.run()

Execution Modes

BitDiver supports two execution modes that determine how steps and testcases are iterated.

Batch Mode (default)

In batch mode the runner iterates steps first, then testcases per step. All testcases execute step 1 (in parallel), then all testcases execute step 2, and so on. This is the default mode and is best suited for parallel execution because all testcases at a given step level can run concurrently without inter-step dependencies.

Normal Mode

In normal mode the runner iterates testcases first, then steps within each testcase. Testcase 1 runs all of its steps sequentially, then testcase 2 runs all of its steps, and so on. This mode is useful when a testcase’s steps have sequential dependencies on each other.

Set the execution mode via the executionMode property on the runner or in the suite definition.

Parallel Execution

The default concurrency limit is 20 testcases running in parallel. You can configure this globally via the maxParallelSteps option in RunnerOptions. Individual steps can also override the global limit by setting their own maxParallelSteps property, which is useful when a particular step interacts with a resource that has its own concurrency constraints.

Under the hood, the custom pAll() function manages concurrent promise execution, ensuring that no more than the configured number of testcases are processed simultaneously for a given step.

Progress Reporting

BitDiver includes built-in progress meters that display execution progress in the console. The available implementations are:

  • ProgressBarConsoleBatch — Simple console progress bar showing step and testcase completion.
  • ProgressBarConsoleLogBatch — Console progress bar combined with inline log output.
  • ProgressBarConsoleLogBatchJson — JSON-formatted progress output, ideal for machine-readable CI pipelines.

Assign a progress bar instance to the runner before calling run() to enable progress reporting during execution.

Suite Builder

For declarative suite creation from YAML or JSON configuration files, use createSuiteFromConfig. The configuration divides a suite into three phases:

  • setup — Steps that run sequentially at the beginning (e.g., environment initialization, database clearing).
  • timed — Steps that are auto-scanned from testcase data and run during the main execution phase.
  • teardown — Steps that run sequentially at the end (e.g., result export, validation).
suiteTypes:
  TEST_FIX:
    setup: [SetupEnv, ClearDB]
    timed: auto
    teardown: [ExportResults, CheckResults]
timedStepMapping:
  kafka: SendKafkaTime
  http: SendHttpTime

When timed is set to auto, the suite builder scans each testcase’s data for keys that match entries in timedStepMapping and automatically includes the corresponding step classes. This keeps the configuration concise while allowing testcase data to drive which timed steps are included.

Test Mode

When testMode: true is set in the runner options, StepTimed instances skip their configured delays. This is useful for dry-runs and CI environments where you want to validate the full execution flow without waiting for real timing intervals. All other step behavior remains unchanged, so test mode gives you a fast, faithful representation of the suite’s execution path.

← Step Types Check & Results →