OPNet Unit Test Framework

The official unit testing framework for OPNet smart contracts. Test your AssemblyScript contracts against the real OP_VM runtime with full TypeScript support, gas metering, state management, and built-in helpers for OP20/OP721 tokens.

Installation

npm install @btc-vision/unit-test-framework

Documentation

Check out the full documentation in /docs!

• Getting Started - Installation & first test
• Writing Tests - Test patterns & lifecycle
• Built-in Contracts - OP20, OP721, OP721Extended helpers
• Assertions - Static & fluent assertion API
• Blockchain API - Blockchain simulator
• Contract Runtime - Custom contract wrappers
• Advanced Topics - Updates, signatures, gas profiling, consensus rules
• Examples - Real-world test examples
• API Reference - Full type reference

Quick Start

import { opnet, OPNetUnit, Assert, Blockchain, OP20 } from '@btc-vision/unit-test-framework';
import { Address } from '@btc-vision/transaction';

await opnet('My Token Tests', async (vm: OPNetUnit) => {
    let token: OP20;

    const deployer: Address = Blockchain.generateRandomAddress();
    const receiver: Address = Blockchain.generateRandomAddress();

    vm.beforeEach(async () => {
        Blockchain.dispose();
        Blockchain.clearContracts();
        await Blockchain.init();

        token = new OP20({
            address: Blockchain.generateRandomAddress(),
            deployer: deployer,
            file: './path/to/MyToken.wasm',
            decimals: 18,
        });

        Blockchain.register(token);
        await token.init();

        Blockchain.msgSender = deployer;
        Blockchain.txOrigin = deployer;
    });

    vm.afterEach(() => {
        token.dispose();
        Blockchain.dispose();
    });

    await vm.it('should mint tokens', async () => {
        await token.mint(receiver, 1000);

        const balance = await token.balanceOf(receiver);
        Assert.expect(balance).toEqual(Blockchain.expandToDecimal(1000, 18));
    });
});

Run with:

npx tsx test/my-token.test.ts

Requirements

• Node.js >= 22
• Rust toolchain (for building @btc-vision/op-vm)

Development

git clone https://github.com/btc-vision/unit-test-framework.git
cd unit-test-framework
npm install
npm run build

Running Tests

# Run the full test suite (builds test contracts + runs all tests)
npm test

# Run a specific test file
npm run test:update-from-address
npm run test:storage
npm run test:gas
npm run test:ecdsa

Test Contracts

End-to-end test contracts live in test/e2e/contracts/. Each contract has:

• contract/ - AssemblyScript source and asconfig.json
• runtime/ - TypeScript ContractRuntime wrapper

Build test contracts separately:

npm run build:test-contract

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: npm test
5. Submit a pull request

Reporting Issues

• Bugs: Open an issue on GitHub
• Security: See SECURITY.md - do not open public issues for vulnerabilities

Changelog

See CHANGELOG.md for release history.

License

Apache-2.0

Links

• OPNet
• Documentation
• GitHub
• npm