bug-reproduce-test

name

bug-reproduce-test

description

Reproduce a php-src bug captured in SPEC.md and convert it into a failing .phpt test. Use when the user says "reproduce the bug", "write a failing test for this issue", "/bug-reproduce-test", "make a phpt that captures GH-12345", "let's prove the bug exists", or otherwise wants to lock down a reproduction case for a php-src bug after /bug-context has been run. The test MUST fail on the current build — that is the post-guardrail.

bug-reproduce-test

Second step of the bug-fix flow. Reads the Context already in SPEC.md, builds a minimal PHP reproduction, converts it into a .phpt test under $PHP_SRC_DIR, runs it, and asserts it FAILS (TDD).

Inputs

1. SPEC.md in the task directory resolved per _shared/task-dir.md (env var → .current → cwd) with type: bug and Context phase done. Refuse otherwise.
2. $PHP_SRC_DIR with a built sapi/cli/php.

What it produces

• repro.php — minimal standalone reproduction script in the task directory, for the user's eyeballing
• $PHP_SRC_DIR/<tests-path>/ghNNNNN.phpt — the new test, following the conventions of the surrounding directory
• Updated SPEC.md: Reproduction phase populated, status → done once post-guardrail is green

Phase owned

Reproduction.

Steps this skill adds:

• repro-script — minimal repro.php reproduces the issue against $PHP_SRC_DIR/sapi/cli/php. Notes observed vs expected.
• phpt-failing — .phpt test created at the appropriate path; run-tests.php returns failure.

Workflow

1. Pre-guardrails

• SPEC.md exists and has type: bug. If type: idea, refuse with: idea SPECs don't use bug-reproduce-test.
• Context phase is done. If not, refuse with: Run /bug-context first.
• Research phase soft-check: if a Research phase exists with status todo, print one warning line and proceed:

  ⚠ Research phase still todo. Run /research first for prior-art (or mark it `skipped` in SPEC.md to silence this warning).
  

  done, skipped, or blocked → no warning. Status done → read Research findings; they may already pin a subsystem or hint at a prior test that captures the bug.
• Reproduction phase is todo or in-progress. If done, refuse with: Reproduction phase is already done. Run /bug-fix next. If blocked, refuse with: Reproduction is blocked: <reason>. Resolve before retrying.
• $PHP_SRC_DIR/sapi/cli/php exists. If missing, do not auto-build — output the build commands and stop:

  $PHP_SRC_DIR/sapi/cli/php missing. Build it first:
    cd "$PHP_SRC_DIR"
    ./buildconf
    ./configure --enable-debug
    make -j$(nproc)
  

• target_branch matches the checked-out branch. Read target_branch from SPEC.md frontmatter. If set (not null) and not equal to git -C "$PHP_SRC_DIR" rev-parse --abbrev-ref HEAD, refuse with:

  SPEC.md target_branch is <X>; $PHP_SRC_DIR is on <Y>.
  Switch with:
    git -C "$PHP_SRC_DIR" checkout <X>
    cd "$PHP_SRC_DIR" && make -j$(nproc)
  …or update target_branch in SPEC.md if the resolution was wrong.
  

  Do not auto-switch branches (CLAUDE.md: "Executing actions with care" — branch swaps trigger rebuilds the user may not want unprompted).
• If target_branch: null (resolver couldn't decide), refuse with: target_branch is null in SPEC.md. Resolve the Open Question raised by /bug-context before reproducing.

2. Build a minimal reproduction

Read Context in SPEC.md. Use the snippet there if present; otherwise construct one from the description.

Write repro.php in the task directory (not in php-src). Run it:

"$PHP_SRC_DIR/sapi/cli/php" -n "$TASK_DIR/repro.php"   # -n: no php.ini interference

Record observed vs expected. If outputs match expected behaviour, the bug doesn't reproduce — mark repro-script as blocked with the evidence and stop. Note that the bug may already be fixed on the current ref.

Mark repro-script as done once the observed output clearly demonstrates the bug.

3. Convert to .phpt

Pick the test path based on the subsystem hint from Context:

Subsystem	Test location pattern
ext/<name>/	ext/<name>/tests/ghNNNNN.phpt
Zend/	Zend/tests/ghNNNNN.phpt
main/streams/ etc.	tests/<area>/ghNNNNN.phpt
sapi/<name>/	sapi/<name>/tests/ghNNNNN.phpt

Name with the GH issue number: ghNNNNN.phpt. If a more descriptive name fits the surrounding directory's convention (look at sibling files), use it — but the GH number should appear in --TEST--.

Use --EXPECT-- when the output is deterministic. Switch to --EXPECTF-- only when the output legitimately contains a path, version, address, or other variable substring. See _shared/phpt-format.md for the full schema.

When target_branch is not master, add a --SKIPIF-- clause encoding the minimum version derived from the branch name per _shared/branch-detection.md § 4. For target_branch: PHP-8.3:

--SKIPIF--
<?php if (version_compare(PHP_VERSION, '8.3.0', '<')) die('skip 8.3+ only'); ?>

Derive the version string from the branch name, not from a hardcoded literal. When target_branch: master, omit --SKIPIF--.

Skeleton:

--TEST--
<short title> (GH-NNNNN)
--FILE--
<?php
<minimal code from repro.php>
?>
--EXPECT--
<the OUTPUT WE WANT after the fix is applied>

The expected output is the post-fix expectation, not what the buggy code emits today. That's why the test fails now and passes after the fix.

4. Run the test — expect failure

cd "$PHP_SRC_DIR"
sapi/cli/php run-tests.php -v <test-path-relative-to-PHP_SRC_DIR>

Inspect the result:

• FAIL → expected. Mark phpt-failing as done, Reproduction phase as done. Append Progress Log.
• PASS → the test doesn't capture the bug. Mark phpt-failing as blocked with: Expected output matches current buggy output — adjust the --EXPECT-- to reflect post-fix behaviour. Stop.
• SKIP / BORK → infrastructure issue. Mark blocked with the runner's reason.

The .diff file shows the divergence — if it matches the documented bug behaviour, you're good.

5. Update SPEC.md

Populate Reproduction phase steps with the file paths and command outputs. Append one Progress Log line:

2026-05-16 14:18 — bug-reproduce-test — phpt-failing at <path> FAILs as expected; .diff shows <one-line summary>

6. Report

Reproduction phase complete.
- repro.php: <task-dir>/repro.php
- new test:  $PHP_SRC_DIR/<tests-path>/ghNNNNN.phpt — FAIL (expected)
- .diff:     $PHP_SRC_DIR/<tests-path>/ghNNNNN.diff

Next: run /bug-fix

Boundaries

• No source-code changes in Zend/, main/, ext/<name>/<src>, etc. Only the test file.
• Stage the new .phpt with git add <path> after run-tests.php FAILs. Do NOT commit — /bug-fix will commit test + fix together as one commit. Never git push, git remote *, or git pull.
• No --CREDITS-- in the new test. Git tracks authorship.
• No new test infrastructure: use only --SKIPIF--, --EXTENSIONS--, --INI--, --FILE--, --EXPECT[F]--, --CLEAN--. Don't introduce a new test-runner pattern just for this bug.

Edge cases

Situation	Handling
Bug only reproduces under specific INI	Add --INI-- section.
Bug only reproduces with a specific extension	Add --EXTENSIONS--.
Bug requires a specific PHP version	The --SKIPIF-- is already emitted when target_branch != master (see § 3). For tighter constraints than the branch minimum, narrow the version_compare check and document the constraint in Context.
Output contains paths/PIDs/addresses	Use --EXPECTF-- with %s/%i/%a. Prefer narrow specifiers.
Bug needs interactive input	Use --CAPTURE_STDIO-- + --FILE-- driving stdin via a heredoc. If genuinely interactive (e.g. phpdbg), mark phpt-failing as blocked with reason; document a manual repro script.
Test path's parent directory doesn't exist	Create it (mkdir -p); flag in the step body.
Sibling tests use snake_case names	Match their style (some_feature_001.phpt); still mention GH-NNNNN in --TEST--.
Reproduction depends on a build of a specific branch	The new target_branch pre-guardrail (§ 1) already catches a mismatch. If target_branch was set wrong, the user updates SPEC.md and re-runs; if right, the user switches $PHP_SRC_DIR. Never switch on their behalf.

Quality checklist

• --TEST-- line mentions GH-NNNNN
• Test path is consistent with sibling tests in the chosen directory
• --EXPECT-- (or --EXPECTF--) reflects post-fix behaviour, not current buggy output
• run-tests.php exit code captured; FAIL verdict recorded
• .diff content (or excerpt) is summarised in the step body
• Reproduction phase guardrail (new .phpt fails) is checked
• Progress Log appended
• No code changes outside the new .phpt and repro.php in the task dir

Out of scope

• Locating the offending C code — /bug-fix
• Fixing the bug — /bug-fix
• Running the broader regression suite — /bug-verify