0 Fork 0

mirror of https://github.com/ksyasuda/SubMiner.git synced 2026-10-21 05:01:26 -07:00

Files

T

sudacode 78eca52b7e test: add headless end-to-end harness (#286 )

* test: add headless end-to-end harness and CI job

Boot the built app against a real mpv, a synthetic clip, a fixture Yomitan
dictionary, and a fake AnkiConnect inside a private Xvfb display, then assert
on the overlay DOM and the AnkiConnect requests. Adds the test:e2e lane, an
e2e session CLI for exploratory checks, and a three-platform CI job.

* ci: set e2e temp dir from a step

* test: make e2e session startup robust on slow machines

Bun caps node:test hooks at 5s, so boot the session inside the first test.
Keep pausing until the app's resume retries stop, read cue tokens in one
round trip, and resolve Electron through its package entry so CI downloads
the binary.

* test: harden e2e harness for CI runners

Fail fast when mpv cannot be spawned, read every Yomitan popup frame instead
of trusting target order, and put the chocolatey mpv directory on PATH.

* test: add e2e failure diagnostics and mark Windows job experimental

Report what the overlay showed when a cue never renders, dispose the session
when the overlay cannot be opened, skip popup frames that vanish mid-poll,
and turn off AniSkip lookups in the harness config.

* test: read the lookup popup entry from textContent

* test: capture renderer console and main-side subtitle state in e2e failures

* test: expose the Electron main-process inspector to the e2e harness

Adds session.mainProcess() and 'e2e eval main', and reports main's window
list alongside the overlay state when a cue never renders.

* test: tap subtitle sends and receipts in e2e failure diagnostics

* test: probe alternate main-to-renderer paths in e2e failure diagnostics

* test: select the visible overlay layer, not the primed modal window

Windows and macOS pre-create a hidden modal window that loads the same
renderer document, and the harness could attach to it instead of the
visible overlay. Drops the delivery taps that found this.

* ci: run the Windows e2e job as a normal matrix entry

* test: address review on e2e harness

Slice the app log at a byte offset before decoding, create the session state
file owner-only since it carries the inspector URL, and keep the cue failure
when inspector diagnostics are unavailable.

* test: create the e2e session state file exclusively

2026-10-05 22:00:58 -07:00

5.2 KiB

Raw Permalink Blame History

AGENTS.md

Internal Docs

Start here, then leave this file.

Internal system of record: docs/README.md
Architecture map: docs/architecture/README.md
Workflow map: docs/workflow/README.md
Verification lanes: docs/workflow/verification.md
Testing guidelines: docs/workflow/testing.md
Knowledge-base rules: docs/knowledge-base/README.md
Release guide: docs/RELEASING.md

docs-site/ is user-facing. Do not treat it as the canonical internal source of truth.

CLAUDE.md is a symlink to this file; there is one project instruction file, not two.

Quick Start

Init workspace: git submodule update --init --recursive
Install deps: make deps or bun install plus (cd vendor/texthooker-ui && bun install --frozen-lockfile)
Fast dev loop: make dev-watch
Full local run: bun run dev
Verbose Electron debug: electron . --start --dev --log-level debug

Build / Test

Runtime/package manager: Bun; use the version pinned by package.json.
Follow docs/workflow/verification.md and start with the cheapest sufficient lane.
Full handoff gate for substantial changes: bun run typecheck bun run test:fast bun run test:env bun run build bun run test:smoke:dist
If docs-site/ changed, also run: bun run docs:test bun run docs:build
Prefer make pretty and bun run format:check:src

Change-Specific Checks

Config/schema/defaults: bun run test:config; if template/defaults changed, bun run generate:config-example
Launcher/plugin: bun run test:launcher or bun run test:env
Runtime-compat / dist-sensitive: bun run test:runtime:compat
Stats dashboard UI (stats/): bun run test:stats
Overlay / renderer / mpv / mining behavior in the running app: bun run build, then bun run test:e2e (headless, sandboxed; bun run e2e start for exploratory checks)
Build/release scripts (scripts/**): bun run test:scripts
Internal docs, AGENTS.md, or repo skills: bun run test:docs:kb
User-facing docs-site/: bun run docs:test, then bun run docs:build
macOS mpv window helper (scripts/get-mpv-window-macos.swift): compile it on macOS with bun run build
Test lanes are directory-discovered via scripts/test-lanes.ts; never hand-list test files in package.json

Docs Upkeep

Docs ship with the change, not after. If a change alters behavior, defaults, flags, shortcuts, ports, or APIs, update the matching docs in the same PR. Touching code without reconciling its docs is an incomplete change.
Source of truth for config defaults is the generated config.example.jsonc. Never write a default value into prose you didn't read from it, and don't restate the same default across multiple docs; cite/link to one place so there's a single thing to update.
Trigger map (touch left → update right):
- src/config/definitions/** (schema/defaults/template) → bun run generate:config-example, then reconcile docs-site/configuration.md + any feature doc that cites that default
- shortcuts/keybindings (shortcuts.*, keybindings, stats.*Key, subtitleSidebar.toggleKey, controller bindings) → docs-site/shortcuts.md
- CLI flags/subcommands (src/cli/args.ts, launcher/**) → docs-site/usage.md + relevant integration doc
- feature behavior (anki / jellyfin / jimaku / anilist / youtube / immersion / stats / websocket / sidebar / character-dictionary / annotations) → matching docs-site/<feature>.md
- architecture / IPC / workflow / internal process → internal docs/ (system of record)
- feature set / requirements / install flow → README.md
Removing or renaming a config key: grep docs-site/ and docs/ for the old key and any value it documented; legacy/hidden keys (LEGACY_HIDDEN_CONFIG_PATHS) should not appear in user docs as current settings.
Verify after doc edits: bun run verify:config-example (if config touched), bun run docs:test, bun run docs:build.

Sensitive Files

Launcher source of truth: launcher/*.ts
Generated launcher artifact: dist/launcher/subminer; never hand-edit it
Repo-root ./subminer is stale; do not revive it
bun run build rebuilds bundled Yomitan from vendor/subminer-yomitan
Do not change signing/packaging identifiers unless the task explicitly requires it

Release / PR Notes

User-visible PRs need reconciled current-outcome fragment(s) in changes/*.md. Format and rules live in changes/README.md (type + area keys required; inspect existing same-PR fragments, then update/remove stale bullets or add only genuinely separate outcomes; apply the skip-changelog label to opt out).
User-visible docs changes get a type: docs fragment
CI enforces bun run changelog:lint and bun run changelog:pr-check
PR review helpers:
- gh pr view --json number,title --jq '"PR #\\(.number): \\(.title)"'
- gh api repos/:owner/:repo/pulls/<num>/comments --paginate
For CI debugging, inspect runs with gh run list/view; rerun or fix only within the requested scope.

5.2 KiB Raw Permalink Blame History