agentleFS
Sign inStart free
3metaJun3metaJun/mstack/skills/principle-test-behavior-not-implementation/SKILL.md

principle-test-behavior-not-implementation

Skill0 starsChanged 27 days agoMITView on GitHub

Apply when you write, change, or keep a test. Call the code the way its users do and assert the result they observe against a literal expected value. If the test would still pass when every imported function returns undefined, rewrite the assertion or delete the test.

We split this skill into the rules it gives an agent

1 rule. 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 30 edited versions we read keep these.

  • 0

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Mock or absence only: Only toHaveBeenCalled, not.toHaveBeenCalled, toBeUndefined, toEqual([]), toHaveLength(0), not.toBe(wrongValue).

    line 17

“Common” is measured: kept by at least 6 in 10 of the 30 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Test Behavior, Not Implementation

A test calls the code the way its users do and asserts the result they observe against a literal expected value. A test that asserts which calls the code made, or restates a constant the code contains, does neither.

The check: before you keep a test, ask whether it would still pass if every function it imports returned undefined. If yes, it observes no behavior and cannot fail for a defect. Rewrite the assertion or delete the test.

Why: A test that cannot fail for a defect costs CI time and review attention and catches nothing. A constant pin also fails when someone edits the constant or the prompt it restates, so it prevents that edit.

Five shapes that still pass when every imported function returns undefined:

  • Weak or no assertion. No expect, or only toBeDefined, toBeTruthy, not.toThrow, toBeInstanceOf, toBeGreaterThan(0).
  • Mock or absence only. Only toHaveBeenCalled, not.toHaveBeenCalled, toBeUndefined, toEqual([]), toHaveLength(0), not.toBe(wrongValue).
  • Self-referential. The expected value comes from the code under test: expect(f(a)).toBe(f(a)), expect(parsed.url).toBe(buildUrl(...)).
  • Constant pin. The assertion restates a hand-maintained constant, config default, table row, or prompt string: expect(LIMITS.maxTools).toBe(8), expect(PROMPT).toContain("You are").
  • Fixture asserts fixture. The assertion reads data the test built or a value computed in beforeEach, and the subject never runs inside the body.

The fix: call the subject inside the test body with one concrete input and assert the literal output or the observable effect, expect(slugify("Hello, World!")).toBe("hello-world"). For an absence, assert the presence on the other input in the same test. For a constant, test the mechanism that reads it with one input instead of restating the value. For a mock, assert the payload it received or the state after the call, not that it was called. When no such assertion exists, delete the test.

Keep a test of a relation across a table's rows (a key present in two tables, a parent that exists), and a compile-time check in a *.test-d.ts file.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free