| name | tester |
| description | Scraper test execution rules, output validation criteria, and report format for the Tester agent |
| applyTo | .github/agents/tester.agent.md |
Tester Skills
Read this at the start of every session before running any test.
Scraper Testing
- Always run with
--dry-run first to avoid writing to DB during validation.
- Check
start_date is populated (not null) for every scraped event — missing dates are the most common data quality failure.
- Verify
source_id is stable across two separate runs before declaring a scraper production-ready. Run twice, diff the IDs.
- For TCC scraper: confirm
start_date is NOT the page update date (visible at the bottom of the page as 日付：).
Batch Repair Validation
- For any reset + re-annotate / backfill run, do not stop at command success or
annotation_status. Query the affected slice and verify the intended structural end-state (event_form, required template fields, missing translations) in DB.
- For publication backfills, confirm pure rows are exact-only (
event_form=['publication']) and mixed rows (for example ['publication', 'lecture']) are not folded into pure behavior.
- For pure publication rows, verify seven intentional-null fields and matching empty sentinels:
location_address, location_address_zh, location_address_en, business_hours, business_hours_zh, business_hours_en, location_prefectures.
- Preserve real DB prices (
is_paid, price_info, price_amount) and verify they are hidden only from pure-publication UI and JSON-LD. Price fields, location_name, and location_url must not enter the seven-field NULL/clear policy.
- For publication backfills, confirm publisher/organizer remains present and
missing_name_zh / missing_name_en are zero before calling the run a pass.
- When publication handling changes, include a writer-whitelist check (
scraper/database.py::_VALID_EVENT_FORMS includes publication) in regression validation.
- If the repaired slice includes named public figures or other high-risk proper nouns, add at least one human semantic spot check on
name_en / name_zh. GPT can fill all required fields while still hallucinating a person name.
Reporting
- Report failures with: source name, event title, field name, expected value, actual value.
- If > 20% of events from a source have null
start_date, escalate to Engineer before proceeding.
- Distinguish between logic errors (wrong field extracted) and selector errors (selector no longer matches).
Agent Tooling Baseline
- In
.github/agents/tester.agent.md, declare tools using aliases (read, search, execute, web) rather than raw function names.
- Before running source tests, perform a quick terminal preflight (any no-op command) to confirm
execute is available.
- Keep Tester read-only; do not add
edit unless the role is intentionally expanded.
- Standard activation path for this repo is
source ../.venv/bin/activate.
Shell Safety (zsh history expansion) — 2026-05-26
- Never embed bare
! characters in inline shell commands (e.g. python -c "print(repr(x))" with !r formatting flag). zsh expands !r, !$, !! from shell history before quoting takes effect, even inside single quotes.
- Always use quoted heredocs for multi-line scripts:
python3 - <<'PY' (note the quoted 'PY'). Quoted delimiter disables both variable interpolation and history expansion.
- If
! is unavoidable in a single-line command, escape it: \!r instead of !r.
- Always quote paths containing
[ or ] (for example app/[locale]/account/events/new/page.tsx) when passing them to zsh commands such as eslint, grep, or sed; otherwise zsh treats them as glob patterns and can fail with no matches found.
- Preflight (machines without
NO_BANG_HIST): [[ -o BANG_HIST ]] && echo "WARN: history expansion enabled, use heredoc".
- Detection signals during execution:
zsh: event not found, or an echoed command that doesn't match what you typed → stop immediately, do NOT press enter on follow-up prompts.
- This repo's owner shell has
setopt NO_BANG_HIST permanently set in ~/.zshrc since 2026-05-26 after a near-miss rm resurrection (see history.md 2026-05-26 entry).
After a Test Failure
- Append an entry to
.github/skills/agents/tester/history.md (newest at top).
- If the failing command already crossed a DB write boundary before crashing, immediately re-query the sample row and restore the pre-test state before continuing.
- If the lesson generalizes, add a rule to this file.
