FizzBee Model Based Testing (MBT) - TypeScript

TypeScript/JavaScript binding for FizzBee Model Based Testing framework.

Installation

npm install @fizzbee/mbt

Quick Start

1. Define Your Model

Implement the Model interface to define your system under test:

import { Model, RoleId, Role } from '@fizzbee/mbt';

class MyModel implements Model {
  private roles: Map<string, Role> = new Map();

  async init(): Promise<void> {
    // Initialize your model
    console.log('Initializing model...');
  }

  async cleanup(): Promise<void> {
    // Clean up resources
    console.log('Cleaning up model...');
  }

  async getRoles(): Promise<Map<string, Role>> {
    return this.roles;
  }
}

2. Define Actions

Actions are the operations that can be performed on your model:

import { ActionFunc } from '@fizzbee/mbt';

// Example action that operates on the model
async function myAction(instance: MyModel, args: any[]): Promise<any> {
  // Implement your action logic
  console.log('Executing action with args:', args);
  return { success: true };
}

// Create action registry
const actionsRegistry = new Map<string, Map<string, ActionFunc>>();
const modelActions = new Map<string, ActionFunc>();
modelActions.set('myAction', myAction);
actionsRegistry.set('', modelActions); // Empty string for model-level actions

3. Run Tests

import { runTests } from '@fizzbee/mbt';

// Run the tests
const model = new MyModel();
const options = {
  'max-seq-runs': 100,
  'max-parallel-runs': 50,
  'max-actions': 1000
};

runTests(model, actionsRegistry, options)
  .then(() => console.log('Tests completed successfully'))
  .catch(error => {
    console.error('Tests failed:', error);
    process.exit(1);
  });

Core Concepts

Model

The Model interface represents your system under test. It must implement:

• init(): Initialize the model before each test run
• cleanup(): Clean up after each test run
• getRoles(): Return all role instances
• getState(): Return the current state for verification

Roles

Roles represent individual components or actors in your system. Each role should implement the Role interface.

Actions

Actions are functions that can be executed on roles or the model itself. They have the signature:

type ActionFunc = (instance: any, args: any[]) => Promise<any>;

State Management

Implement StateGetter or SnapshotStateGetter to enable state verification:

• StateGetter.getState(): Returns current state (not necessarily thread-safe)
• SnapshotStateGetter.snapshotState(): Returns a consistent snapshot (thread-safe)

If both are implemented, snapshotState() takes precedence.

Configuration

All configuration is done through environment variables or the options object passed to runTests().

Environment Variables

Test configuration can be overridden with environment variables:

• FIZZBEE_MBT_BIN: Path to the fizzbee-mbt-runner binary
• FIZZBEE_MBT_MAX_SEQ_RUNS: Override max-seq-runs option
• FIZZBEE_MBT_MAX_PARALLEL_RUNS: Override max-parallel-runs option
• FIZZBEE_MBT_MAX_ACTIONS: Override max-actions option
• FIZZBEE_MBT_SEQ_SEED: Random seed for sequential tests
• FIZZBEE_MBT_PARALLEL_SEED: Random seed for parallel tests

Example:

export FIZZBEE_MBT_BIN=/path/to/fizzbee-mbt-runner
export FIZZBEE_MBT_MAX_SEQ_RUNS=100
export FIZZBEE_MBT_SEQ_SEED=12345

node my-test.js

RunTestsOptions

Options can be provided programmatically:

const options: RunTestsOptions = {
  'max-seq-runs': 100,
  'max-parallel-runs': 50,
  'max-actions': 1000,
  'seq-seed': 12345,
  'parallel-seed': 67890
};

await runTests(model, actionsRegistry, options);

Environment variables take precedence over options passed to runTests().

Development

Building from Source

# Install dependencies
npm install

# Generate proto files
npm run generate-proto

# Build TypeScript
npm run build

Project Structure

typescript/
├── src/
│   ├── index.ts           # Main exports
│   ├── interfaces.ts      # Core interfaces
│   ├── types.ts           # Type definitions
│   ├── value.ts           # Value conversion utilities
│   ├── plugin-service.ts  # gRPC service implementation
│   └── runner.ts          # Test runner
├── proto-gen/             # Generated protobuf files
├── scripts/
│   └── generate-proto.js  # Proto generation script
├── package.json
├── tsconfig.json
└── README.md

Examples

See the examples/ directory in the FizzBee repository for complete examples.

License

Apache-2.0

Contributing

Contributions are welcome! Please see the main FizzBee repository for contribution guidelines.