ag2ai FastStream Dev Workflow
Toolchain
uv for Python deps + just as the task runner + docker compose for brokers. Never use bare pip. Run just with no args to list all recipes.
just init [python-version]— build the dev environment (default Python 3.10).
Docker brokers
just up/just stop/just down— start / stop / remove all containers (brokers + thefaststreamdev container the test recipes exec into).- Per broker:
just kafka-up,rabbit-up,nats-up,redis-up,redis-cluster-up(+ matching-stopand-logsrecipes). MQTT has no local just recipes — it is tested in CI only.
Test matrix
All just test* recipes execute inside the dev container (docker compose exec faststream) — run just up first.
| Command | Selection |
|---|---|
just test [path] |
fast: not slow and not connected, parallel -n auto |
just test-all [path] |
full suite (-m "all") — all brokers must be up |
just test-<broker> [path] |
broker-marked tests excluding connected and slow (kafka, confluent, rabbit, redis, redis-cluster, nats) |
just test-<broker>-all [path] |
every broker-marked test incl. slow/connected — needs that broker up |
just test-coverage [path] / test-coverage-all |
with coverage |
Extra pytest args pass through: just test tests/brokers/kafka -vv. Run pytest directly when needed (uv run pytest ... — no container required, but bare pytest excludes only slow by default) — never via the rtk proxy.
Lint & static analysis (run before any PR, in this order)
just linter— runsruff format(rewrites files in place), thenruff check --exit-non-zero-on-fix(reports fixable issues without applying them), then codespell (alias:just lint). Expect formatting changes in your working tree after running it.just mypy— strict mode overfaststream/andtests/mypy/.just static-analysis— mypy + bandit + semgrep;just zizmorseparately for GitHub Actions workflows.just pre-commit— pre-commit hooks on modified files (just pre-commit-allfor the whole tree).
Docs recipes
just docs-serve— live server;just docs-build— static build (details in the documentation-writing skill).
CI expectations
- CI (
.github/workflows/pr_tests.yaml): core jobs run everything exceptconnected(-m "(slow and not connected) or not connected"); per-broker jobs run<broker> and not connected, plus dedicated jobs with real broker services forconnectedtests. - 30s per-test timeout; xdist parallelism — tests must be order-independent.
- Coverage sources include
faststream/,tests/,docs/docs_src/, andexamples/.
Related skills
- testing-patterns — markers, base testcases, fixtures.
- code-architecture — source conventions the linters enforce.
- documentation-writing — docs authoring and snippet testing.