Testing
Contracts compile with Solidity 0.8.37 for the osaka EVM, which matches Plume’s Fusaka upgrade, using Foundry v1.8.3. The compiler settings are in chain/foundry.toml, and CI and pnpm setup install the same Foundry release.
Before a pull request
| Change | Run |
|---|---|
| Solidity | make test or pnpm test, which includes the invariants |
| Share accounting or stock logic | Also make test-invariant-deep |
Server or @tap/units | pnpm lint, pnpm typecheck, and pnpm test:units |
| App | pnpm --filter tap-app lint, pnpm --filter tap-app typecheck, and pnpm app:build |
| App flows | pnpm app:test:e2e, which runs Playwright against a mocked API on desktop, iPad, and iPhone |
| Docs | pnpm --filter tap-docs lint and pnpm docs:build |
pnpm --filter tap-app test:nav runs a few small app unit tests. It’s optional, for local use, and never runs in CI.
make build compiles the contracts, and make test-v runs the Solidity tests with verbose output.
What CI runs
| Workflow | When | Runs |
|---|---|---|
ci.yml, Node job | Pull requests and pushes to main | pnpm lint, pnpm --filter tap-docs lint, pnpm --filter tap-app lint, pnpm --filter tap-app typecheck, pnpm test:units |
ci.yml, Foundry job | Pull requests and pushes to main | forge test, including the invariants |
security.yml | Changes to Solidity files or chain/foundry.toml | forge test --mt invariant -vvv |
CI doesn’t typecheck the server, build the app or docs, or run e2e tests, so run those locally. Root pnpm lint skips docs/, which is why docs lint is a separate step.
Solidity tests
| Area | Files in chain/test |
|---|---|
| Cap table setup | CapTable.t.sol, CapTableFactory.t.sol, Issuer.t.sol |
| Access control | AccessControl.t.sol, Wallet.t.sol |
| Stock transactions | StockIssuance.t.sol, StockTransfer.t.sol, StockCancellation.t.sol, StockRepurchase.t.sol, StockReissuance.t.sol, StockRetraction.t.sol, StockAcceptance.t.sol |
| Setup records and seeding | Stakeholder.t.sol, StockClass.t.sol, Minting.t.sol |
| Authorized-share adjustments | Adjustment.t.sol |
| Invariants | invariants/CapTableInvariants.t.sol, invariants/CapTableHandler.sol |
Invariants
The invariant suite fuzzes a handler that creates stakeholders and stock classes; issues, seeds, transfers, cancels, retracts, reissues, and repurchases stock; and adjusts authorized shares. After every call it checks:
| Invariant | Checks that |
|---|---|
issuerSharesIssuedNeverExceedsAuthorized | The issuer’s issued shares stay within its authorized shares. |
stockClassSharesConsistency | Each class’s issued shares stay within its authorized shares. |
stockClassAuthorizedNeverExceedsIssuer | Each class’s authorized shares stay within the issuer’s. |
issuerSharesIssuedEqualsSumOfStockClasses | The issuer’s issued shares equal the sum across classes. |
activePositionsMatchStockClassSharesIssued | Live holdings in each class equal that class’s issued shares. |
stakeholderIndexConsistency | Each stakeholder’s index points back to it. |
stockClassIndexConsistency | Each stock class’s index points back to it. |
stakeholderCountConsistency | The contract’s stakeholder count matches the handler’s. |
stockClassCountConsistency | The contract’s stock class count matches the handler’s. |
The handler keeps inputs within the share caps, so stockClassSharesConsistency and stockClassAuthorizedNeverExceedsIssuer depend on it as well as on the contract; see What the contracts don’t enforce. The default campaign is 256 runs at depth 50, set in chain/foundry.toml, and make test-invariant-deep runs 2000 at depth 100.