Skip to content

docs: clarify local plugin test commands#1706

Open
anhtnt90dev wants to merge 1 commit into
obra:devfrom
anhtnt90dev:anhtnt90dev/docs-testing-plugin-commands
Open

docs: clarify local plugin test commands#1706
anhtnt90dev wants to merge 1 commit into
obra:devfrom
anhtnt90dev:anhtnt90dev/docs-testing-plugin-commands

Conversation

@anhtnt90dev

@anhtnt90dev anhtnt90dev commented Jun 8, 2026

Copy link
Copy Markdown

Who is submitting this PR? (required)

Field Value
Your model + version GPT-5 (exact model ID not exposed by Codex CLI)
Harness + version Codex CLI 0.137.0 on Windows/PowerShell
All plugins installed Browser, Documents, Presentations, Sites, Spreadsheets, Superpowers
Human partner who reviewed this diff anhtnt90dev approved the complete diff in Codex chat

What problem are you trying to solve?

While checking the plugin test surface from docs/testing.md, the current guidance only said to use the relevant directory's run-*.sh or npm test.

That left two concrete traps in my local contributor session:

  • Running npm test in tests/brainstorm-server before installing that test suite's dependency failed with Error: Cannot find module 'ws' from tests/brainstorm-server/server.test.js.
  • Running tests/brainstorm-server/windows-lifecycle.test.sh with a 120-second command timeout produced a false timeout. The test intentionally sleeps past the 60-second lifecycle check window twice, so it needs more than 150 seconds on Windows/Git Bash.

This PR documents the exact commands and time expectation that made those tests pass.

What does this PR change?

Adds a small "Fast local checks" section to docs/testing.md with the verified commands for the brainstorm server JS tests, shell lint wrapper tests, and Windows lifecycle test. It also documents the Git Bash invocation from PowerShell for Windows contributors.

Is this change appropriate for the core library?

Yes. This is contributor documentation for the core repository's existing test suites. It is not project-specific, team-specific, or a third-party integration.

What alternatives did you consider?

I considered adding a new root-level test runner, but that would be a larger tooling change and could overlap with existing test organization. I also considered changing the Windows lifecycle test timeout behavior, but the test's runtime is intentional because it verifies behavior past lifecycle check windows. A docs-only clarification addresses the actual contributor failure mode with less risk.

Does this PR contain multiple unrelated changes?

No. It only updates docs/testing.md to clarify local plugin test commands.

Existing PRs

#1703 and #1677 touch adjacent test/tooling areas but do not document these local commands. #1592 and #1655 are prior Windows brainstorm lifecycle fixes; this PR only documents how to run the existing test reliably.

Environment tested

Harness (e.g. Claude Code, Cursor) Harness version Model Model version/ID
Codex CLI on Windows/PowerShell 0.137.0 GPT-5 GPT-5 (Codex session; exact model ID not exposed by harness)

Authoring environment disclosure: generated with GPT-5 in Codex CLI 0.137.0. Installed Codex plugins available in the session: Browser, Documents, Presentations, Sites, Spreadsheets, Superpowers.

New harness support (required if this PR adds a new harness)

Not applicable. This PR does not add a new harness.

Clean-session transcript for "Let's make a react todo list"
Not applicable. This PR does not add a new harness.

Evaluation

  • What was the initial prompt you (or your human partner) used to start the session that led to this change?
  • How many eval sessions did you run AFTER making the change?
    • 0 LLM eval sessions. This is a docs-only change, not a skill behavior change.
  • How did outcomes change compared to before the change?
    • Before: following the broad npm test guidance in tests/brainstorm-server without npm ci failed with Cannot find module 'ws'; running the Windows lifecycle test with a 120-second timeout timed out even though the test is designed to run longer.
    • After: the documented commands match the successful local runs below.

Verification run after the change:

git diff --check HEAD~1..HEAD
# exit 0

cd tests/brainstorm-server && npm test
# Results: 25 passed, 0 failed

bash tests/shell-lint/test-lint-shell.sh
# All shell lint script tests passed

bash tests/brainstorm-server/windows-lifecycle.test.sh
# Results: 12 passed, 0 failed, 0 skipped

Rigor

  • If this is a skills change: I used superpowers:writing-skills and completed adversarial pressure testing (paste results below)
  • This change was tested adversarially, not just on the happy path
  • I did not modify carefully-tuned content (Red Flags table, rationalizations, "human partner" language) without extensive evals showing the change is an improvement

This is not a skills change. No skill text, prompts, red flags, rationalization lists, or behavior-shaping content were modified.

Human review

  • A human has reviewed the COMPLETE proposed diff before submission

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant