mirror of
https://github.com/Chia-Network/chia-blockchain.git
synced 2026-08-24 10:05:29 -05:00
Almog De PazandGitHub
79008d11d5
* context fo cursor * pass with docs refrence, fix line counts and some more and minor fixes * lint * pr comments * fixes
120 lines
6.1 KiB
Plaintext
120 lines
6.1 KiB
Plaintext
---
|
|
description: Detailed block creation, transaction submission, and assertion patterns for Chia tests
|
|
globs:
|
|
- chia/_tests/**
|
|
---
|
|
|
|
# Chia Test Patterns
|
|
|
|
## How We Make Blocks
|
|
|
|
### 1) Deterministic block lists (`BlockTools`)
|
|
|
|
Use `bt.get_consecutive_blocks(...)` when you need exact block structure, specific spend inclusion, or malformed block variants.
|
|
|
|
Common options:
|
|
- `block_list_input=` continue from existing chain
|
|
- `transaction_data=` include a spend bundle
|
|
- `guarantee_transaction_block=True` force tx block
|
|
- `force_overflow`, `skip_slots`, `seed`, `time_per_block`
|
|
|
|
Then add blocks with:
|
|
- `await full_node.add_block(block)` for single steps, or
|
|
- `await add_blocks_in_batches(blocks, full_node)` for larger sets
|
|
|
|
### 2) High-level farming APIs (`FullNodeSimulator`)
|
|
|
|
Use these for behavior tests where exact block internals do not matter:
|
|
- `farm_blocks_to_puzzlehash()`
|
|
- `farm_blocks_to_wallet()`
|
|
- `farm_rewards_to_wallet()`
|
|
- `farm_new_transaction_block()`
|
|
- `reorg_from_index_to_new_index()`
|
|
- `revert_block_height()`
|
|
|
|
### 3) Pre-generated persistent chains
|
|
|
|
Use fixtures like:
|
|
- `default_400_blocks`, `default_1000_blocks`, `default_10000_blocks`
|
|
- reorg variants and compact variants
|
|
|
|
These come from `persistent_blocks(...)` and are used heavily in consensus/timelord/weight proof tests.
|
|
|
|
## How We Submit Transactions
|
|
|
|
### A) Wallet-internal (most common)
|
|
|
|
1. `async with wallet.wallet_state_manager.new_action_scope(..., push=True) as action_scope:`
|
|
2. `await wallet.generate_signed_transaction(...)`
|
|
3. Records from `action_scope.side_effects.transactions`
|
|
4. Wait via `wait_transaction_records_entered_mempool` or `process_pending_states`.
|
|
|
|
### B) Wallet RPC
|
|
|
|
`WalletRpcClient`: `send_transaction(...)`, `create_signed_transactions(...)`, `push_transactions(...)`, `push_tx(...)`.
|
|
|
|
### C) Full node protocol-level
|
|
|
|
Build `wallet_protocol.SendTransaction(spend_bundle)`, send via `full_node_api.send_transaction(...)` with dummy peers from `chia/_tests/connection_utils.py`.
|
|
|
|
### D) CLVM simulator
|
|
|
|
`status, err = await sim_client.push_tx(spend_bundle)`
|
|
|
|
## How We Assert Steps Happened
|
|
|
|
Use layered assertions instead of a single final check:
|
|
|
|
1. **Immediate invariants** — object created, response success, expected fields present.
|
|
2. **Eventual behavior** — `time_out_assert(...)` for async convergence.
|
|
3. **Mempool checks** — `mempool_manager.get_spendbundle(...)`, `assert_sb_in_pool(...)`.
|
|
4. **Wallet transitions** — `process_pending_states(...)` with `WalletStateTransition`.
|
|
5. **Failure paths** — `pytest.raises(...)` with explicit error matching.
|
|
6. **Log assertions** — `caplog` for protocol/service side effects.
|
|
|
|
## Module-by-Module Test Setup Map
|
|
|
|
| Module | Typical Setup | Blocks | Transaction Path | Assertion Style |
|
|
|---|---|---|---|---|
|
|
| `blockchain` | `bt`, `empty_blockchain`, `two_nodes` | `get_consecutive_blocks`, `add_block`, `add_blocks_in_batches` | `WalletTool.generate_signed_transaction`, protocol `send_transaction`, in-block `transaction_data` | direct consensus result checks, `pytest.raises`, occasional `time_out_assert` |
|
|
| `clvm` | no network harness, or `sim_and_client` | `SpendSim.farm_block` | `sim_client.push_tx` | direct CLVM/coin-store assertions, `pytest.raises` |
|
|
| `cmds` | `CliRunner`, `get_test_cli_clients`, temp config roots | usually none | mocked RPC client calls | output assertions, parse/validation errors |
|
|
| `core` | mixed: `one_node_one_block`, `simulator_and_wallet`, data-layer fixtures | heavy use of `get_consecutive_blocks`, farming APIs | wallet-generated spends, protocol `send_transaction`/`respond_transaction` | heavy `time_out_assert`, mempool/state assertions, `caplog`, `pytest.raises` |
|
|
| `db` | `DBConnection`/`PathDBConnection` fixtures | none | none | concurrency/transactionality assertions, `pytest.raises` |
|
|
| `farmer_harvester` | `farmer_one_harvester*`, `harvester_farmer_environment` | minimal | protocol message flow | service-state `time_out_assert`, `caplog` |
|
|
| `fee_estimation` | mostly mempool/unit harness | minimal farming | small generated spend bundles | direct estimator state assertions |
|
|
| `generator` | pure generator/CLVM tests | none | none | deterministic program output/cost assertions |
|
|
| `harvester` | `harvester_farmer_environment` + test plots | `default_400_blocks` for signage data | harvester protocol interactions | `time_out_assert`, mock peer assertions |
|
|
| `pools` | pure puzzle unit tests and wallet/simulator integration | farming + reorg in integration | wallet RPC and framework tx processing | `process_pending_states`, `time_out_assert`, `pytest.raises` |
|
|
| `simulation` | `simulator_and_wallet`, full system fixture | high-level simulator farming/reorg | wallet-generated spends | heavy `time_out_assert`, mempool/coin-store confirmations |
|
|
| `wallet` | `wallet_environments` (primary), simulator fixtures | frequent farming/reorg | wallet action scopes, wallet RPC | `process_pending_states`, `time_out_assert`, mempool checks |
|
|
| `weight_proof` | pre-generated block fixtures + `BlockchainMock` | `get_consecutive_blocks` for edge chains | none | proof validity/fork point assertions |
|
|
|
|
## Agent Templates
|
|
|
|
### Wallet transfer with robust checks
|
|
|
|
1. Use `wallet_environments` with needed prefarm.
|
|
2. Build tx inside `new_action_scope(..., push=True)`.
|
|
3. Call `wallet_environments.process_pending_states([...])` with pre-block and post-block expected deltas.
|
|
|
|
### Protocol/mempool acceptance test
|
|
|
|
1. Create spend bundle (`WalletTool` or wallet action scope).
|
|
2. Submit with `full_node_api.send_transaction(...)` via dummy peer.
|
|
3. Assert mempool inclusion, farm tx block, assert eviction + coin-store updates.
|
|
|
|
### Consensus block validation test
|
|
|
|
1. Build base chain using `bt.get_consecutive_blocks`.
|
|
2. Mutate crafted block (or use transaction conditions).
|
|
3. Validate with `_validate_and_add_block(...)` expecting specific `Err`.
|
|
|
|
## Checklist
|
|
|
|
- Harness matches behavior under test.
|
|
- Async convergence uses `time_out_assert`, not raw sleeps.
|
|
- Wallet behavior uses `process_pending_states` where practical.
|
|
- Mempool and confirmation asserted as separate steps.
|
|
- Failure paths use `pytest.raises` with explicit error matching.
|