Skip to Content
Testing

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

ChangeRun
Soliditymake test or pnpm test, which includes the invariants
Share accounting or stock logicAlso make test-invariant-deep
Server or @tap/unitspnpm lint, pnpm typecheck, and pnpm test:units
Apppnpm --filter tap-app lint, pnpm --filter tap-app typecheck, and pnpm app:build
App flowspnpm app:test:e2e, which runs Playwright against a mocked API on desktop, iPad, and iPhone
Docspnpm --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

WorkflowWhenRuns
ci.yml, Node jobPull requests and pushes to mainpnpm lint, pnpm --filter tap-docs lint, pnpm --filter tap-app lint, pnpm --filter tap-app typecheck, pnpm test:units
ci.yml, Foundry jobPull requests and pushes to mainforge test, including the invariants
security.ymlChanges to Solidity files or chain/foundry.tomlforge 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

AreaFiles in chain/test
Cap table setupCapTable.t.sol, CapTableFactory.t.sol, Issuer.t.sol
Access controlAccessControl.t.sol, Wallet.t.sol
Stock transactionsStockIssuance.t.sol, StockTransfer.t.sol, StockCancellation.t.sol, StockRepurchase.t.sol, StockReissuance.t.sol, StockRetraction.t.sol, StockAcceptance.t.sol
Setup records and seedingStakeholder.t.sol, StockClass.t.sol, Minting.t.sol
Authorized-share adjustmentsAdjustment.t.sol
Invariantsinvariants/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:

InvariantChecks that
issuerSharesIssuedNeverExceedsAuthorizedThe issuer’s issued shares stay within its authorized shares.
stockClassSharesConsistencyEach class’s issued shares stay within its authorized shares.
stockClassAuthorizedNeverExceedsIssuerEach class’s authorized shares stay within the issuer’s.
issuerSharesIssuedEqualsSumOfStockClassesThe issuer’s issued shares equal the sum across classes.
activePositionsMatchStockClassSharesIssuedLive holdings in each class equal that class’s issued shares.
stakeholderIndexConsistencyEach stakeholder’s index points back to it.
stockClassIndexConsistencyEach stock class’s index points back to it.
stakeholderCountConsistencyThe contract’s stakeholder count matches the handler’s.
stockClassCountConsistencyThe 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.

Last updated on