project-testing

name	project-testing
description	Test commands, fixtures, and validation patterns for update-ipsets. MUST be followed for test work.

Test stack

• Go standard testing package with colocated *_test.go files (evidence: go.mod, cmd/, internal/, pkg/, and tools/ test files).
• Common helpers: t.TempDir, inline fixtures, table-driven subtests, and httptest.NewServer.
• UI uses Vitest, Testing Library, user-event, jest-dom, MSW, jsdom, vitest-axe, and V8 coverage for black-box behavioral component tests (evidence: ui/package.json, ui/vitest.config.ts, ui/vitest.setup.ts, ui/src/test/).
• UI test files are linted with eslint-plugin-testing-library scoped to *.test.{ts,tsx} (evidence: ui/eslint.config.js).
• Fuzz tests exist in pkg/iprange, pkg/config, and pkg/processor; make fuzz-replay replays the committed seed corpus shape with go test -run=Fuzz and is wired into CI.
• Tool versions come from manifests: Go 1.26.4 in go.mod, React/Vite/TypeScript/Tailwind in ui/package.json.
• Go analysis tool versions are pinned in Makefile: govulncheck v1.3.0, Staticcheck v0.7.0, and golangci-lint v2.11.4.

Canonical commands

• Main Go module: make test, make race, make lint, make coverage, make vulncheck, make staticcheck, make golangci-lint, make fuzz-replay, and make bench (evidence: Makefile).
• JSON codec benchmark comparisons: make jsonbench runs the isolated tools/jsonbench module so third-party JSON candidates can be measured without adding them to the main application dependency graph.
• Nested tool modules: make test-tools (currently covers tools/dronebl2ipsets). make race also runs the nested module's race tests, and make coverage-tools writes tools/dronebl2ipsets/coverage.out for its separate coverage gate.
• UI behavioral tests: make ui-test or pnpm --dir ui test. The package script disables Node 25 experimental Web Storage for Vitest because Node's global localStorage path emits --localstorage-file warnings in the jsdom worker context.
• UI browser smoke tests: make ui-e2e or pnpm --dir ui test:e2e. These build the production bundle first and run the small Chromium Playwright suite under ui/e2e/. The package script clears NO_COLOR for Playwright because the runner sets color forcing internally and Node warns when both NO_COLOR and FORCE_COLOR are present.
• Strict flake/order smoke for scheduler, engine, and web packages: make test-strict (go test -shuffle=on -count=3 ./pkg/scheduler ./pkg/engine ./pkg/web).
• Direct coverage command used by CI: make coverage for the root module and make coverage-tools for tools/dronebl2ipsets (evidence: .github/workflows/ci.yml).
• Codacy coverage upload is owned by the CI coverage job. It uploads the root coverage.out and tools/dronebl2ipsets/coverage.out reports only on trusted push events to main or master, using CODACY_API_TOKEN and Codacy's Go coverage parser. Pull-request runs intentionally skip the upload so untrusted/fork/Dependabot contexts do not need Codacy secrets.
• Embedded admin UI static is generated by make ui-static. Root Go build/test/coverage/race/strict/cross targets depend on it so clean CI checkouts build the same pkg/web/static/index.html and pkg/web/static/assets/ shape that install.sh embeds. Direct go test ./... from a clean checkout is not the release gate because pkg/web compile-time embeds the generated SPA shell.
• Nested DroneBL module when touched: cd tools/dronebl2ipsets && go test ./... (evidence: nested tools/dronebl2ipsets/go.mod; root go test ./... does not enter nested modules).
• UI changes: pnpm --dir ui install --frozen-lockfile, pnpm --dir ui test, pnpm --dir ui build, and pnpm --dir ui lint (evidence: install.sh, ui/package.json).
• Root ESLint bridge changes: make eslint-root-config or pnpm --dir ui test:eslint-root-config verifies that repository-root eslint.config.mjs imports the UI flat config, resolves TS/TSX/JS/MJS file shapes, applies the UI TypeScript rules, and applies Node script rules for modern .mjs maintenance scripts covered by Codacy/GitHub scanners.
• UI pnpm build-script policy lives in ui/pnpm-workspace.yaml; keep pnpm 11 CI installs green by classifying dependency lifecycle scripts there.
• UI bundle-size changes: make ui-budget or pnpm --dir ui build:budget. The budget checker reads ui/dist/assets after a production build, matches stable chunk-name prefixes, and does not require generated assets to be committed.
• Browser-level UI changes: install the selected Playwright browser runtime with pnpm --dir ui exec playwright install chromium, then run make ui-e2e. CI installs Chromium with system dependencies before this gate.
• Install verification when runtime behavior changes: ./install.sh, then smoke endpoints (evidence: install.sh, README.md).

CI facts

• GitHub Actions validates Go build/test/race/vet/cross-build, strict shuffled tests, fuzz seed replay, blocking govulncheck, blocking staticcheck, blocking golangci-lint, and 50% coverage thresholds for both the root module and tools/dronebl2ipsets (evidence: .github/workflows/ci.yml).
• UI install, behavioral tests, lint, and build are wired into CI (evidence: .github/workflows/ci.yml).
• Root go test ./... does not cover the nested tools/dronebl2ipsets module; make test-tools, make race, make coverage-tools, make vulncheck, make staticcheck, and make golangci-lint explicitly enter that module.

Fixture patterns

• Prefer small inline YAML, text, JSON, and archive fixtures in tests.
• Use t.TempDir() for filesystem state; do not write into repo source paths.
• Test fixtures should use restrictive file and directory modes (0600 for files, 0700 for directories) unless the test explicitly verifies a public/shared mode contract. Do not use 0644/0755 as generic fixture defaults.
• Use httptest for downloader and web/API behavior.
• Treat configs/firehol/ as a real catalog fixture for catalog validation tests.
• When catalog source inventory changes, update all duplicated source-count assertions, not only pkg/config/catalog_verify_test.go; search for the old count across pkg/config, pkg/processor, and other test packages (from SOW-0008).
• Feed-catalog changes need installed-service validation that affected feeds publish committed public sets; URL checks and parser smoke counts alone do not prove the downloader-to-processor-to-publication path completed (from SOW-0008).
• Provider/catalog role changes need tests for both catalog/provider membership and generated artifact coverage, plus serving-path tests showing public routes do not generate missing feed-scoped artifacts on request (from SOW-0025 regression).
• Engine tests must use the package-local newEngineFixture helper instead of direct &Engine{} literals. pkg/engine/engine_fixture_test.go contains an AST regression guard that enforces this construction boundary (from SOW-0046).
• Same-package Go tests may call unexported helpers only when the helper is an internal algorithm or writer contract where exported behavior would be much slower, broader, or less precise. When an exported engine API already exposes the same behavior, use the exported API instead (from SOW-0049).
• New Go tests for packages with stable exported APIs should default to an external pkg_test package. Keep same-package tests for internal algorithms, package fixtures, global registries, or lock/queue invariants only when the SOW or test comments make the contract reason clear (from SOW-0064).
• ASN/geolocation default-provider changes need tests for config validation, default-first provider API ordering, engine preferred-provider selection, and default-provider drift marker behavior that forces rebuilds after config changes (from SOW-0028).
• Static config-backed feeds need tests for validation and end-to-end staging: static: YAML lines must materialize through the normal raw source, processor, and finalized set path, not through hardcoded internal providers (from SOW-0017).

Real-use validation

• API/server changes: run the daemon or installed service and verify with curl against /healthz, /api/v1/status, /api/v1/sets, and affected admin/public routes.
• Integrity/mtime changes require installed-service validation: run ./install.sh, use admin repair/reprocess endpoints rather than manual file edits, and verify both /api/v1/admin/integrity and /api/v1/admin/integrity/entities return clean after background work settles (from SOW-0017 regression).
• UI changes: run pnpm --dir ui build and pnpm --dir ui lint; install when generated static assets or embedded serving are involved.
• UI route-splitting changes need a browser smoke check against the embedded serving model or installed service that proves the changed route loads through the lazy boundary. Record any build-time asset warnings separately from functional failures (from SOW-0033).
• Playwright smoke tests run against ui/e2e/static-server.mjs, not vite preview. The production bundle uses /static/ as its public asset base; vite preview treats that as the app base too, while the embedded Go server serves public routes from / and assets from /static/*. Keep the browser test server aligned with the Go serving model (from SOW-0054).
• UI component tests must stay black-box behavioral: render real components through ui/src/test/render.tsx, drive interactions with userEvent, mock backend boundaries with MSW handlers, and assert visible roles/text/links, accessible names, URL/navigation outcomes, or request parameters. Do not mock hooks, child components, TanStack Query, or internal state (from SOW-0034).
• New UI tests should be colocated as *.test.tsx next to the component or page under test. Shared test helpers and fixtures belong under ui/src/test/ (from SOW-0034).
• Page/component tests that cover accessible flows should include a small vitest-axe check when the jsdom surface can represent the behavior. Disable jsdom-impossible rules such as color-contrast locally instead of accepting noisy failures (from SOW-0034).
• Treat actionable vitest-axe findings as product bugs, not test noise. Fix source issues such as unlabeled form controls, empty table headers, missing dialog labeling, and nested interactive controls before disabling a rule. Disable only checks that jsdom cannot evaluate faithfully (from SOW-0052).