npm package: @fizzbee/mbt
Description: FizzBee Model Based Testing (MBT) TypeScript/JavaScript binding
Author: FizzBee Team
Latest version: 0.1.2

# FizzBee Model Based Testing (MBT) - TypeScript

TypeScript/JavaScript binding for FizzBee Model Based Testing framework.

## Installation

```bash
npm install @fizzbee/mbt
```

## Quick Start

### 1. Define Your Model

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

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

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

### 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:

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

### RunTestsOptions

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

### Building from Source

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