> For the complete documentation index, see [llms.txt](https://whitepaper.litho.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://whitepaper.litho.ai/docs/guides/testing-best-practices.md).

# Testing Best Practices

This guide covers the testing toolchain, CI pipeline configuration, security auditing tools, and environment-specific testing strategies for the Lithosphere project.

## Smart Contract Testing Toolchain

Lithosphere uses a dual toolchain approach for smart contract testing:

### Hardhat (v2.19+)

* **TypeScript-native development** -- Write tests and deployment scripts in TypeScript.
* **Hardhat Ignition** -- Declarative deployment system for reproducible contract deployments.
* **hardhat-gas-reporter** -- Gas usage reporting for optimization during test runs.
* **Parallel test execution** -- Run tests concurrently for faster feedback.

### Foundry (Forge)

* **Fast fuzz testing** -- Property-based testing with high throughput.
* **Configurable fuzz runs** -- Default 10,000 fuzz runs in CI for thorough coverage.
* **Solidity-native tests** -- Write tests directly in Solidity for lower-level control.

## Contract CI Pipeline

The CI pipeline for smart contracts runs the following steps in order:

```bash
# 1. Compile contracts
hardhat compile

# 2. Run Hardhat tests in parallel
hardhat test --parallel

# 3. Run Foundry fuzz tests
forge test --fuzz-runs 10000

# 4. Static analysis with Slither
slither . --sarif output.sarif

# 5. Symbolic execution with Mythril
mythril analyze contracts/*.sol
```

## Security Auditing Tools

| Tool    | Type                           | Purpose                                                                             |
| ------- | ------------------------------ | ----------------------------------------------------------------------------------- |
| Slither | Static analysis                | Detect common vulnerabilities, code quality issues, and optimization opportunities. |
| Mythril | Symbolic execution             | Deep analysis of contract bytecode for security vulnerabilities.                    |
| Echidna | Property-based testing/fuzzing | Fuzz testing with user-defined invariants to find edge cases.                       |
| Certora | Formal verification (optional) | Mathematically prove contract properties hold for all inputs.                       |

## Testing Strategy by Environment

| Environment | Test Type            | Details                                                                       |
| ----------- | -------------------- | ----------------------------------------------------------------------------- |
| Local       | Unit tests           | Fast iteration with hot-reload. Run individual test files during development. |
| Devnet      | CI ephemeral testing | Automated tests on short-lived environments with seeded fixtures.             |
| Staging     | Integration testing  | Full integration tests against a persistent testnet with realistic data.      |
| Mainnet     | Smoke tests          | Post-deployment verification with minimal, non-destructive checks.            |

## General Best Practices

* **Test edge cases** -- Cover boundary conditions, zero values, overflow/underflow, and reentrancy scenarios.
* **Use deterministic fixtures** -- Seed test data consistently to ensure reproducible results.
* **Run security scans in CI** -- Never skip Slither or container scanning in the pipeline.
* **Fuzz test critical financial logic** -- Any function handling token transfers, staking, or governance must be fuzz tested.
* **Isolate tests** -- Each test should be independent and not rely on state from other tests.

## Version Pinning Policy

| Component       | Strategy      | Version           |
| --------------- | ------------- | ----------------- |
| Solidity        | Exact version | 0.8.20            |
| Node.js Runtime | LTS           | 20                |
| Security Tools  | Latest stable | Updated regularly |

## Dependency Update Policy

| Cadence   | Scope            | Method                 |
| --------- | ---------------- | ---------------------- |
| Weekly    | Security patches | Dependabot (automated) |
| Monthly   | Minor versions   | Manual review          |
| Quarterly | Major versions   | RFC required           |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://whitepaper.litho.ai/docs/guides/testing-best-practices.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.