===========================================
POP TEST CHAIN
===========================================

Test a chain runtime

Usage: pop test [OPTIONS] [PATH] [FILTER]
       pop test <COMMAND>

Commands:
  on-runtime-upgrade  Test migrations
  execute-block       Executes the given block against some state
  fast-forward        Executes a runtime upgrade (optional), then mines a number of blocks while
                      performing try-state checks
  create-snapshot     Create a chain state snapshot

Arguments:
  [PATH]  Directory path without flag for your project [default: current directory]

Options:
  -p, --path <PATH>  Directory path for your project [default: current directory]
  -h, --help         Print help
  [FILTER]           Run with the specified test filter

===========================================
TEST COMMANDS
===========================================

on-runtime-upgrade:
Test runtime migrations before deployment

execute-block:
Execute historical block against chain state

fast-forward:
Mine blocks while checking runtime state

create-snapshot:
Capture chain state for testing

===========================================
ON-RUNTIME-UPGRADE
===========================================

Test migrations before deploying runtime upgrade

Usage: pop test on-runtime-upgrade [OPTIONS] [COMMAND]

Commands:
  live  Test against live chain
  snap  Test against state snapshot

Options:
  --checks [<CHECKS>]               Select checks [default: pre-and-post]
                                    Values: none, all, pre-and-post, try-state
  --no-weight-warnings              Disable weight warnings (relay chain)
  --disable-spec-version-check      Skip spec_version enforcement
  --disable-spec-name-check         Skip spec_name enforcement
  --disable-idempotency-checks      Skip migration idempotency checks
  --print-storage-diff              Print storage diff for non-idempotent migrations
  --disable-mbm-checks              Skip multi-block migration checks
  --mbm-max-blocks <N>              Max blocks for MBMs [default: 600]
  --blocktime <MS>                  Chain blocktime in ms [default: 6000]
  --runtime <RUNTIME>               Runtime to use [default: existing]
  --profile <PROFILE>               Build profile [default: release]
  -n, --no-build                    Skip rebuilding runtime
  -y, --skip-confirm                Auto-source binaries

Test against live chain:
pop test on-runtime-upgrade live [OPTIONS]
  -u, --uri <URI>                   Chain URL to connect
  -a, --at <AT>                     Block hash to fetch state
  -p, --pallet <PALLET>...          Specific pallets to test

Test against snapshot:
pop test on-runtime-upgrade snap [OPTIONS]
  -p, --path <PATH>                 Path to snapshot file

===========================================
FAST-FORWARD
===========================================

Execute runtime upgrade and mine blocks with try-state checks

Usage: pop test fast-forward [OPTIONS] [COMMAND]

Commands:
  live  Test against live chain
  snap  Test against state snapshot

Options:
  --n-blocks <N>                    Number of empty blocks to process
  --blocktime <MS>                  Chain blocktime in ms [default: 6000]
  --try-state <TRY_STATE>           Which try-state targets to execute
  --run-migrations                  Run pending migrations before fast-forward
  --runtime <RUNTIME>               Runtime to use [default: existing]
  --disable-spec-name-check         Skip spec_name enforcement
  --profile <PROFILE>               Build profile [default: release]
  -n, --no-build                    Skip rebuilding runtime
  -y, --skip-confirm                Auto-source binaries

===========================================
EXECUTE-BLOCK
===========================================

Execute specific block against chain state

Usage: pop test execute-block [OPTIONS]

Options:
  -u, --uri <URI>                   Chain URL to connect
  -a, --at <AT>                     Block hash to fetch state
  -p, --pallet <PALLET>...          Specific pallets to scrape
  --prefix <HASHED_PREFIXES>...     Storage key prefixes (0x hex)
  --child-tree                      Fetch child keys
  --try-state <TRY_STATE>           Which try-state targets to execute
  --runtime <RUNTIME>               Runtime to use [default: existing]
  --profile <PROFILE>               Build profile [default: release]
  -n, --no-build                    Skip rebuilding runtime
  -y, --skip-confirm                Auto-source binaries

===========================================
CREATE-SNAPSHOT
===========================================

Create chain state snapshot for testing

Usage: pop test create-snapshot [OPTIONS] [SNAPSHOT_PATH]

Arguments:
  [SNAPSHOT_PATH]  Path to write snapshot file

Options:
  -u, --uri <URI>                   Chain URL to connect
  -a, --at <AT>                     Block hash to fetch state
  -p, --pallet <PALLET>...          Specific pallets to scrape
  --prefix <HASHED_PREFIXES>...     Storage key prefixes (0x hex)
  --child-tree                      Fetch child keys
  -y, --skip-confirm                Auto-source binaries

===========================================
USAGE
===========================================

# Test migrations on live chain
pop test on-runtime-upgrade live \
  --uri wss://paseo-rpc.dwellir.com

# Test migrations from snapshot
pop test on-runtime-upgrade snap \
  --path ./snapshot.json

# Fast-forward 100 blocks
pop test fast-forward live \
  --uri wss://paseo-rpc.dwellir.com \
  --n-blocks 100

# Execute specific block
pop test execute-block \
  --uri wss://paseo-rpc.dwellir.com \
  --at 0xabc123...

# Create snapshot at specific block
pop test create-snapshot ./my-snapshot.json \
  --uri wss://paseo-rpc.dwellir.com \
  --at 0xabc123...

===========================================
WORKFLOW: TESTING RUNTIME UPGRADE
===========================================

IMPORTANT: Requires runtime built with --try-runtime flag

Step 1: Build runtime with try-runtime:
pop build --release --try-runtime

Step 2: Create snapshot (optional but recommended):
pop test create-snapshot ./snapshot.json \
  --uri wss://paseo-rpc.dwellir.com

Step 3: Test migrations:
pop test on-runtime-upgrade snap \
  --path ./snapshot.json

Step 4: Test with all checks:
pop test on-runtime-upgrade snap \
  --path ./snapshot.json \
  --checks all

Step 5: Fast-forward blocks to verify:
pop test fast-forward snap \
  --path ./snapshot.json \
  --n-blocks 100 \
  --run-migrations

Step 6: If all pass, deploy to production

===========================================
CHECKS EXPLAINED
===========================================

--checks <value>:

none:
- No runtime checks performed
- Fastest execution
- Only for quick validation

pre-and-post (default):
- Pre-upgrade checks
- Post-upgrade checks
- Validates state consistency

all:
- Pre-upgrade checks
- Post-upgrade checks
- Try-state checks
- Most comprehensive

try-state:
- Only try-state checks
- Validates pallet invariants

===========================================
IDEMPOTENCY CHECKS
===========================================

What: Verifies migrations produce same result when run twice

Why: Ensures migrations are safe to re-run

--disable-idempotency-checks:
- Skip idempotency validation
- Use only if certain migrations are idempotent

--print-storage-diff:
- When idempotency fails, show storage differences
- Helps debug non-idempotent migrations

===========================================
MULTI-BLOCK MIGRATIONS (MBM)
===========================================

What: Migrations that span multiple blocks

--disable-mbm-checks:
- Skip multi-block migration execution
- Use if no MBMs in runtime

--mbm-max-blocks <N>:
- Max blocks to execute MBMs [default: 600]
- Increase if MBMs take longer

--blocktime <MS>:
- Chain blocktime in milliseconds [default: 6000]
- Adjust for your chain's block time

===========================================
EXAMPLES
===========================================

# Quick migration test (snapshot)
pop build --release --try-runtime
pop test create-snapshot ./snap.json --uri wss://paseo-rpc.dwellir.com
pop test on-runtime-upgrade snap --path ./snap.json

# Comprehensive migration test
pop test on-runtime-upgrade snap \
  --path ./snap.json \
  --checks all \
  --print-storage-diff

# Test specific pallets only
pop test on-runtime-upgrade live \
  --uri wss://paseo-rpc.dwellir.com \
  --pallet Balances \
  --pallet Staking

# Fast-forward with migration
pop test fast-forward snap \
  --path ./snap.json \
  --n-blocks 50 \
  --run-migrations \
  --try-state All

# Execute specific block
pop test execute-block \
  --uri wss://paseo-rpc.dwellir.com \
  --at 0xabc123... \
  --try-state All

# Create full state snapshot
pop test create-snapshot ./full-state.json \
  --uri wss://paseo-rpc.dwellir.com

# Create partial snapshot (specific pallets)
pop test create-snapshot ./partial-state.json \
  --uri wss://paseo-rpc.dwellir.com \
  --pallet Balances \
  --pallet System

===========================================
TROUBLESHOOTING
===========================================

Error: "try-runtime feature not enabled":
Solution: Build with try-runtime flag
pop build --release --try-runtime

Error: "spec_version not greater":
Solution: Use --disable-spec-version-check
pop test on-runtime-upgrade snap --path ./snap.json --disable-spec-version-check

Error: "Migration not idempotent":
Solution: Debug with storage diff
pop test on-runtime-upgrade snap --path ./snap.json --print-storage-diff

Error: Connection refused:
Solution: Check URI and network connectivity
pop test on-runtime-upgrade live --uri wss://correct-url.com

Snapshot too large:
Solution: Scrape specific pallets only
pop test create-snapshot ./snap.json --uri wss://... --pallet Balances

===========================================
BEST PRACTICES
===========================================

1. Always test migrations before production:
   - Create snapshot from production chain
   - Test on snapshot, not live chain
   - Use --checks all for comprehensive validation

2. Version control snapshots:
   - Commit snapshots for reproducible tests
   - Tag snapshots with block number and date

3. CI/CD integration:
   ```yaml
   - name: Test runtime upgrade
     run: |
       pop build --release --try-runtime
       pop test on-runtime-upgrade snap --path ./snap.json
   ```

4. Test with realistic state:
   - Use production snapshot
   - Or use testnet snapshot
   - Not empty state

5. Validate idempotency:
   - Never disable idempotency checks in production
   - Fix non-idempotent migrations

===========================================
NEXT STEPS
===========================================

After successful tests:

# Build deterministic runtime for governance
pop build --deterministic

# Deploy runtime upgrade
# (via governance or sudo)

See: build/chain.txt, up/chain.txt
