Testing¶

Table of Contents¶

Install Dependencies
Solidity Tests
Frontend Tests
Current Added Coverage
Linting
Build Checks
CI Profiles
Authors and Contributors
Legal

Kevin K. Le (LinkedIn) — Founder, Founding Engineer, and Current Lead Engineer; Software Engineer at the Oregon Blockchain Group, University of Oregon.

Kellen Snider — Founding Engineer; Software Engineer at the Oregon Blockchain Group, University of Oregon. His vision, ideas, and dedication during TrustLedger's Ethereum development were invaluable to the codebase we build on today.

See CREDITS.md.

This document explains how to run TrustLedger tests and quality gates. Use it before opening a PR or debugging a failing GitHub Actions job.

Install Dependencies¶

Home · Top · Table of Contents

npm install
cd src
npm install
cd ..

Solidity Tests¶

Home · Top · Table of Contents

Run all Foundry tests:

npm run foundry:test

Run the staging Foundry profile:

npm run foundry:test:staging

Run Foundry fork tests:

npm run foundry:test:fork

The default fork command is sandbox-safe and skips live RPC execution unless it is explicitly enabled. Run live fork tests with:

npm run foundry:test:fork:live

Live Foundry fork tests read SEPOLIA_RPC_URL and FORK_BLOCK_NUMBER directly. Set SEPOLIA_RPC_URL before running fork tests that require live Sepolia state. tools/foundry-sandbox.mjs strips proxy-related environment variables before invoking forge, which avoids macOS system proxy access panics in sandboxed agent sessions.

Run Hardhat TypeScript/Mocha tests:

npm run hardhat:test

Hardhat forks only when FORK_URL is set. Otherwise it uses a fresh in-memory chain. Foundry owns Solidity .t.sol execution; npm run hardhat:test runs the Hardhat Mocha subtask so the same Solidity suites are not double-run through Hardhat. Use npm run foundry:gas for gas reports; hardhat-gas-reporter still peers on Hardhat 2 and is intentionally not installed in the Hardhat 3 toolchain. Use Foundry deploy scripts with --verify for explorer verification because the Hardhat 3 verify plugin currently reintroduces unfixed ethers v5 advisories.

Frontend Tests¶

Home · Top · Table of Contents

Run unit tests:

cd src
npm run test:unit

Run the strict locale and visible-copy scanner:

npm run i18n:scan

Install the Chromium browser used by Playwright:

cd src
npm run install:playwright

Run Playwright E2E tests:

cd src
npm run test:e2e

The Playwright web server binds to localhost by default to avoid managed sandbox failures on direct 127.0.0.1 binds. Set PLAYWRIGHT_WEB_SERVER_HOST=127.0.0.1 only when a runner requires IPv4 loopback.

Run the interactive Playwright UI:

cd src
npm run test:e2e:ui

Run headed browser tests:

cd src
npm run test:e2e:headed

Sandboxed agent sessions may block DNS for external wallet metadata endpoints such as Reown/Web3Modal. Frontend builds must treat those fetch failures as non-fatal fallback warnings, not application errors. For live wallet-provider checks that genuinely require network access, run the specific command with an approved sandbox escalation and keep the command scoped to the frontend test or build being verified.

Current Added Coverage¶

Home · Top · Table of Contents

The current testing sweep added focused frontend tests for:

Legal document localization and translation prompt guardrails.
Solana cluster resolution, address-shape validation, and Explorer URLs.
Home-page interactive contract preview phase selection and CTA advancement.

These tests complement existing wallet, validation, health, oracle, route, contract-error, and public route checks.

Linting¶

Home · Top · Table of Contents

Run all root lint checks:

npm run lint

Run frontend lint checks:

npm run lint:frontend

Run Solidity lint checks:

npm run lint:sol
npm run lint:forge

Run markdown lint checks:

npm run lint:md

Run ignored local artifact retention checks:

npm run lint:logs
npm run tmp:check

Run direct log retention checks:

npm run logs:check

Run Python docstring and type checks for the project-owned Python helper scripts:

npm run lint:py

npm run lint:py runs tools/check-python-docstrings.py before mypy. The docstring gate scans only project-owned Python files and excludes vendored contract libraries, generated outputs, caches, and dependency directories.

Build Checks¶

Home · Top · Table of Contents

Compile Hardhat contracts:

npm run compile

Build Foundry contracts:

npm run foundry:build

Build the frontend:

cd src
npm run build:frontend

CI Profiles¶

Home · Top · Table of Contents

The Solidity CI workflow uses FOUNDRY_PROFILE=ci, which lowers fuzz runs to keep CI fast. The default local Foundry profile runs more fuzz cases. The staging profile keeps production optimizer settings with intermediate fuzz and invariant coverage.

Authors and Contributors¶

Home · Top · Table of Contents

Kevin K. Le — Founder, Founding Engineer, and Current Lead Engineer (LinkedIn)
Kellen Snider — Founding Engineer (LinkedIn)

See CREDITS.md for the complete acknowledgement list.

Legal¶

Home · Top · Table of Contents

This document is part of TrustLedger, an open-source decentralized escrow and arbitration protocol. Use of this software and documentation is subject to the Terms and Conditions, Privacy Policy, and Risk Disclosure. See LEGAL.md for the full compliance and licensing overview.