https://github.com/algorandfoundation/algokit-polytest
https://github.com/algorandfoundation/algokit-polytest
algokit utils
Last synced: about 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/algorandfoundation/algokit-polytest
- Owner: algorandfoundation
- Created: 2025-11-03T16:59:58.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-04-19T18:08:37.000Z (2 months ago)
- Last Synced: 2026-04-19T19:28:37.303Z (2 months ago)
- Topics: algokit, utils
- Language: TypeScript
- Homepage:
- Size: 13.7 MB
- Stars: 3
- Watchers: 0
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Codeowners: .github/CODEOWNERS.md
Awesome Lists containing this project
README
# AlgoKit Polytest
Test configuration files and mock server infrastructure for cross-language testing of AlgoKit libraries.
## Overview
This repository provides:
- **Test Configurations** (`test_configs/`) - Shared test plans for polytest CLI, ensuring consistent test coverage across Python, TypeScript, and other language implementations
- **Mock Server** (`resources/mock-server/`) - Bun-based HTTP server that replays pre-recorded HAR files for deterministic API testing
- **GitHub Actions** (`.github/actions/`) - Reusable composite actions for CI integration
## Directory Structure
```
├── .github/
│ └── actions/
│ ├── setup-polytest/ # Install polytest CLI
│ └── run-mock-server/ # Start mock server for testing
├── resources/
│ └── mock-server/ # Bun/Fastify mock server
│ ├── recordings/ # HAR files for algod, indexer, kmd
│ └── src/ # Server implementation
├── test_configs/ # Polytest configuration files
│ ├── algod_client.jsonc
│ ├── indexer_client.jsonc
│ ├── kmd_client.jsonc
│ └── transact.jsonc
└── docs/ # Generated test plan documentation
```
## GitHub Actions
### `setup-polytest`
Installs Rust toolchain and the polytest CLI.
```yaml
- uses: algorandfoundation/algokit-polytest/.github/actions/setup-polytest@main
with:
version: "0.6.0" # Optional: pin to specific version
```
### `run-mock-server`
Starts a mock server for testing Algorand API clients.
```yaml
- uses: algorandfoundation/algokit-polytest/.github/actions/run-mock-server@main
with:
client: algod # Required: algod, indexer, or kmd
# After this step, MOCK_ALGOD_URL, MOCK_INDEXER_URL, MOCK_KMD_URL is available (e.g., http://localhost:8000)
```
See [run-mock-server README](.github/actions/run-mock-server/README.md) for full documentation.
## Local Development
### Prerequisites
- [Bun](https://bun.sh/) runtime: `curl -fsSL https://bun.sh/install | bash`
### Running the Mock Server
**Start all servers (recommended):**
```bash
cd resources/mock-server
./scripts/start_all_servers.sh
```
This starts algod (port 8000), kmd (port 8001), and indexer (port 8002) in the background and outputs the environment variables to set.
**Start a single server:**
```bash
cd resources/mock-server
./scripts/start_server.sh algod # Port 8000
./scripts/start_server.sh kmd # Port 8001
./scripts/start_server.sh indexer # Port 8002
```
**Stop all servers:**
```bash
cd resources/mock-server
./scripts/stop_all_servers.sh
```
See [mock-server README](resources/mock-server/README.md) for more details.
### Recording New HAR Files
Edit `resources/mock-server/src/record.ts` to add new requests, then restart the server. It will record any missing requests to the HAR files.
## Integration with Implementation Repos
Implementation repositories (e.g., `algokit-utils-py`, `algokit-utils-ts`) use this repo via:
1. **Test Generation**: polytest CLI with `--git` flag pulls configs from this repo
2. **Mock Server**: GitHub Action starts the mock server in CI