---
name: migrate-pytest
description: Migrate a pytest integration test to the test-loop framework. Use when converting a pytest from pytest/tests/ to a deterministic test-loop test.
argument-hint: <path-to-pytest-file>
allowed-tools: Read, Grep, Glob, Bash, Edit, Write
---

Migrate a pytest integration test to the test-loop framework.

**Target pytest file:** $ARGUMENTS

Follow these steps in order:

## 1. Understand the pytest

- Read the target pytest file
- Identify each distinct test scenario (steps, test methods, or test functions)
- For each scenario, write in details:
  - What is being tested (the behavior under test)
  - The network topology (how many validators, archival nodes, RPC nodes, observers)
  - Key configuration (epoch_length, gc settings, archive mode, split storage, etc.)
  - The sequence of actions (start nodes, wait for blocks, kill/restart, send txs, etc.)
  - The assertions (what is verified and how)
- Present this analysis to the user before proceeding
- Write this analysis into `<test_name>_migration.md` in the project root.

## 2. Study the test-loop framework

- Read `test-loop-tests/README.md` for the builder API and patterns
- Read relevant examples from `test-loop-tests/src/examples/` that are relevant to the pytest being migrated (list available examples with `ls test-loop-tests/src/examples/`)
- Browse existing tests in `test-loop-tests/src/tests/` for patterns similar to what the pytest does

## 3. Design the test-loop test

For each pytest scenario, decide:
- Whether it maps to a separate `#[test]` function or can be combined
- The simplest builder API setup that covers the scenario
- Which test-loop utilities to use (runners, node accessors, transactions)
- Whether any simplification is appropriate (the README says: "it would be _extremely_ hard to migrate the logic precisely. Instead, migrate tests only if they make sense to you")

Present the plan to the user and get confirmation before writing code.

## 4. Write the test

- Create `test-loop-tests/src/tests/<test_name>.rs`
- Follow the instructions in `test-loop-tests/README.md`
- Register the module in `test-loop-tests/src/tests/mod.rs` (keep alphabetical order)

## 5. Verify

- Run `cargo check --package test-loop-tests --features test_features` to verify compilation
- Run each test individually:
  `cargo test --package test-loop-tests --features test_features -- tests::<module>::<test_name> --exact --show-output`
- Fix any compilation errors or test failures
- Run `cargo fmt --package test-loop-tests`

## 6. Clean up the pytest

- Delete the original pytest file
- Remove its entries from `nightly/pytest-sanity.txt` (check for both regular and `--features nightly` variants, and commented-out spice variants)
- Search for any other references to the pytest filename

## 7. Summary

Report what was done:
- Which pytest scenarios were migrated (and any that were intentionally simplified or skipped)
- The new test file location and test function names
- Approximate runtime comparison if available