Skip to content

Commands

m4bwav edited this page Nov 21, 2026 · 1 revision

tw.py is run from the plugin root as python scripts/tw.py COMMAND. Every command that takes --json prints one JSON object or array instead of text.

Exit codes

Code Meaning
0 ok
1 failures or findings (a failed test, an uncovered changed line, a lint finding)
2 usage or tool error: no runnable suite, no report written, a file that does not parse

detect

detect [DIR] prints the stacks and runners found in DIR (default .) as JSON. It always prints JSON and has no --json flag. The README's command list leaves it out.

python scripts/tw.py detect evals/fixtures/flaky
[
  {
    "stack": "python",
    "runner": "pytest",
    "cmd": "python -m pytest --junitxml=tw-results.xml"
  }
]

A folder with no tests and no project file gives []. Details per stack: Stacks and runners.

parse

parse FILE... [--json] reads TRX (dotnet test), NUnit 3 XML (Unity Test Framework), JUnit XML (pytest, jest-junit and others) and Jest or Vitest JSON, in any mix, and prints one summary. A file whose text starts with { is read as Jest JSON; anything else is read as XML and told apart by its root element.

python scripts/tw.py parse tests/fixtures/junit.xml tests/fixtures/jest.json tests/fixtures/nunit.xml
jest,junit,nunit: 8 tests, 3 passed, 3 failed, 2 skipped, 3.555s
FAIL test_a.test_bad
  assert 1 == 2
FAIL sum fails
  expected 3
FAIL Game.Spawn
  null ref

Each failure shows only the first line of its message. With --json messages are cut at 500 characters:

python scripts/tw.py parse --json tests/fixtures/jest.json
{
  "format": "jest",
  "total": 3,
  "passed": 1,
  "failed": 1,
  "skipped": 1,
  "time": 0.905,
  "failures": [
    {
      "name": "sum fails",
      "message": "expected 3"
    }
  ]
}

JUnit test names are classname.name. Inconclusive NUnit results and TRX NotExecuted count as skipped. Exit code 1 when any test failed.

run

run [DIR] [--reruns N] [--json] runs the first runnable stack detect found, with report flags, writing the report to a temporary folder, then parses it. Unity is never started (see the unity reference); Luau has no command. With --reruns N it reruns the whole suite up to N times while failures remain; a test that failed and then passed is printed as FLAKY name, removed from the failures and not counted as passed.

python scripts/tw.py run evals/fixtures/legacy
no runnable suite detected (Unity and Luau: see the skill's references)

Exit code 2 in that case, and when the suite wrote no report.

slow

slow FILE... [--top N] lists the slowest tests across reports, default top 10.

python scripts/tw.py slow tests/fixtures/junit.xml tests/fixtures/nunit.xml --top 3
    2.000s  Game.Spawn
    0.300s  test_a.test_bad
    0.250s  Game.SaveRoundTrip

changed

changed COVERAGE [--base REF] [--dir DIR] [--json] reports changed lines that have no coverage. COVERAGE is Cobertura XML or lcov. --base defaults to origin/main. --dir (default .) is the git working tree to diff; the README does not mention it.

When diff-cover is installed, changed runs diff-cover COVERAGE --compare-branch=REF and returns its exit code; --json then has no effect. Without it, tw.py takes git diff -U0 REF, matches each changed file to a coverage file by path suffix, and prints FILE: uncovered changed lines [..], or every changed, instrumented line is covered. A changed line the coverage file does not list counts as neither, so paths that do not match give the all-covered line. The skill tells the agent to fix the paths rather than report 100%.

Not tested on this wiki's run (it needs a git diff and a coverage file of the same tree); the repository's own tests cover the diff and coverage parsers.

lint

lint PATH... [--json] flags test code that cannot fail. A PATH is a file, or a folder searched for test files (test_*.py, *_test.py, *.test.js, *.spec.ts and the like, *Test.cs or *Tests.cs, *.spec.luau).

python scripts/tw.py lint tests/fixtures/bad_test.py
tests\fixtures\bad_test.py:4: assert True can never fail
tests\fixtures\bad_test.py:6: asserts only on mock calls; checks wiring, not behaviour
tests\fixtures\bad_test.py:11: test has no assertion (passes unless it throws)
3 finding(s)

Line findings: assert True, Assert.True(true) and Assert.IsTrue(true), Assert.Pass(), expect(true).toBe(true), a value compared with itself (assert x == x, expect(x).toBe(x), Assert.AreEqual(x, x)), a line that ends with .toBeDefined() or .not.toBeNull(), and a call to Assert.NotNull or Assert.IsNotNull. At most one line finding per line.

Test findings: a test block with no assertion of any kind, and a test that creates a mock (new Mock<, Substitute.For<, A.Fake<, vi.fn(, jest.fn(, MagicMock(, Mock(, mocker.patch) whose every assertion is a call check. Line findings print first, then test findings, so line numbers are not in order. These are text patterns, not a parse: a test split oddly across lines can be missed or flagged wrongly.

plan

plan [DIR] [--top N] [--json] ranks source files by risk, default top 15. Scoring: How the plan ranks files.

Clone this wiki locally