Testing Guide

Testing is the backbone of Matador's security model. Given the critical nature of permission management, we employ a multi-layered testing strategy encompassing unit tests, fuzzing, and integration scenarios.

1. Smart Contract Testing

The on-chain components are tested using Foundry, which provides blazing-fast execution and property-based fuzzing.

Unit Tests

Located in contracts/tests/core/, these tests verify the individual logic of each opcode and module.

# Run all unit tests
forge test --match-path "contracts/tests/core/*"

Fuzzing & Invariants

We use Foundry's fuzzing engine to test the interpreter against random inputs and stateful invariants (e.g., "The stack depth never exceeds 16").

# Run fuzz tests
forge test --match-contract Fuzz

Integration Tests

Located in contracts/tests/integration/, these tests simulate real-world interactions with protocols like Uniswap and Aave, ensuring end-to-end correctness.

# Run a specific integration test
forge test --match-path contracts/tests/integration/UniswapV3Enforcement.t.sol -vv

2. DSL Compiler Testing

The TypeScript compiler stack is tested using Vitest.

Intermediate Representation (IR) & Encoding

Verifies that the AST is correctly lowered to IR and that the binary encoder produces the expected bytecode.

npm run test --workspace=packages/core

Grammar & Validation

Ensures that valid .matador syntax is accepted and invalid code (e.g., type mismatches) generates the correct diagnostics.

npm run test --workspace=packages/language

End-to-End Workflow

Tests the CLI commands (compile, format) against sample projects to ensure a smooth developer experience.

npm run test --workspace=packages/cli

3. Documentation Testing

We treat documentation as code.

Type Checking: All code snippets in the docs are subject to verification (WIP).
Link Validation: We run a link checker in CI to ensure no broken internal or external references.
Build Check: The npm run build command in the docs/ directory ensures the site generates without errors.

CI/CD Pipeline

Every Pull Request triggers a comprehensive GitHub Actions workflow:

Build: Compiles all packages and contracts.
Lint: Checks for code style violations (Solhint, Prettier).
Test: Runs the full suite of Foundry and Vitest tests.
Docs: Builds the documentation site preview.

Coverage Requirements

We maintain a strict >90% code coverage requirement for the core interpreter and compiler logic. PRs that decrease coverage may be rejected.