New contributors hitting a failing pnpm test:uat:preflight (or the equivalent E2E setup checks) currently have to dig through TESTING.md's "Environment Setup" prose to figure out what a given failure message means. There's no quick-reference troubleshooting section in README.md.
Task
Add a "Troubleshooting" section to README.md (or a linked doc) that maps each preflight failure message to its likely cause and fix, covering at minimum:
- Firefox version below 152 detected (or no Firefox binary found).
claude CLI not authenticated (claude /login needed).- Built
.xpi/extension zip missing (pnpm build not run).
- Fixture hash mismatch (
tests/uat/newtabtools_knowngood.zip stale or modified).
- UAT daemon port already in use / stale process.
geckodriver missing or wrong version.
Notes
- Source the exact failure message strings from
tests/uat/_tools/ (preflight script) and tests/e2e/run_esr_tests.sh so the troubleshooting entries are greppable — a user pasting the literal error should find the matching section.
- Cross-link from
TESTING.md's "Environment Setup" section rather than duplicating the install instructions.
New contributors hitting a failing
pnpm test:uat:preflight(or the equivalent E2E setup checks) currently have to dig throughTESTING.md's "Environment Setup" prose to figure out what a given failure message means. There's no quick-reference troubleshooting section inREADME.md.Task
Add a "Troubleshooting" section to
README.md(or a linked doc) that maps each preflight failure message to its likely cause and fix, covering at minimum:claudeCLI not authenticated (claude /loginneeded)..xpi/extension zip missing (pnpm buildnot run).tests/uat/newtabtools_knowngood.zipstale or modified).geckodrivermissing or wrong version.Notes
tests/uat/_tools/(preflight script) andtests/e2e/run_esr_tests.shso the troubleshooting entries are greppable — a user pasting the literal error should find the matching section.TESTING.md's "Environment Setup" section rather than duplicating the install instructions.