feat: refinements in api generator; initial polytest integration for algod

.github/workflows/check-python.yaml

@@ -35,3 +35,14 @@ jobs:
         run: |
           # stop the build if there are files that don't meet formatting requirements
           uv run poe lint
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: stable
+
+      - name: Install polytest
+        run: cargo install polytest
+
+      - name: Validate polytest algod_client tests
+        run: uv run poe polytest-validate-algod

MIGRATION-NOTES.md

@@ -39,3 +39,114 @@ A collection of notes to consolidate todos during decoupling efforts (similar do
 - What do we do with SourceMap abstraction? AlgoSDK version is more feature complete, while we also have a simple autogenerated sourcemap variant in algosdk. ts currently relies on ProgramSourceMap which is vendored from js algosdk. Do we drop the vendored variants completely and enhance api generator to hand roll a custom sourcemap variant we need and rely on that everywhere? Or do we move the vendored source map variant into the algokit-utils and enhance it there?
 
 - BoxReference used to be a subclass of algosdk BoxReference, now there is a direct equivalent imported from transact package. Do we want to keep aliasing the BoxReference to transact version or do we want to deprecate and advice consumers to import directly from transact?
+
+## Contributing Guide
+
+- Introduce comprehensive contributing guide around running tests/updating snapshots in API client tests and dealing with Polytest
+
+## Polytest Integration
+
+This section tracks the generated API endpoint tests from Polytest. Tests are categorized by implementation status.
+
+### Algod Client Endpoints
+
+#### ✅ Implemented (21 endpoints)
+
+| Endpoint | Test File | Notes |
+|----------|-----------|-------|
+| `GET /genesis` | `test_get_genesis.py` | |
+| `GET /health` | `test_get_health.py` | |
+| `GET /ready` | `test_get_ready.py` | |
+| `GET /versions` | `test_get_versions.py` | |
+| `GET /v2/accounts/{address}` | `test_get_v2_accounts_address.py` | |
+| `GET /v2/accounts/{address}/applications/{application-id}` | `test_get_v2_accounts_address_applications_application_id.py` | |
+| `GET /v2/accounts/{address}/assets/{asset-id}` | `test_get_v2_accounts_address_assets_asset_id.py` | |
+| `GET /v2/accounts/{address}/transactions/pending` | `test_get_v2_accounts_address_transactions_pending.py` | |
+| `GET /v2/applications/{application-id}` | `test_get_v2_applications_application_id.py` | |
+| `GET /v2/assets/{asset-id}` | `test_get_v2_assets_asset_id.py` | |
+| `GET /v2/blocks/{round}` | `test_get_v2_blocks_round.py` | |
+| `GET /v2/blocks/{round}/hash` | `test_get_v2_blocks_round_hash.py` | |
+| `GET /v2/blocks/{round}/lightheader/proof` | `test_get_v2_blocks_round_lightheader_proof.py` | |
+| `GET /v2/blocks/{round}/txids` | `test_get_v2_blocks_round_txids.py` | |
+| `GET /v2/deltas/{round}` | `test_get_v2_deltas_round.py` | |
+| `GET /v2/ledger/supply` | `test_get_v2_ledger_supply.py` | |
+| `GET /v2/ledger/sync` | `test_get_v2_ledger_sync.py` | |
+| `GET /v2/status` | `test_get_v2_status.py` | |
+| `GET /v2/status/wait-for-block-after/{round}` | `test_get_v2_status_wait_for_block_after_round.py` | |
+| `GET /v2/transactions/params` | `test_get_v2_transactions_params.py` | |
+| `GET /v2/transactions/pending` | `test_get_v2_transactions_pending.py` | |
+
+#### ⏳ Stub (Not Implemented) (21 endpoints)
+
+| Endpoint | Test File | Notes |
+|----------|-----------|-------|
+| `DELETE /v2/catchup/{catchpoint}` | `test_delete_v2_catchup_catchpoint.py` | Admin endpoint |
+| `DELETE /v2/ledger/sync` | `test_delete_v2_ledger_sync.py` | Admin endpoint |
+| `GET /v2/applications/{application-id}/box` | `test_get_v2_applications_application_id_box.py` | |
+| `GET /v2/applications/{application-id}/boxes` | `test_get_v2_applications_application_id_boxes.py` | |
+| `GET /v2/blocks/{round}/transactions/{txid}/proof` | `test_get_v2_blocks_round_transactions_txid_proof.py` | |
+| `GET /v2/deltas/{round}/txn/group` | `test_get_v2_deltas_round_txn_group.py` | |
+| `GET /v2/deltas/txn/group/{id}` | `test_get_v2_deltas_txn_group_id.py` | |
+| `GET /v2/devmode/blocks/offset` | `test_get_v2_devmode_blocks_offset.py` | Dev mode only |
+| `GET /v2/experimental` | `test_get_v2_experimental.py` | |
+| `GET /v2/stateproofs/{round}` | `test_get_v2_stateproofs_round.py` | |
+| `GET /v2/transactions/pending/{txid}` | `test_get_v2_transactions_pending_txid.py` | |
+| `POST /v2/catchup/{catchpoint}` | `test_post_v2_catchup_catchpoint.py` | Admin endpoint |
+| `POST /v2/devmode/blocks/offset/{offset}` | `test_post_v2_devmode_blocks_offset_offset.py` | Dev mode only |
+| `POST /v2/ledger/sync/{round}` | `test_post_v2_ledger_sync_round.py` | Admin endpoint |
+| `POST /v2/shutdown` | `test_post_v2_shutdown.py` | Admin endpoint |
+| `POST /v2/teal/compile` | `test_post_v2_teal_compile.py` | |
+| `POST /v2/teal/disassemble` | `test_post_v2_teal_disassemble.py` | |
+| `POST /v2/teal/dryrun` | `test_post_v2_teal_dryrun.py` | |
+| `POST /v2/transactions` | `test_post_v2_transactions.py` | |
+| `POST /v2/transactions/async` | `test_post_v2_transactions_async.py` | |
+| `POST /v2/transactions/simulate` | `test_post_v2_transactions_simulate.py` | |
+
+#### 🔧 Manual Tests (6 tests)
+
+These tests are hand-written to cover complex scenarios not easily generated:
+
+| Test File | Description |
+|-----------|-------------|
+| `manual/test_block.py` | Block endpoint against mainnet/testnet with state proof tracking |
+| `manual/test_ledger_state_delta.py` | Ledger state delta endpoint against mainnet/testnet |
+| `manual/test_pending_transaction_information.py` | Pending transaction info flow on localnet |
+| `manual/test_raw_transaction.py` | Raw transaction broadcast on localnet |
+| `manual/test_simulate_transactions.py` | Transaction simulation with trace config |
+| `manual/test_suggested_params.py` | Suggested params and error handling |
+
+### Indexer Client Endpoints
+
+#### 🔧 Manual Tests (2 tests)
+
+| Test File | Description |
+|-----------|-------------|
+| `manual/test_search_applications.py` | Search for applications and app creation flow |
+| `manual/test_search_transactions.py` | Search and lookup transactions |
+
+### KMD Client Endpoints
+
+#### 🔧 Manual Tests (2 tests)
+
+| Test File | Description |
+|-----------|-------------|
+| `manual/test_wallet_lifecycle.py` | Wallet creation and listing |
+| `manual/test_key_management.py` | Key generation and wallet handle management |
+
+### Test Infrastructure
+
+The Polytest-generated tests use a mock server infrastructure:
+
+- **Mock Server**: Docker container running `algorandfoundation/algod-mock:latest`
+- **Parallel Execution**: Uses `filelock` for xdist worker coordination
+- **Container Management**: Named containers with fixed ports (18000, 18001, 18002)
+- **Test Configuration**: Located in `tests/modules/conftest.py`
+
+### Summary
+
+| Client | Implemented | Stub | Manual | Total |
+|--------|-------------|------|--------|-------|
+| Algod | 21 | 21 | 6 | 48 |
+| Indexer | 0 | 0 | 2 | 2 |
+| KMD | 0 | 0 | 2 | 2 |
+| **Total** | **21** | **21** | **10** | **52** |