test: opt-in broker-failure suite (just test-dr)

.gitignore

@@ -15,6 +15,7 @@ __pycache__/*
 htmlcov/
 coverage.xml
 pytest.xml
+tests_dr/results/
 .python-version
 .venv
 dist

AGENTS.md

@@ -16,6 +16,10 @@ title. Most of the vocabulary is FastStream's and aiokafka's; only seven terms a
 runs pytest, and tears down. To run one test against an already-running stack,
 `uv run --no-sync pytest tests/test_kafka_committer.py -k <name>`.
 
+`just test-dr` runs the broker-failure suite in `tests_dr/` from the host against a 3-node Redpanda
+cluster. It kills and pauses brokers, takes about four minutes, and runs only on demand, never in CI.
+Run it after changing commit, rebalance, or shutdown behaviour.
+
 ## Architecture
 
 `faststream_concurrent_aiokafka/` is nine short modules; read the ones you are changing. The one

justfile

@@ -12,6 +12,16 @@ test-ci:
 test-branch:
     @just test --cov=. --cov-branch
 
+dr_compose := "docker compose -f tests_dr/compose.yml"
+
+# Opt-in: kills and pauses brokers of a 3-node Redpanda cluster; not part of `test` or CI.
+test-dr *args:
+    #!/usr/bin/env sh
+    set -eu
+    trap '{{ dr_compose }} down --remove-orphans' EXIT
+    {{ dr_compose }} up -d
+    uv run --no-sync pytest tests_dr -o addopts= -p no:randomly {{ args }}
+
 build:
     docker compose build application
 

pyproject.toml

@@ -89,9 +89,16 @@ isort.no-lines-before = ["standard-library", "local-folder"]
     "S101",    # allow asserts
     "PLR2004", # allow magic values in test assertions
 ]
+"tests_dr/**" = [
+    "INP001",  # no __init__.py, so `--cov=.` in test-ci does not count this opt-in suite
+    "S101",    # allow asserts
+    "PLR2004", # allow magic values in test assertions
+]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+# pytest's defaults plus tests_dr, which only `just test-dr` runs.
+norecursedirs = ["*.egg", ".*", "_darcs", "build", "CVS", "dist", "node_modules", "venv", "{arch}", "tests_dr"]
 addopts = "-n auto"
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"

tests_dr/compose.yml

@@ -0,0 +1,59 @@
+name: fca-dr
+services:
+  redpanda-0:
+    image: redpandadata/redpanda:latest
+    container_name: fca-dr-0
+    command:
+      - redpanda
+      - start
+      - --overprovisioned
+      - --smp 1
+      - --memory 512M
+      - --reserve-memory 0M
+      - --node-id 0
+      - --check=false
+      - --seeds redpanda-0:33145,redpanda-1:33145,redpanda-2:33145
+      - --rpc-addr 0.0.0.0:33145
+      - --advertise-rpc-addr redpanda-0:33145
+      - --kafka-addr internal://0.0.0.0:9092,external://0.0.0.0:19092
+      - --advertise-kafka-addr internal://redpanda-0:9092,external://localhost:19092
+    ports:
+      - "19092:19092"
+  redpanda-1:
+    image: redpandadata/redpanda:latest
+    container_name: fca-dr-1
+    command:
+      - redpanda
+      - start
+      - --overprovisioned
+      - --smp 1
+      - --memory 512M
+      - --reserve-memory 0M
+      - --node-id 1
+      - --check=false
+      - --seeds redpanda-0:33145,redpanda-1:33145,redpanda-2:33145
+      - --rpc-addr 0.0.0.0:33145
+      - --advertise-rpc-addr redpanda-1:33145
+      - --kafka-addr internal://0.0.0.0:9092,external://0.0.0.0:29092
+      - --advertise-kafka-addr internal://redpanda-1:9092,external://localhost:29092
+    ports:
+      - "29092:29092"
+  redpanda-2:
+    image: redpandadata/redpanda:latest
+    container_name: fca-dr-2
+    command:
+      - redpanda
+      - start
+      - --overprovisioned
+      - --smp 1
+      - --memory 512M
+      - --reserve-memory 0M
+      - --node-id 2
+      - --check=false
+      - --seeds redpanda-0:33145,redpanda-1:33145,redpanda-2:33145
+      - --rpc-addr 0.0.0.0:33145
+      - --advertise-rpc-addr redpanda-2:33145
+      - --kafka-addr internal://0.0.0.0:9092,external://0.0.0.0:39092
+      - --advertise-kafka-addr internal://redpanda-2:9092,external://localhost:39092
+    ports:
+      - "39092:39092"