> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phylax.systems/llms.txt
> Use this file to discover all available pages before exploring further.
# How to Plan Assertion Testing
> Plan local testing, backtesting, staging, and production promotion for assertions
This guide shows you how to allocate assertion testing effort across local tests, backtesting, staging, and production promotion.
**Summary**
* Local testing validates core logic; staging validates real-world behavior
* Deploy to staging early to observe behavior against real transaction flow
* Real transactions expose scenarios that are difficult to predict locally
* Use backtesting to debug specific transactions with the smallest feedback loop
## The Testing Philosophy
The most effective approach to assertion development prioritizes [staging](/credible/glossary#staging) over exhaustive local testing. In staging, assertions run against real transactions on a mirrored environment but don't drop transactions—allowing you to observe behavior safely. In [production](/credible/glossary#production), assertions actively prevent violations by dropping invalid transactions.
Real-world transactions reveal edge cases that would take significant effort to anticipate and mock locally.
**Why local testing has limits:**
* You can only think of so many test cases manually
* Complex protocol states are difficult to reproduce
* Setting up realistic testing environments for multi-protocol interactions is time-consuming
**Why staging excels:**
* Real usage patterns and transaction diversity
* Edge cases emerge organically from actual user behavior
* Weeks of staging exposure reveals issues that extended local testing might miss
## How to Allocate Your Time
| Phase | Effort | Goal |
| ------------- | -------- | -------------------------------------------------------------- |
| Local testing | \~20-30% | Validate core logic, catch obvious bugs, verify gas limits |
| Backtesting | \~10-20% | Sanity check before staging; debug specific transactions after |
| Staging | \~50-60% | Discover edge cases, observe real-world behavior, iterate |
The bulk of your validation happens in staging. Local testing catches the obvious issues quickly so you can deploy with confidence, but staging is where you discover the edge cases.
## What to Test Locally
Focus local testing on:
* **Happy paths:** Verify assertions pass on valid transactions
* **Known violation scenarios:** Verify assertions catch the specific violations you designed for
* **Gas limits:** Ensure assertions stay within the 300k gas limit, especially on the happy path (which typically uses more gas since all checks run to completion)
**What NOT to over-invest in locally:**
* Exhaustive edge case enumeration
* Complex multi-protocol interaction scenarios
* Simulating every possible user behavior
These are better discovered through staging with real transactions.
See [Testing Assertions](/credible/testing-assertions) for local testing patterns and [Gas Limits](/credible/testing-assertions#gas-limits) for gas considerations.
**Leverage existing invariant tests.** If your protocol already has Forge invariant tests, the test setup and infrastructure can often be reused for assertion testing. This can significantly reduce the time spent on local test configuration.
## Backtesting: Two Key Uses
Backtesting serves two distinct purposes in the development workflow:
### 1. Pre-Staging Sanity Check
Before deploying to staging, run a quick backtest against recent transactions:
* Verifies expected behavior on normal protocol operations
* Catches trigger mismatches (assertion not running when expected)
* Identifies gas issues with realistic transaction complexity
Keep block ranges small (10-100 blocks) for this sanity check. The goal is quick verification, not comprehensive coverage.
For production promotion, expect a broader historical review. The exact window depends on protocol risk, transaction volume, network requirements, and the assertions being promoted. At minimum, include representative high-volume periods, known incident windows when applicable, and enough normal activity to measure assertion behavior on normal transactions.
### 2. Debugging Staging Issues
When staging reveals unexpected behavior, backtesting becomes your debugging tool:
* Replay the specific transaction that triggered the issue locally
* Step through assertion logic with full visibility
* Fastest feedback loop for debugging
This is often faster than trying to reproduce the scenario from scratch in a local test.
See [Backtesting](/credible/backtesting) for configuration and usage details.
## The Staging Workflow
```mermaid theme={null}
flowchart LR
LOCAL[Local Testing] --> BACKTEST[Backtesting
sanity check]
BACKTEST --> STAGING[Deploy to
Staging]
STAGING --> MONITOR[Monitor]
MONITOR --> ISSUE{Issues
Found?}
ISSUE --> |Yes| DEBUG[Backtest
specific tx]
DEBUG --> FIX[Fix & Redeploy]
FIX --> STAGING
ISSUE --> |No, over weeks| PROD[Promote to
Production]
style PROD fill:#27ae60,color:#fff
```
### Deploy Early
Once local tests pass and backtesting shows no obvious issues, [deploy to staging](/credible/deploy-assertions-dapp). Don't wait for "perfect" local coverage—staging will reveal what you missed. Note that deployments have a [timelock](/credible/glossary#timelock) period before assertions become active, so starting early is beneficial.
### Monitor Staging Behavior
Check the [platform dashboard](https://app.phylax.systems) regularly for assertion execution status and enable [incident notifications](/credible/dapp-integrations) to get alerted via Slack or PagerDuty. Look for:
* Unexpected invalidations on legitimate operations
* Assertion behavior that needs tuning before production
Staging runs assertions but does NOT drop transactions, so you can observe behavior without risk.
### Debug with Backtesting
When an issue appears in staging:
1. Identify the transaction that triggered unexpected behavior
2. Use backtesting to replay that exact transaction locally
3. Debug with full visibility into assertion execution (`-vvvv`)
4. Fix the issue and redeploy
**Add regression tests for discovered edge cases.** When staging or backtesting reveals an unexpected scenario, create a local unit test that reproduces the behavior. This prevents regressions and builds a test suite informed by real-world usage patterns rather than speculation.
### Recommended Staging Duration
* **Minimum:** 1-2 weeks before considering production
* **High-traffic protocols:** More transactions means faster feedback
* **Low-traffic protocols:** May need longer staging periods
The goal is sufficient transaction diversity, not a specific timeframe. As the developer, you are best positioned to judge when your assertions have been validated against enough real-world scenarios to warrant promotion to production.
## When to Move to Production
Before promoting to production, verify:
* Expected behavior observed on legitimate transactions
* Sufficient transaction diversity to build confidence
* Historical backtesting covers the relevant protocol surfaces and known risky periods
* Trigger frequency, runtime, and gas usage fit the network's production limits
* You understand how the assertion behaves across different scenarios
Moving to production means transactions that violate your assertion will be dropped. Ensure you have validated behavior thoroughly in staging before promoting.
## Common Mistakes
**Over-investing in local testing:** Trying to cover every edge case locally is inefficient. Staging does this better with real transactions.
**Skipping backtesting entirely:** A quick backtest catches obvious issues before staging and is essential for debugging staging discoveries.
**Deploying directly to production:** Always validate in staging first. Production should only use assertions that have passed staging review.
**Expecting immediate feedback:** Edge cases may take weeks to surface in staging. Be patient and let real usage patterns emerge.
## Next Steps
Local testing patterns and best practices
Test against historical transactions
Deploy assertions to staging or production
Common errors and solutions