FizzBee Model Based Testing (MBT) - TypeScript

TypeScript/JavaScript binding for FizzBee Model Based Testing framework.

Installation

``bash
npm install @fizzbee/mbt
`

Quick Start

$3

Implement the Model interface to define your system under test:

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

class MyModel implements Model {
private roles: Map = new Map();

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

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

async getRoles(): Promise> {
return this.roles;
}
}
`

$3

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

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

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

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

$3

`typescript
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

$3

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

$3

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

$3

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

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

$3

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().

$3

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:
`bash
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
`

$3

Options can be provided programmatically:

`typescript
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

$3

`bash


Install dependencies

npm install

Generate proto files

npm run generate-proto

Build TypeScript

npm run build
`

$3

`
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.