Quickstart

Get up and running with BitDiver in 5 minutes. This guide walks you through installing the framework, writing your first step, and executing a test suite.

Installation

Install the runner package from npm. It includes the core model, definition types, and log adapters as transitive dependencies.

npm install @xhubio/bitdiver-runner

Your First Step

Steps are the basic execution units in BitDiver. A StepNormal runs once per test case in the suite. Create a file called HelloStep.ts:

import { StepNormal } from '@xhubio/bitdiver-runner'

class HelloStep extends StepNormal {
  async run() {
    await this.logInfo('Hello from BitDiver!')
    const name = this.tc.name
    await this.logInfo(`Running testcase: ${name}`)
  }
}

The run() method is the heart of a step. It is called during the step lifecycle after start() and beforeRun(). You have access to the current test case context via this.tc and shared run-level state via this.environment.

Register Steps

Before the runner can use your steps, you need to register them in a StepRegistry. The registry maps step class names to their implementations:

import { StepRegistry } from '@xhubio/bitdiver-runner'

const registry = new StepRegistry()
registry.registerStep({ stepName: 'hello', step: HelloStep })

You can register as many steps as you need. Each step name must be unique within the registry.

Define a Suite

A suite definition is a JSON object that describes which steps to run and which test cases to execute. Create a file called suite.json:

{
  "name": "my-first-suite",
  "steps": ["hello"],
  "stepDefinitions": {
    "hello": {
      "name": "hello",
      "class": "hello",
      "type": "normal"
    }
  },
  "testcases": [
    { "name": "TC-001", "data": {} },
    { "name": "TC-002", "data": {} }
  ]
}

The steps array controls the execution order. Each entry in stepDefinitions maps a step name to its class (as registered in the StepRegistry) and its type (normal or single). The testcases array defines the individual test cases that every normal step will iterate over.

Run the Suite

Now wire everything together. Create a run.ts file that loads the suite definition, configures a log adapter, and starts the runner:

import { Runner, LogAdapterConsole } from '@xhubio/bitdiver-runner'

const runner = new Runner({
  id: 'run-001',
  dataDirectory: './data',
  suite: suiteDefinition,
  stepRegistry: registry,
  logAdapter: new LogAdapterConsole({ levelName: 'info' })
})

await runner.run()

The runner will process each step in order, executing normal steps once per test case and single steps once per suite. Progress and log output are routed through the configured log adapter.

Next Steps

Now that you have a working suite, dive deeper into the framework:

  • Core Concepts — Understand the execution model, environments, and the step lifecycle.
  • Configuration — Learn about all available runner options and environment setup.
  • Step Types — Explore the differences between normal steps, single steps, and how to choose the right one.
Core Concepts →