feat: refinements in api generator; initial polytest integration for algod by aorumbayev · Pull Request #222 · algorandfoundation/algokit-utils-py

aorumbayev · 2025-11-28T23:54:01Z

WIP draft, remaining polytest tests are still being implemented

Notes

Depends on fixes in fix: fixes casing of version strings joe-p/polytest#57 being merged
Depends on fix: updates client config versions to 0.6.0 algokit-polytest#15 ( merged )
Depends on latest spec refinements in fix: more oas refinement algokit-oas-generator#3
Relies on yet to be discussed ci: adds shared reusable setup polytest and mock server actions algokit-polytest#18 which includes:
- mock server pulled from ghcr
- setup polytest moved to shared action on algokit-polytest repo

…field

- Only set format=msgpack when msgpack is explicitly selected - Remove unnecessary format=json assignments for JSON-only endpoints - Align with TypeScript client behavior

Generated output from updated client.py.j2 template: - Remove format=json for endpoints that only support JSON - Simplify msgpack format selection logic - Reduce unnecessary query parameters

When dataclasses use slots=True and have fields named 'bytes' or 'type', the class namespace contains member descriptors that interfere with get_type_hints() evaluation. Fix by passing explicit globalns with builtins and empty localns to get_type_hints() to avoid the class namespace pollution. Fixes TypeError: unsupported operand type(s) for |: 'member_descriptor' and 'NoneType'

The local_state_schema and global_state_schema fields may not always be present in wire data from the ledger state delta endpoint. Make them optional with default=None to handle missing fields gracefully.

Add Docker container-based mock server fixtures using testcontainers: - MockServerContainer class to manage PollyJS mock server lifecycle - Session-scoped fixtures for algod, indexer, and kmd mock servers - Mock server replays pre-recorded HAR files for deterministic testing - Fixtures automatically start/stop containers per test session - Configure via POLYTEST_MOCK_SERVER_IMAGE and POLYTEST_RECORDINGS_PATH env vars - Add test configuration constants matching TS mock server config

- Add testcontainers>=4.0.0 to dev dependencies for mock server containers - Add polytest generate/validate tasks for algod, indexer, kmd clients - Update transact polytest config to use algorandfoundation repo - Add polytest-generate-all and polytest-validate-all aggregate tasks - Add group_common_tests pytest marker for polytest test groups

- Install Rust toolchain and polytest CLI - Run polytest-validate-algod to ensure test structure matches polytest config - Validates that generated test files follow the expected naming conventions

Move manually written tests to tests/modules/algod_client/manual/ to distinguish them from polytest-generated test stubs: - test_block.py - test_ledger_state_delta.py - test_pending_transaction_information.py - test_raw_transaction.py - test_simulate_transactions.py - test_suggested_params.py Also fix localnet tests to use AlgorandClient.default_localnet().client.algod consistently instead of mixing mock server with localnet transactions.

Add NOT IMPLEMENTED test stubs for algod client API endpoints: - DELETE endpoints (catchup, ledger_sync) - GET endpoints (boxes, state proofs, deltas, devmode, experimental, etc.) - POST endpoints (catchup, ledger_sync, shutdown, teal, transactions) All stubs are marked with @pytest.mark.skip(reason='Test not implemented') and follow the polytest naming convention matching TypeScript tests. These stubs serve as placeholders for future test implementation and ensure structural parity with algokit-utils-ts polytest suite.

- Implement test_get_genesis.py, test_get_health.py, test_get_versions.py - Implement test_get_v2_status.py, test_get_v2_ledger_supply.py - Implement test_get_v2_transactions_params.py - Implement test_get_v2_accounts_address.py with localnet - Implement test_get_v2_blocks_round.py with mainnet/testnet endpoints - Implement test_get_v2_deltas_round.py with mainnet endpoint - Skip msgpack-related tests matching TypeScript approach - All tests verify client methods return correct model types

- Move indexer and kmd integration tests to manual/ folders - These tests require localnet with indexer/kmd, not mock server - Update tests to use localnet clients directly - Add E501, W292, I001 lint ignores for tests/modules/**/* in pyproject.toml - Fix trailing newlines in polytest stub files (pre-commit format)

…duplicate schemas removed

…lelock dependency

…ced by filtered oas tags are not generated

…ed clients; minor alignment with latest on ts

Copilot

Pull request overview

This PR introduces polytest integration for the algod client and includes refinements to the API generator. The changes establish a mock server testing infrastructure and add initial test coverage for algod API endpoints using recorded HAR files.

Key changes:

Adds mock server infrastructure for deterministic API testing
Implements polytest-based tests for ~30 algod endpoints
Refactors model field defaults to be more explicit
Renames/consolidates API client methods for consistency

Reviewed changes

Copilot reviewed 293 out of 310 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/modules/_mock_server.py	Docker-based mock server infrastructure with retry logic
tests/modules/conftest.py	Shared test utilities including dataclass serializer
tests/modules/algod_client/conftest.py	Algod-specific mock server fixture
tests/modules/algod_client/test_*.py	Polytest suite for algod endpoints
src/algokit_kmd_client/client.py	Adds retry mechanism with exponential backoff
src/algokit_kmd_client/models/*.py	Updates field defaults and model naming
src/algokit_transact/models/*.py	Adds Unknown transaction type fallback

Comments suppressed due to low confidence (1)

tests/modules/_mock_server.py:1

The jitter calculation produces values between 0.5 and 1.5, which means backoff is always reduced by at least 50% (when jitter is 0.5). This differs from typical jitter implementations that add randomness around the base value. Consider using a more standard jitter approach like random.uniform(0.5, 1.5) (which is already implemented) or documenting this specific backoff reduction strategy.

"""Mock server infrastructure for algod/indexer/kmd client testing.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/algokit_kmd_client/client.py

src/algokit_transact/models/transaction.py

src/algokit_kmd_client/models/_create_wallet_request.py

src/algokit_utils/transactions/transaction_composer.py

aorumbayev · 2025-12-02T23:54:30Z

@daniel-makerx a few bits around consumption of mock client are to be decided and still missing a set of kmd algod and indexer tests to be covered (missing har files on mock server side) - otherwise ready for preliminary review. The main aim here was aligning with Neil's progress on the various algod/indexer/kmd generator and spec related refinements. The following 2 were split into separate branches and mainly cover the addition of polytest generated stubs while majority of all tweaks and refinements are within this branch. #224 -> to be merged into -> #225 -> to be merged into -> this branch

* test: add indexer client polytest tests - Add 21 indexer client endpoint tests aligned with TypeScript implementation - Add test constants for indexer test data (address, app_id, asset_id, txid, round) - Add JSON snapshots for all indexer endpoints - Tests use mock server recordings for deterministic testing * test: add KMD client polytest tests (#224) - Add 23 KMD client endpoint tests aligned with TypeScript implementation - Fix init_wallet_handle method name in kmd_account_manager.py - Fix manual test_key_management.py (remove non-existent display_mnemonic param) - Add JSON snapshots for KMD endpoints with recordings - Most tests skipped due to missing mock server recordings (require localnet)

aorumbayev · 2025-12-03T19:55:09Z

@daniel-makerx @lempira - ready for review - before merging would require one extra commit to:

change mock server image tag to ghcr on algorandfoundation org once ci: adds shared reusable setup polytest and mock server actions algokit-polytest#18 is merged
change setup-polytest action path to point to algorandfoundation's algokit-polytest repo once ci: adds shared reusable setup polytest and mock server actions algokit-polytest#18 is merged
Updating branch to point to main (source urls for specs which are now pulled from remote paths) once fix: more oas refinement algokit-oas-generator#3 is merged
If we are ok with this change fix: fixes casing of version strings joe-p/polytest#57 then no changes needed in polytest stubs, however if we do decide on further alternative naming for the file names for stubs generated with polytest - both ts and py would need to be regenerated via uv run poe tasks (which now include dedicated polytest tasks for generation and validation)

Post merge remaining polytest stubs are to be implemented on kmd/algod/indexer site as remaining har recordings become available in mock server for testing.

.pre-commit-config.yaml

…er (#231) * refactor: change test setup to use external mock servers Updates the test suite to utilize externally managed mock servers for algod, indexer, and kmd clients. This change decouples the test environment from Docker-based mock servers, promoting greater flexibility and simplifying setup, especially in CI/CD environments. It leverages the algokit-polytest repository for managing the mock server lifecycles. The tests now connect to mock servers via environment variables. * chore: tweaks * chore: enable polytest validate in ci for algod, indexer, kmd

Renames `get_arc56_method` to `get_abi_method` for clarity and consistency across the codebase, reflecting the shift towards using ABI method specifications. Also, replace calls to transaction.tx_id with transaction.tx_id() to align with ts

…algod (#222) * refactor: algod and api generator refinements aligning with ts * chore: txnleases * feat: default value handling of required fields; omitting txn leases field * fix(api): refine format parameter handling in client generator template - Only set format=msgpack when msgpack is explicitly selected - Remove unnecessary format=json assignments for JSON-only endpoints - Align with TypeScript client behavior * fix(api): regenerate algod client with refined format handling Generated output from updated client.py.j2 template: - Remove format=json for endpoints that only support JSON - Simplify msgpack format selection logic - Reduce unnecessary query parameters * fix(serde): handle dataclass fields that shadow builtin names When dataclasses use slots=True and have fields named 'bytes' or 'type', the class namespace contains member descriptors that interfere with get_type_hints() evaluation. Fix by passing explicit globalns with builtins and empty localns to get_type_hints() to avoid the class namespace pollution. Fixes TypeError: unsupported operand type(s) for |: 'member_descriptor' and 'NoneType' * fix(algod): make LedgerAppParams schema fields optional The local_state_schema and global_state_schema fields may not always be present in wire data from the ledger state delta endpoint. Make them optional with default=None to handle missing fields gracefully. * feat(test): integrate polytest mock server for API client testing Add Docker container-based mock server fixtures using testcontainers: - MockServerContainer class to manage PollyJS mock server lifecycle - Session-scoped fixtures for algod, indexer, and kmd mock servers - Mock server replays pre-recorded HAR files for deterministic testing - Fixtures automatically start/stop containers per test session - Configure via POLYTEST_MOCK_SERVER_IMAGE and POLYTEST_RECORDINGS_PATH env vars - Add test configuration constants matching TS mock server config * build: add testcontainers dependency and polytest poe tasks - Add testcontainers>=4.0.0 to dev dependencies for mock server containers - Add polytest generate/validate tasks for algod, indexer, kmd clients - Update transact polytest config to use algorandfoundation repo - Add polytest-generate-all and polytest-validate-all aggregate tasks - Add group_common_tests pytest marker for polytest test groups * ci: add polytest validation to check-python workflow - Install Rust toolchain and polytest CLI - Run polytest-validate-algod to ensure test structure matches polytest config - Validates that generated test files follow the expected naming conventions * refactor(test): move manual algod tests to dedicated folder Move manually written tests to tests/modules/algod_client/manual/ to distinguish them from polytest-generated test stubs: - test_block.py - test_ledger_state_delta.py - test_pending_transaction_information.py - test_raw_transaction.py - test_simulate_transactions.py - test_suggested_params.py Also fix localnet tests to use AlgorandClient.default_localnet().client.algod consistently instead of mixing mock server with localnet transactions. * test(algod): generate polytest stubs for all algod client endpoints Add NOT IMPLEMENTED test stubs for algod client API endpoints: - DELETE endpoints (catchup, ledger_sync) - GET endpoints (boxes, state proofs, deltas, devmode, experimental, etc.) - POST endpoints (catchup, ledger_sync, shutdown, teal, transactions) All stubs are marked with @pytest.mark.skip(reason='Test not implemented') and follow the polytest naming convention matching TypeScript tests. These stubs serve as placeholders for future test implementation and ensure structural parity with algokit-utils-ts polytest suite. * test(algod): implement polytest stubs aligning with TypeScript tests - Implement test_get_genesis.py, test_get_health.py, test_get_versions.py - Implement test_get_v2_status.py, test_get_v2_ledger_supply.py - Implement test_get_v2_transactions_params.py - Implement test_get_v2_accounts_address.py with localnet - Implement test_get_v2_blocks_round.py with mainnet/testnet endpoints - Implement test_get_v2_deltas_round.py with mainnet endpoint - Skip msgpack-related tests matching TypeScript approach - All tests verify client methods return correct model types * fix(test): move integration tests to manual folders and fix lint ignores - Move indexer and kmd integration tests to manual/ folders - These tests require localnet with indexer/kmd, not mock server - Update tests to use localnet clients directly - Add E501, W292, I001 lint ignores for tests/modules/**/* in pyproject.toml - Fix trailing newlines in polytest stub files (pre-commit format) * style: fix indentation in oas-generator template renderer * chore: update api client to support latest refined specs with inline duplicate schemas removed * chore: refine fixtures for cross worker access to mock server with filelock dependency * feat: add graceful handling of unknown transaction types * refactor: ensure models that are not used anywhere and/or are referenced by filtered oas tags are not generated * chore: extra fixes for unknown txn support * chore: adding snapshot testing; migration notes * chore: remove refs * chore: linter tweaks * chore: sqlite as default value from spec; retry mechanism for generated clients; minor alignment with latest on ts * feat: support fetching oas specs directly from oas-generator repo * chore: integrate docker image from fork; shared action * chore: temporarily comment out polytest validate in ci * docs: regen docs * chore: regen clients * chore: regen kmd clients; simplify remote oas fetching * chore: refine mock server fixtures * chore: refine pre commit; fix mypy warnings * chore: add jitter and polling health check to the mock server fixture * docs: remove mentions of oas shorthand * test: add indexer client polytest tests (#225) * test: add indexer client polytest tests - Add 21 indexer client endpoint tests aligned with TypeScript implementation - Add test constants for indexer test data (address, app_id, asset_id, txid, round) - Add JSON snapshots for all indexer endpoints - Tests use mock server recordings for deterministic testing * test: add KMD client polytest tests (#224) - Add 23 KMD client endpoint tests aligned with TypeScript implementation - Fix init_wallet_handle method name in kmd_account_manager.py - Fix manual test_key_management.py (remove non-existent display_mnemonic param) - Add JSON snapshots for KMD endpoints with recordings - Most tests skipped due to missing mock server recordings (require localnet) * chore: add support for overriding mock server urls for local dev * docs: update migration guide * chore: refresh kmd client * chore: refresh docs * feat: add support for skip tag in oas generator; dropping dryrun * chore: update branch for oas generator remote source to main * chore: further simplify mock server * docs: add documentation to prevent base type docs appearing * chore: refresh docs * refactor: change test setup to use external mock servers without docker (#231) * refactor: change test setup to use external mock servers Updates the test suite to utilize externally managed mock servers for algod, indexer, and kmd clients. This change decouples the test environment from Docker-based mock servers, promoting greater flexibility and simplifying setup, especially in CI/CD environments. It leverages the algokit-polytest repository for managing the mock server lifecycles. The tests now connect to mock servers via environment variables. * chore: tweaks * chore: enable polytest validate in ci for algod, indexer, kmd * chore: remove slow stages from pre commit * refactor: change arc56 method to abi method Renames `get_arc56_method` to `get_abi_method` for clarity and consistency across the codebase, reflecting the shift towards using ABI method specifications. Also, replace calls to transaction.tx_id with transaction.tx_id() to align with ts --------- Co-authored-by: Daniel McGregor <daniel.mcgregor@makerx.com.au>

aorumbayev added 22 commits November 26, 2025 17:32

refactor: algod and api generator refinements aligning with ts

91e5b6f

chore: txnleases

e1d10b0

feat: default value handling of required fields; omitting txn leases …

8a210a6

…field

fix(api): refine format parameter handling in client generator template

23f4006

- Only set format=msgpack when msgpack is explicitly selected - Remove unnecessary format=json assignments for JSON-only endpoints - Align with TypeScript client behavior

fix(api): regenerate algod client with refined format handling

6d8f4a6

Generated output from updated client.py.j2 template: - Remove format=json for endpoints that only support JSON - Simplify msgpack format selection logic - Reduce unnecessary query parameters

fix(algod): make LedgerAppParams schema fields optional

63aee43

The local_state_schema and global_state_schema fields may not always be present in wire data from the ledger state delta endpoint. Make them optional with default=None to handle missing fields gracefully.

ci: add polytest validation to check-python workflow

d8f739a

- Install Rust toolchain and polytest CLI - Run polytest-validate-algod to ensure test structure matches polytest config - Validates that generated test files follow the expected naming conventions

style: fix indentation in oas-generator template renderer

1abfc3d

chore: update api client to support latest refined specs with inline …

ce4a4ec

…duplicate schemas removed

chore: refine fixtures for cross worker access to mock server with fi…

bd08abe

…lelock dependency

feat: add graceful handling of unknown transaction types

d606108

refactor: ensure models that are not used anywhere and/or are referen…

7706766

…ced by filtered oas tags are not generated

chore: extra fixes for unknown txn support

5cfe58c

chore: adding snapshot testing; migration notes

5697d1a

chore: remove refs

69c987b

aorumbayev requested review from daniel-makerx, lempira and neilcampbell November 28, 2025 23:54

aorumbayev added 5 commits November 29, 2025 00:56

chore: linter tweaks

8e0673f

chore: sqlite as default value from spec; retry mechanism for generat…

be0407e

…ed clients; minor alignment with latest on ts

feat: support fetching oas specs directly from oas-generator repo

d42dc42

chore: integrate docker image from fork; shared action

237230e

chore: temporarily comment out polytest validate in ci

201aa1e

aorumbayev force-pushed the decoupling-algod-tweaks branch from e7c4710 to 59851d2 Compare December 2, 2025 22:33

aorumbayev added 2 commits December 2, 2025 23:44

chore: refine pre commit; fix mypy warnings

d8f2d3d

chore: add jitter and polling health check to the mock server fixture

dee7fe7

aorumbayev requested a review from Copilot December 2, 2025 23:52

Copilot AI reviewed Dec 2, 2025

View reviewed changes

aorumbayev and others added 4 commits December 3, 2025 01:03

docs: remove mentions of oas shorthand

bb60d54

chore: add support for overriding mock server urls for local dev

a949517

docs: update migration guide

8661bd9

aorumbayev marked this pull request as ready for review December 3, 2025 19:55

aorumbayev and others added 6 commits December 4, 2025 00:30

Merge branch 'decoupling' into decoupling-algod-tweaks

88b5e9f

chore: refresh kmd client

bb452b9

chore: refresh docs

6f0b9ac

feat: add support for skip tag in oas generator; dropping dryrun

158e727

chore: update branch for oas generator remote source to main

eec3fe0

chore: further simplify mock server

58ec86b

daniel-makerx reviewed Dec 5, 2025

View reviewed changes

.pre-commit-config.yaml Outdated Show resolved Hide resolved

daniel-makerx added 2 commits December 5, 2025 13:12

docs: add documentation to prevent base type docs appearing

fd43ae9

chore: refresh docs

d79cfad

daniel-makerx approved these changes Dec 5, 2025

View reviewed changes

aorumbayev and others added 2 commits December 8, 2025 21:49

chore: remove slow stages from pre commit

50fcad7

aorumbayev force-pushed the decoupling-algod-tweaks branch from ea4f023 to a8ddedb Compare December 8, 2025 21:07

refactor: change arc56 method to abi method

b147c37

Renames `get_arc56_method` to `get_abi_method` for clarity and consistency across the codebase, reflecting the shift towards using ABI method specifications. Also, replace calls to transaction.tx_id with transaction.tx_id() to align with ts

aorumbayev force-pushed the decoupling-algod-tweaks branch from a8ddedb to b147c37 Compare December 8, 2025 21:27

aorumbayev merged commit 6347860 into decoupling Dec 8, 2025
5 checks passed

aorumbayev deleted the decoupling-algod-tweaks branch December 8, 2025 21:34

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

feat: refinements in api generator; initial polytest integration for algod #222
aorumbayev merged 49 commits intodecouplingfrom
decoupling-algod-tweaks

aorumbayev commented Nov 28, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aorumbayev commented Dec 2, 2025 •

edited

Loading

Uh oh!

aorumbayev commented Dec 3, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

aorumbayev commented Nov 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Notes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aorumbayev commented Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aorumbayev commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

aorumbayev commented Nov 28, 2025 •

edited

Loading

aorumbayev commented Dec 2, 2025 •

edited

Loading

aorumbayev commented Dec 3, 2025 •

edited

Loading