Both round-2 reviewers returned BLOCKED, and the sharpest findings were defects the previous fix commit introduced rather than ones it missed. The mechanism that fix added was untested. Deleting EnsureBuiltInElementRow from the ALREADY-SEEDED branch left the whole 2054-test suite green - and that is the branch every install carrying #74's marker takes on its first #732 boot, i.e. exactly the population the fix exists for. The previous commit message claimed the marker "is only ever written against a resolved element"; that was proven only for the fresh-seed minority. Same shape for the duplicate guard inside it: without the guard the already-seeded branch inserts a row on every boot, RefreshGraphicsElements neither reaps nor dedupes them, and the SPA list fills with copies. Both now have tests, and both were confirmed to redden. That claim was also still false. With the template file absent, EnsureBuiltInElementRow returns without creating a row and the marker was written anyway - a narrower version of the stranding bug round 1 found. The backfill now stays armed when nothing resolves. This is safe in a way it was not in round 1: EnsureBuiltInElementRow closed the "row appears later" window that argued against it. The clamp only shrank insetPixels, not the box. DrawBackgroundBox kept stroking at the original border width, centred on a rect with no room for it, so an oversized border flooded the element and painted over its interior. The box's own fields are clamped now, border first. The catch was over-corrected. Round 1 asked for it to be broader; everything-but-cancellation swallows genuinely fatal failures and boots a compromised process. It is a named filesystem set again, plus a carve-out for an OperationCanceledException raised while the token is NOT cancelled - that one is just a faulty read, and letting it escape is the restart loop the catch exists to stop. The template rewrite was not atomic: WriteAllTextAsync truncates first, so an interrupted write left a partial file matching no fingerprint, which the upgrade could then never repair, on a template now attached to every channel. Write-then-move, with the temp file cleaned up on failure. Also: YAML doubles like 1e100 and NaN reach float/int casts, so box dimensions are sanitized at the boundary; the built-in row is created with a Name so it does not sort into the unnamed bucket in the SPA until the first refresh; CreateChannelHandler threads the real cancellation token. Decisions-Edit: yes Refs: #732
8.6 KiB
Testing map
Purpose: authoritative map of what each test project/suite covers and how to run it. Read this
before adding tests, not just docs/contributing.md §8 (which now just points here).
Test projects
Font dependency (ersatztv#732).
Infrastructure/Graphics/TextElementBackgroundBoxTestsis the only suite that rasterises text, so it needs at least one system font to lay anything out. The CI image installs none explicitly — fonts arrive viaplaywright install --with-depsindocker/ci/Dockerfile(351 present in the pinned image, measured 2026-08-26). This is a real dependency, declared here so a future slimming of that install produces a known cause rather than a mystery red.Baseline_Renders_A_Non_Empty_Bitmapexists to make that failure loud: without it a fontless host would render a 0x0 bitmap and every relative geometry assertion would pass vacuously.
| Project | Covers | Notes |
|---|---|---|
ErsatzTV.Tests |
API controllers + MediatR handlers, plus the SkiaSharp text-overlay rasteriser (Infrastructure/Graphics/) |
In-memory SQLite fixture: a shared SqliteConnection("Data Source=:memory:;Foreign Keys=False") kept open + EnsureCreatedAsync() (not full migration replay) + PRAGMA foreign_keys=OFF, then seed; a tiny IDbContextFactory wraps new TvContext(...). ~1,870 tests (approximate on purpose — an exact count goes stale on every PR that adds one; the previous hardcoded 828 was off by over a thousand). |
ErsatzTV.Core.Tests |
Domain logic, scheduling, IPTV/XMLTV generation | References ErsatzTV.Application directly — there is no separate Application.Tests project. ~650 tests + 1 skipped under TZ=UTC (the Block playout golden additionally skips under a non-UTC TZ; see Golden-file nets). |
ErsatzTV.Scanner.Tests |
Library scanning: scan handlers, folder scanners, NFO readers | Handler tests substitute the folder scanners + ILibraryRepository and assert the resulting repository writes (e.g. ScanLocalLibraryHandlerTests pins which LastScan levels a scan records — ersatztv#264). Fakes/Testably back the file-system-facing scanners. ~1,485 tests (approximate on purpose — an exact count goes stale on every PR that adds one). Additionally contains Core/FFmpeg/TranscodingTests — [Explicit] + [Combinatorial], so it never runs in CI or a plain dotnet test (it needs real ffmpeg/hardware) and contributes 0 to that count; run it by name when touching the transcoding pipeline. |
ErsatzTV.Architecture.Tests |
Layering rules via NetArchTest.eNhancedEdition | Core↛Infra/App/EF; FFmpeg↛all; App↛concrete providers. 5 tests. See docs/contributing.md §1. |
ErsatzTV.FFmpeg.Tests |
FFmpeg command construction | Build a pipeline, assert the exact rendered arg string (PipelineBuilderBaseTests.cs). |
web/ (vitest) |
React SPA unit tests | 995 tests across 105 files; run alongside typecheck + build (see below). Collects src/** and web/scripts/**, but deliberately excludes web/e2e/** (the Playwright specs — vitest's default **/*.spec.* glob would otherwise run them under jsdom). |
web/e2e/ (Playwright) |
UI-interactive E2E flows against a live instance | Not a unit suite and not part of npm test — needs a running server, so it runs via scripts/e2e-ui.sh (boots its own fresh instance) and in CI as a step of the functional-e2e job. Headless Chromium, serial, retries: 0. Scope rule: assert only what the curl harness structurally cannot. See docs/e2e-local.md → "UI-E2E harness". |
Golden-file nets
Three golden-file suites guard the highest-value, most-subtle output:
- M3U:
ErsatzTV.Core.Tests/Iptv/ChannelPlaylistGoldenTests.cs(ersatztv#11) — env varETV_UPDATE_GOLDENS - XMLTV:
ChannelGuideGoldenTests(ersatztv#28) — env varETV_UPDATE_GOLDENS - Playout build:
ErsatzTV.Core.Tests/Scheduling/Goldens/PlayoutBuildGoldenTests.cs(ersatztv#163) — env varETV_UPDATE_PLAYOUT_GOLDENS(deliberately separate fromETV_UPDATE_GOLDENSso regenerating one net can't silently rewrite the other). Snapshots thePlayoutItems each builder produces over a pinned build window. Covers the Classic (PlaybackOrder.Chronological), Block, and Sequential (YAML) builders. The Scripted end-to-end pipeline is excluded from this net —ScriptedPlayoutBuilderruns a user-authored external process that drives the engine over HTTP, which the in-memory harness can't pin; that integration harness is tracked in ersatztv#563. The scheduling behavior those scripts drive, though, lives in the in-processSchedulingEngine(the HTTP controller is a 1:1 pass-through) and IS directly testable —SchedulingEngineTestsnews it up with substitutes, andContentEnumeratorBuilderTests(ersatztv#395) is the direct regression net over the enumerator-construction helper the Scripted and Sequential/YAML engines now share (decision:testing.scripted-playout-golden-deferred). The Sequential case (Sequential_yaml, ersatztv#381) builds from a committed YAML fixture (Goldens/Fixtures/sequential-schedule.yml) instead of aProgramSchedule; it is TZ-independent (thecount/all/durationhandlers do UTC-only arithmetic — it passes, not skips, under a non-UTCTZ) so needs noAssumeguard. A third case,Classic_clock_padded(ersatztv#77), locks clock-boundary padding: aFillerMode.Pad+PadToNearestMinute=15PostRoll preset snaps content to:15, and the test both goldens the output and asserts every content item after the first starts on a quarter-hour. Its EPG counterpart isErsatzTV.Core.Tests/Channels/ChannelGuideProjectorClockPadTests.cs(guide programmes stop on the padded boundary). The build reads no wall clock — time enters only via the caller-suppliedstart— so a pinnedstartis fully deterministic. Snapshots the rawPlayoutItem.Start/Finish(UTC), not the*Offsetproperties (those call.ToLocalTime()and would make the golden machine-TZ dependent). The Block case is TZ-sensitive by construction (BlockPlayoutBuildermaps template times viaTimeZoneInfo.Local), so it is guarded withAssume.That(TimeZoneInfo.Local.BaseUtcOffset == Zero): it runs underTZ=UTC(CI) and reports inconclusive (a graceful skip, not a failure) under any other TZ. A real TZ seam for the block builder is ersatztv#380's scope.
All three locate their golden files via [CallerFilePath]. A missing golden is a hard fail, not a
skip. Regenerate via ETV_UPDATE_GOLDENS=1 dotnet test ... (M3U/XMLTV) or
ETV_UPDATE_PLAYOUT_GOLDENS=1 dotnet test ... (playout build).
Never set ETV_UPDATE_GOLDENS / ETV_UPDATE_PLAYOUT_GOLDENS in CI or from an agent. A golden
diff during normal test runs means the code changed the output — regenerating to make the diff go
away hides the change instead of surfacing it. Only a human who has confirmed the change is
intentional should regenerate.
Timezone independence
The suite is timezone-independent (ersatztv#24). When constructing test PlayoutItems, always
set a real Start (e.g. startState.CurrentTime.UtcDateTime) — never rely on the default
DateTime.MinValue, which underflows DateTimeOffset.MinValue once a non-UTC local offset is
applied (StartOffset calls ToLocalTime()). CI runs in UTC; local runs may not.
Running tests
Full .NET gate:
dotnet build ErsatzTV.sln
TZ=UTC dotnet test
CI adds --blame-hang-timeout 2m to catch hangs.
Fast subsets:
# single project
dotnet test ErsatzTV.Tests
# filtered
dotnet test ErsatzTV.Core.Tests --filter FullyQualifiedName~ChannelPlaylistGoldenTests
Web (web/):
npm test # vitest (excludes web/e2e — those need a live server)
npm run typecheck # tsc -b --pretty false
npm run lint # eslint .
npm run build # tsc -b && vite build
UI-E2E (needs a built solution + built SPA; boots and tears down its own instance):
scripts/e2e-ui.sh # from the repo root, NOT web/
Per-PR verification gate
Before opening a PR: build the solution, run ErsatzTV.Tests + ErsatzTV.Core.Tests (plus
ErsatzTV.Scanner.Tests, ErsatzTV.Architecture.Tests and ErsatzTV.FFmpeg.Tests if touched),
and run the web test/lint/typecheck/build steps above. All must be green. A golden-file diff or
an architecture-test failure is a hard stop — fix the code, don't regenerate/relax the test.
See also
docs/ci-cd.md— CI pipeline (test → migrations → build), versioning, dependency management.docs/contributing.md§1 — layering rules enforced byErsatzTV.Architecture.Tests.docs/contributing.md§8 — short pointer back to this doc.