TheRock/rocm-systems/projects/amdsmi/.claude/skills/test-driven-development/SKILL.md

name, description

name	description
test-driven-development	Use when implementing any amd-smi feature, bug fix, or behavior change — before writing implementation code. Enforces strict RED-GREEN-REFACTOR: failing test first, watch it fail, minimal code to pass, refactor.

Test-Driven Development — amd-smi

Write the test first. Watch it fail. Write minimal code to make it pass.

Core principle: If you didn't watch the test fail, you don't know what it tests.

Violating the letter of the rules is violating the spirit of the rules.

The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Wrote code before the test? Delete it. Start over from the test.

No exceptions:

• Don't keep it as "reference"
• Don't "adapt" it while writing the test
• Don't peek at it
• Delete means delete

When to Use

Always:

• New amdsmi_* API functions
• CLI command additions or behavior changes
• Bug fixes (write the test that reproduces the bug first)
• Refactors that change observable behavior

Exceptions (ask first):

• Pure auto-generated files (amdsmi_wrapper.py)
• Build/packaging-only changes with no testable behavior
• Throwaway diagnostic scripts

Thinking "this is too simple for a test"? Stop. That's rationalization.

Red-Green-Refactor

RED  → write one minimal failing test
     ↓
verify it fails (and fails for the right reason)
     ↓
GREEN → minimal code to make it pass
     ↓
verify it passes; all other tests still pass
     ↓
REFACTOR → clean up while staying green
     ↓
repeat for the next behavior

RED — Write the Failing Test

One behavior. Clear name. Real code (no mocks unless unavoidable).

C++ (GTest) example:

TEST_F(AmdSmiTest, GetGpuPowerCapHandlesInvalidHandle) {
    uint64_t cap = 0;
    amdsmi_status_t status = amdsmi_get_power_cap(nullptr, 0, &cap);
    EXPECT_EQ(status, AMDSMI_STATUS_INVAL);
}

Python example:

def test_get_gpu_power_cap_raises_on_invalid_handle():
    with pytest.raises(AmdSmiLibraryException) as exc:
        amdsmi.amdsmi_get_power_cap(None)
    assert exc.value.err_code == amdsmi.AmdSmiRetCode.STATUS_INVAL

Verify RED — Watch It Fail

MANDATORY. Never skip.

# C++
cd build && make -j$(nproc) amdsmitst && \
  ./tests/amd_smi_test/amdsmitst --gtest_filter=AmdSmiTest.GetGpuPowerCapHandlesInvalidHandle

# Python
cd tests/python_unittest && python3 -m pytest -v -k test_get_gpu_power_cap_raises_on_invalid_handle

Confirm:

• Test fails (not errors out)
• Failure message matches what you expected
• It fails because the behavior is missing, not because of a typo

Test passes immediately? You're testing existing behavior. Fix the test.

GREEN — Minimal Code

Simplest code that makes the failing test pass. No extra features, no flexibility flags, no "while I'm here" improvements.

Verify GREEN

MANDATORY.

Re-run the same test. Confirm pass. Then run the relevant suite to confirm nothing else broke.

REFACTOR — Clean Up

After green only. Remove duplication, improve names, extract helpers. Keep tests green. Don't add behavior.

Repeat

One failing test for the next behavior.

One Test at a Time — No Horizontal Slicing

Do NOT write all the tests first, then all the implementation. Treating RED as "write every test" and GREEN as "write every implementation" is horizontal slicing and it produces crap tests:

• Bulk-written tests verify imagined behavior, not actual behavior.
• You end up testing the shape of things (signatures, struct fields) instead of observable behavior.
• The tests go insensitive to real changes — they pass when behavior breaks.

Correct approach — vertical slices (tracer bullets): one test → one minimal implementation → repeat. Each test responds to what the previous cycle taught you.

WRONG (horizontal):
  RED:   test1, test2, test3, test4
  GREEN: impl1, impl2, impl3, impl4

RIGHT (vertical):
  RED→GREEN: test1→impl1
  RED→GREEN: test2→impl2
  ...

amd-smi cascade caution: it's tempting, when adding a C API function, to write the GTest and the Python unit test and the CLI test all up front. Don't. Drive one tracer bullet end-to-end first (e.g. C++ behavior), then add the next layer's test once that layer exists. The cascade is still fully tested — just one slice at a time, not all tests before any code.

Good Tests

Quality	Good	Bad
Minimal	One thing. "and" in the name? Split it.	test('validates handle and reads register and formats output')
Clear name	test_get_power_cap_returns_inval_on_null_handle	test_power_1
Real code	Calls the actual amdsmi_* function	Mocks the function being tested
Observable	Tests behavior the user sees	Tests internal state nobody else can read

Rationalizations — Reality

Excuse	Reality
"I'll write tests after to verify it works"	Tests-after pass immediately and prove nothing. You never saw them catch the bug.
"I already manually tested all edge cases"	Manual testing is ad-hoc, undocumented, and doesn't re-run on CI.
"Deleting X hours of work is wasteful"	Sunk cost. Working code without real tests is technical debt.
"TDD is dogmatic, being pragmatic means adapting"	TDD IS pragmatic — finds bugs before commit, prevents regressions, enables refactoring.
"Tests-after achieve the same goal — it's about spirit"	No. Tests-after answer "what does this do?" Tests-first answer "what should this do?"
"This is just a one-line fix"	One-line fixes have caused production outages. Write the test.
"The CI will catch it"	CI catches what you tested. If you didn't write the test, CI is blind.

Red Flags — STOP and Start Over

• Code before test
• "I already verified it manually"
• "Tests after achieve the same purpose"
• "It's about the spirit, not the ritual"
• "This case is different because..."
• Watching the test pass without ever seeing it fail
• Adding production code while writing the test
• Writing every layer's test up front before any implementation (horizontal slicing)

All of these mean: delete the code, start over with the test.

amd-smi-Specific Notes

• Cascade testing: A new API function needs tests at multiple layers — at minimum the C++ GTest and a Python unit test. CLI changes need a CLI test.
• Hardware dependency: Most amd-smi tests require an AMD GPU. If your test cannot run on the dev box, say so in the test plan in the spec; don't silently skip the RED step.
• Auto-generated wrapper: When adding a C function, the wrapper regen is part of the GREEN step, not a separate "fix later".

Required Companion Skills

• systematic-debugging — when a test fails in a way you don't understand
• verification-before-completion — after every commit