polylith-testing

Testing Skill

Quick command

# Human-readable (default)
uv run poly test diff

# Pipe-friendly: comma-separated list of affected bricks (use this in scripts)
uv run poly test diff --short

Agent rule of thumb: when the goal is to do something with the result (run pytest, drive CI), reach for --short first. The default output is for human readers.

Command prefix: If you do not know the package manager, list lock files with ls uv.lock poetry.lock pdm.lock 2>/dev/null (a pyproject.toml is always present, so it tells you nothing on its own). Use uv run poly (uv), poetry poly (poetry), pdm run poly (pdm), hatch run poly (hatch), or poly (activated venv). Examples below use uv run.

⚠ poly test diff reports only — it does not execute tests. Pipe its output into pytest / unittest. poly test diff vs poly diff:

• poly test diff → which test files changed (drives test runs).
• poly diff → which brick implementations changed (drives releases). Load polylith-diff.

Tag selection

• Default: latest git tag matching [tool.polylith.tag.patterns].stable from workspace.toml (e.g. stable-*).
• --since <ref> — pin a tag/branch/commit. The output line Test diff based on stable-4 shows the tag the CLI selected.

Command reference

💡 For piping into pytest use --short. It emits just the brick names separated by commas, with no headers, prefixes, or decoration — exactly what a script needs. --bricks is meant for humans reading the output.

Examples

# Default: against latest stable-* tag
uv run poly test diff

# Pipe-friendly bricks list (best for scripts / agents)
uv run poly test diff --short

# Pin a tag, then pipe affected bricks into pytest
uv run poly test diff --since stable-4 --short

# Human-readable list of affected bricks
uv run poly test diff --bricks

Sample output (default, no flags)

Projects and bricks affected by changes in tests
Test diff based on stable-4

Affected projects: 5
Affected components: 1
Affected bases: 0

  brick   consumer_project   message-api   aws lambda   my_fastapi_project   gcp function
 ────────────────────────────────────────────────────────────────────────────────────────
  log            ✔                ✔            ✔                ✔                 ✔

✔ = the column project is affected by the row brick's test changes.

Sample output (--short)

log,message

Just the brick names, comma-separated. No header, no prefix, no namespace. Empty result = no affected bricks.

Sample output (--bricks)

--bricks is a human-readable variant; one line per affected brick:

⚙ Changes affecting log
⚙ Changes affecting message

Use --short instead when piping into another tool.

Executing tests for affected bricks

💡 Most common case — "I changed code, run the tests for it": that's driven by poly diff (implementation diff), not poly test diff. Load polylith-diff for the canonical recipe; the same pytest -k pattern shown below works there.

poly test diff only reports — you drive the test runner yourself. The established Polylith pattern is to feed --short straight into pytest -k: brick names become an or-expression that pytest matches against test IDs, so you don't need to know the namespace, the theme, or whether each brick is a base or a component.

Recommended flow

1. Capture poly test diff --short.
2. Replace the commas with or to form a pytest -k expression.
3. Pass it to pytest -k. Skip the call when the result is empty (no affected bricks).

Shell one-liner (uv)

changes="$(uv run poly test diff --short)"
[ -n "$changes" ] && uv run pytest -k "${changes//,/ or }"

Example: --short outputs log,message → pytest is invoked as pytest -k "log or message", which collects every test whose ID contains log or message (the brick directory name appears in the test path, so this matches both test/components/<ns>/log/... and test/bases/<ns>/log/... automatically).

Caveat — substring matching

pytest -k matches substrings of test IDs, so a brick named log will also pull in tests whose name happens to contain log (e.g. tests for an unrelated brick called logger or a function test_login). If a brick name is short or generic and produces unwanted matches, fall back to passing explicit test directories instead.

Running targeted tests for a single brick

If you are iteratively debugging or just created a single brick, you do not need to use poly test diff. You can run the test runner directly against the brick's test folder.

Check workspace.toml to determine the theme and namespace:

• For the loose theme (recommended): pytest test/components/<namespace>/<basename> or pytest test/bases/<namespace>/<basename>.
• For the tdd theme: pytest components/<basename>/test or pytest bases/<basename>/test.

Notes for the agent

• Always exits 0 — informational, never a CI gate.
• If no matching tag exists and --since isn't passed, prints No matching tags or commits found in repository. and exits 0. Handle this in scripts.