test(phase 2): add critical-path test coverage across Domain / Application / Infrastructure layers

.github/workflows/build.yml

@@ -49,10 +49,51 @@ jobs:
       - name: Format check
         run: dotnet format Sources/ProjectV.sln --severity warn --verify-no-changes
 
-      - name: Test (C# projects)
+      # Linux: four sequential named test stages with Coverlet
+      # collection on the C# stages (via coverlet.runsettings).
+      - name: Test (Unit)
         if: matrix.os == 'ubuntu-latest'
-        run: dotnet test Sources/ProjectV.sln --configuration Release --no-build
+        run: dotnet test Sources/ProjectV.sln --configuration Release --no-build --filter "Category=Unit" --collect:"XPlat Code Coverage" --settings Sources/Tests/coverlet.runsettings
 
-      - name: Test (F# ContentDirectories)
+      - name: Test (Integration)
+        if: matrix.os == 'ubuntu-latest'
+        run: dotnet test Sources/ProjectV.sln --configuration Release --no-build --filter "Category=Integration" --collect:"XPlat Code Coverage" --settings Sources/Tests/coverlet.runsettings
+
+      - name: Test (Contract)
+        if: matrix.os == 'ubuntu-latest'
+        run: dotnet test Sources/ProjectV.sln --configuration Release --no-build --filter "Category=Contract" --collect:"XPlat Code Coverage" --settings Sources/Tests/coverlet.runsettings
+
+      # F# stage: explicit fsproj invocation, no Category filter, no coverage collection
+      # (F# coverage non-essential and the project is tiny).
+      - name: Test (F#)
         if: matrix.os == 'ubuntu-latest'
         run: dotnet test Sources/Tests/ProjectV.ContentDirectories.Tests/ProjectV.ContentDirectories.Tests.fsproj --configuration Release --no-build -p:Platform=x64
+
+      # Coverage publication: merge per-stage Cobertura outputs into
+      # one HTML artifact + a Markdown step-summary panel.
+      - name: Merge coverage reports
+        if: matrix.os == 'ubuntu-latest'
+        uses: danielpalme/ReportGenerator-GitHub-Action@5
+        with:
+          reports: '**/TestResults/**/coverage.cobertura.xml'
+          targetdir: 'coverage-report'
+          reporttypes: 'HtmlInline;MarkdownSummaryGithub'
+          verbosity: 'Warning'
+
+      - name: Upload coverage report artifact
+        if: matrix.os == 'ubuntu-latest'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage-report/
+
+      - name: Write coverage summary to Step Summary
+        if: matrix.os == 'ubuntu-latest'
+        run: cat coverage-report/SummaryGithub.md >> $GITHUB_STEP_SUMMARY
+
+      # Windows: non-Docker tests. Single-quoted filter so PowerShell does not
+      # interpret `!=` and YAML keeps the string verbatim. Docker-dependent
+      # Testcontainers tests stay Linux-only via the [Trait("RequiresDocker","true")] tag.
+      - name: Test (Non-Docker)
+        if: matrix.os == 'windows-latest'
+        run: dotnet test Sources/ProjectV.sln --configuration Release --no-build --filter 'RequiresDocker!=true'

Docs/Testing/Scenarios/projectv-jwt-scenarios.md

@@ -0,0 +1,132 @@
+# ProjectV JWT Scenario Tests
+
+Companion to
+[`projectv-scenario-tests-overview.md`](./projectv-scenario-tests-overview.md)
+and [`../Coverage/test-coverage.md`](../Coverage/test-coverage.md).
+This document is the per-family scenario doc for the JWT-authentication
+slice of `ProjectV.CommunicationWebService`. Scenarios live under
+`Sources/Tests/ProjectV.CommunicationWebService.Tests/Scenarios/Jwt/` and
+inherit the conventions described in the overview doc.
+
+## Purpose
+
+Cover the JWT runtime path of `ProjectV.CommunicationWebService` end-to-end
+through `WebApplicationFactory<Startup>` — without mocking the authentication
+pipeline. The scenarios exercise:
+
+- The bearer-token validation path wired by
+  `AddJtwAuthentication(jwtConfig)` in
+  `Sources/WebServices/ProjectV.CommonWebApi/Service/Extensions/ServiceCollectionExtensions.cs`.
+- The login round-trip exposed by
+  `Sources/WebServices/ProjectV.CommunicationWebService/v1/Controllers/UsersController.cs`
+  (`POST /api/v1/Users/login`).
+- The protected entry point in
+  `Sources/WebServices/ProjectV.CommunicationWebService/v1/Controllers/RequestsController.cs`
+  (`POST /api/v1/Requests`).
+
+The JWT path uses the in-memory user store
+(`InMemoryUserInfoService`) — these tests do NOT require Testcontainers,
+so they carry only `[Trait("Category", "Integration")]` (no
+`[Trait("RequiresDocker", "true")]`) and run on both the Linux Integration
+stage and the Windows Non-Docker stage of CI.
+
+## Audience
+
+- **Test authors** adding new JWT scenarios — for example expired-token,
+  malformed-Authorization-header, or refresh-token-flow tests. They inherit
+  from `JwtAuthScenarioBaseTest` and follow the conventions below.
+- **Reviewers** scanning the family folder — the class XML doc on each
+  test file reads like a business-language sentence so a reviewer can scan
+  the directory and immediately see what behaviour is covered.
+
+## Architecture
+
+Each test class inherits the family base
+[`JwtAuthScenarioBaseTest`](../../../Sources/Tests/ProjectV.CommunicationWebService.Tests/Scenarios/Jwt/JwtAuthScenarioBaseTest.cs),
+which extends `ProjectV.Tests.Shared.ForTests.WebApiBaseTest<Startup>`. The
+base test wires up an in-process
+`TestWebApplicationFactory<ProjectV.CommunicationWebService.Startup>` that
+injects a deterministic JWT signing key
+(`TestJwtConfig.DefaultSecretKeyBase64`) into the host's
+`IConfiguration` BEFORE `Startup.ConfigureServices` runs — that timing is
+the only seam that lets the test side mint tokens with the same HMAC
+SHA-256 secret the production `AddJwtBearer` registration validates against.
+
+```mermaid
+flowchart LR
+    TF[Test Fixture<br/>JwtAuthScenarioBaseTest]
+    TF --> WAF[TestWebApplicationFactory&lt;Startup&gt;]
+    WAF --> CAC[ConfigureAppConfiguration<br/>inject JwtOptions:SecretKey,<br/>Issuer, Audience]
+    WAF --> CTS[ConfigureTestServices<br/>per-scenario DI overrides]
+    CAC --> HOST[(Hosted CommunicationWebService<br/>real Startup + middleware)]
+    CTS --> HOST
+    HOST -->|HTTP loopback| HC[HttpClient<br/>anonymous OR Bearer-decorated]
+    TF -->|CreateAuthenticatedClient| HC
+    TF -->|TestJwtHelper| TOK[Signed test JWT<br/>HMAC SHA-256]
+    TOK --> HC
+    HC --> CTRL[RequestsController / UsersController]
+```
+
+## Scenario Catalog
+
+| Scenario | Test File | Endpoint | Expected Outcome |
+|----------|-----------|----------|------------------|
+| **JWT-1** — Anonymous request rejected | `JwtAnonymousRequestTests.cs` | `POST /api/v1/Requests` (no `Authorization`) | `401 Unauthorized` |
+| **JWT-2** — Authenticated request passes auth | `JwtAuthenticatedRequestTests.cs` | `POST /api/v1/Requests` (valid bearer token) | Status code is NOT 401 / 403 (auth pipeline accepts the token) |
+| **JWT-3** — Login issues token | `JwtLoginIssuesTokenTests.cs` | `POST /api/v1/Users/login` (valid in-memory creds) | `200 OK` + `TokenResponse` with non-empty `AccessToken.Token` |
+
+### Scenario JWT-1: Anonymous request rejected
+
+When no `Authorization` header is present on a request to a
+`[Authorize]`-decorated controller action, the production JWT bearer
+middleware must short-circuit the pipeline with HTTP `401 Unauthorized`.
+Verifies that the auth wiring is present at all — a regression that
+silently disabled authentication (e.g. removing `app.UseAuthentication()`
+or `[Authorize]`) would let the request through with a 400 instead.
+
+### Scenario JWT-2: Authenticated request passes the auth pipeline
+
+A token signed with the same secret / issuer / audience the host was
+configured with must pass `TokenValidationParameters` so the request
+reaches the controller action. The scenario asserts that the response is
+neither 401 nor 403; it does NOT assert on the response body shape
+because the request body is intentionally empty (the controller may
+short-circuit with 400 for that reason — what matters is that the auth
+middleware did NOT short-circuit).
+
+### Scenario JWT-3: Login round-trip issues a token pair
+
+The scenario seeds a single user into the in-memory user store via the
+production `IPasswordManager` so the stored salt + hash format match
+exactly what `UserService.LoginAsync` expects. It then POSTs credentials
+at `/api/v1/Users/login` and asserts the response is `200 OK` with a
+non-empty `AccessToken.Token` field. The `ShouldCreateSystemUser` flag is
+held OFF to avoid the fire-and-forget seed race in
+`UserService`'s constructor — the test owns the entire in-memory store.
+
+## Conventions
+
+JWT scenario tests follow the conventions described in
+[`projectv-scenario-tests-overview.md`](./projectv-scenario-tests-overview.md#conventions)
+without exception. Two family-specific points:
+
+- **No `[Trait("RequiresDocker", "true")]`** — JWT scenarios use only the
+  in-memory user store. They run on the Windows Non-Docker stage of CI in
+  addition to the Linux Integration stage.
+- **No `[Collection]` attribute** — JWT scenarios do NOT share a fixture
+  with the Testcontainers Postgres path used by the DAL integration suite.
+  Each scenario class spins up its own in-process host via the factory in
+  `InitializeAsync` and tears it down in `DisposeAsync`.
+
+## Cross-references
+
+- [`Docs/Testing/Coverage/test-coverage.md`](../Coverage/test-coverage.md) —
+  Infrastructure-Layer rows for the three JWT scenarios.
+- [`Docs/Testing/Scenarios/projectv-scenario-tests-overview.md`](./projectv-scenario-tests-overview.md) —
+  cross-family conventions, architecture diagram, scenario-test pattern.
+- [`Sources/Tests/ProjectV.Tests.Shared/Helpers/WebApi/TestWebApplicationFactory.cs`](../../../Sources/Tests/ProjectV.Tests.Shared/Helpers/WebApi/TestWebApplicationFactory.cs) —
+  generic test host wrapper.
+- [`Sources/Tests/ProjectV.Tests.Shared/Helpers/WebApi/TestJwtHelper.cs`](../../../Sources/Tests/ProjectV.Tests.Shared/Helpers/WebApi/TestJwtHelper.cs) —
+  bearer-token issuance helper.
+- [`Sources/Tests/ProjectV.Tests.Shared/ForTests/WebApiBaseTest.cs`](../../../Sources/Tests/ProjectV.Tests.Shared/ForTests/WebApiBaseTest.cs) —
+  `IAsyncLifetime` base + `CreateAuthenticatedClient`.

Docs/Testing/Scenarios/projectv-scenario-tests-overview.md

@@ -0,0 +1,181 @@
+# ProjectV Scenario Tests — Overview
+
+Companion to
+[`Docs/Testing/Coverage/test-coverage.md`](../Coverage/test-coverage.md).
+This document is the architecture-diagram baseline for the
+`WebApplicationFactory`-based scenario suites covering JWT authentication,
+Telegram webhook, and Telegram polling. Per-family scenario docs
+(e.g. `projectv-jwt-scenarios.md`, `projectv-telegram-scenarios.md`,
+`projectv-tmdb-pipeline-scenarios.md`, …) are added alongside their
+respective scenario suites as they land.
+
+## Purpose
+
+Scenario tests in ProjectV are integration tests written one test file per
+business scenario:
+
+- One sealed test class per scenario; file name is `<ScenarioShortName>Tests.cs`.
+- Class XML doc summarises the scenario in **business** terms (e.g.
+  "Scenario JWT-1: Anonymous request to `/api/v1/Requests` returns 401"),
+  not in test-framework terms.
+- Class inherits from a per-family base class — e.g. `JwtAuthScenarioBaseTest`,
+  `TelegramWebhookScenarioBaseTest`, `TmdbPipelineScenarioBaseTest` — which
+  bundles the `WebApplicationFactory` wiring + scenario-family-wide config knobs.
+- Test method bodies use **explicit `// Arrange.` / `// Act.` / `// Assert.`
+  comment markers**. This convention was introduced during the test-coverage
+  work tracked in PR #342; new scenario tests follow it without exception.
+- Assertions cover production behavior AND stub-side call counts where
+  relevant — for example, `wireMock.LogEntries.Should().HaveCount(1)` to
+  verify that the SDK called the external API exactly once after a Polly
+  retry policy completed.
+
+The point is that the file name, class name, and XML doc together read like
+a checklist of business behaviour, so a reviewer can scan the
+`Scenarios/<ScenarioFamily>/` directory and see exactly what is being verified
+without opening any test method.
+
+## Audience
+
+- **Scenario test authors** — engineers implementing `WebApplicationFactory`-based
+  integration tests for the JWT authentication
+  (`Sources/Tests/ProjectV.CommunicationWebService.Tests/Scenarios/Jwt/`),
+  Telegram webhook
+  (`Sources/Tests/ProjectV.TelegramBotWebService.Tests/Scenarios/Webhook/`),
+  or Telegram polling
+  (`Sources/Tests/ProjectV.TelegramBotWebService.Tests/Scenarios/Polling/`)
+  suites. They use this overview
+  to know which base class to inherit from, which Helpers wires up which
+  external surface, and what shape an Arrange / Act / Assert block should
+  take inside the scenario file.
+- **Future contributors** adding new scenario families — they create a new
+  per-family base class under
+  `Sources/Tests/ProjectV.<WebService>.Tests/Scenarios/<ScenarioFamily>/`,
+  add a per-family doc next to this overview, and follow the conventions
+  named here.
+- **Reviewers** of phase-end PRs — they use the diagram below to confirm
+  that a new scenario test wires up the real production DI graph (no mocks
+  on the request path) and that any external dependency lives behind a
+  WireMock.Net stub.
+
+Scenario tests live under
+`Sources/Tests/ProjectV.<WebService>.Tests/Scenarios/<ScenarioFamily>/` —
+one directory per scenario family, one file per scenario inside it.
+
+## Architecture
+
+The diagram below shows how a scenario test process drives the system under
+test, including the `WebApplicationFactory` integration branch used by the
+JWT and Telegram scenario suites.
+
+Key invariants in the diagram:
+
+- The **Real Application** node represents the production DI graph — the
+  same `Startup` class production runs, the same `ICrawler` / `IAppraiser`
+  / `IJobInfoService` registrations, the same EF Core `ProjectVDbContext`.
+- The **only test doubles on the request path** are `WireMockServer`
+  instances for external HTTP APIs (TMDb / OMDb / Steam) and a substituted
+  `ITelegramBotClient` for the Telegram polling branch. There are no
+  in-process mocks for the Application or Domain layers in scenario tests
+  (that is the Unit-test layer's job).
+- The **Testcontainers Postgres** node is the single per-test-run
+  container started by `ICollectionFixture<DbCollectionFixture>`; the same
+  container is reused across scenario test classes that share the
+  `DbCollection` `CollectionDefinition`.
+
+```mermaid
+flowchart TD
+    TP[Test Process<br/>xUnit + AwesomeAssertions + NSubstitute]
+
+    TP --> UT[Unit Tests<br/>Category=Unit]
+    UT --> NS[NSubstitute substitutes]
+    NS --> SUT[Single SUT class]
+    SUT --> AA1[AwesomeAssertions on return value]
+
+    TP --> IT[Integration Tests<br/>Category=Integration]
+    IT --> WAF[WebApplicationFactory&lt;TStartup&gt;]
+    WAF --> CTS[ConfigureTestServices<br/>swap connection string &<br/>stub HTTP clients]
+    CTS --> RA[Real Application DI graph<br/>Startup + EF Core + Polly]
+    RA --> TC[(Testcontainers<br/>PostgreSqlContainer)]
+    RA -.->|external HTTP| WMI[WireMockServer<br/>recorded JSON fixtures]
+
+    TP --> CT[Contract Tests<br/>Category=Contract]
+    CT --> WMS[WireMockServer in-process]
+    WMS -.->|HTTP loopback| HCF[IHttpClientFactory]
+    HCF --> SDK[Real SDK<br/>TMDbLib / OmdbApiNet / SteamWebApiLib]
+    SDK --> ADP[Adapter mapper]
+    ADP --> AA2[AwesomeAssertions on<br/>BasicInfo / MovieInfo / GameInfo]
+
+    TP --> FT[F# Tests<br/>separate fsproj invocation,<br/>no Category trait]
+    FT --> UQ[Unquote quoted-expression<br/>assertions]
+    UQ --> CF[ContentFinder / PolicyModels]
+
+    classDef testDouble stroke-dasharray: 5 5;
+    class WMI,WMS testDouble;
+```
+
+The dashed edges (`-.->`) and dashed-border nodes mark the only places where
+a scenario test substitutes a real dependency: HTTP traffic to TMDb / OMDb /
+Steam is routed through a local `WireMockServer` instance that serves recorded
+JSON fixtures from `Sources/Tests/Fixtures/{Tmdb,Omdb,Steam}/`. Everything
+else on the request path is production code running against a real
+Testcontainers Postgres.
+
+## Scenario Family Documents
+
+Per-family docs are added by the plan that lands the family's scenario suite,
+not up-front:
+
+> Only scenario-family docs that correspond to scenario suites actually
+> committed to the repository are created — the overview is mandatory,
+> family docs are added as their scenario suites land.
+
+Expected per-family doc filenames:
+
+- `projectv-jwt-scenarios.md` — added alongside the JWT scenario suite
+  (`Sources/Tests/ProjectV.CommunicationWebService.Tests/Scenarios/Jwt/`).
+- `projectv-telegram-scenarios.md` — added alongside the Telegram webhook +
+  polling scenario suites
+  (`Sources/Tests/ProjectV.TelegramBotWebService.Tests/Scenarios/Webhook/` and `/Polling/`).
+- `projectv-tmdb-pipeline-scenarios.md` — added if/when a TMDb-end-to-end
+  scenario suite lands; current TMDb coverage is at the contract-test
+  layer (`Sources/Tests/ProjectV.TmdbService.Tests/TmdbContractTests.cs`).
+
+Family docs follow the same shape as this overview — Purpose, Audience,
+Architecture (with a scenario-family-specific mermaid view), Conventions,
+and a table that enumerates each scenario file with a one-line description.
+
+## Conventions
+
+- **Class XML doc** summarises the scenario in business terms. Bad:
+  `"Tests that the controller returns 401 when no Authorization header is
+  present."` Good: `"Scenario JWT-1: Anonymous request to /api/v1/Requests
+  returns 401."`
+- **Class shape** — `public sealed class <ScenarioShortName>Tests` with an
+  explicit empty constructor (matches the rest of the ProjectV test stack).
+- **Base class** — inherits from a per-family base class (e.g.
+  `JwtAuthScenarioBaseTest`) that holds the `WebApplicationFactory`
+  instance + scenario-family-wide config knobs. The base class is what
+  swaps test-side HttpClients onto WireMock and tells the
+  `ProjectVDbContext` to point at the Testcontainers Postgres.
+- **AAA markers** — every test method body has explicit `// Arrange.`,
+  `// Act.`, and `// Assert.` comment lines. No exceptions; even one-line
+  acts include the marker.
+- **Assertions** — assert on production behavior AND on stub-side call
+  counts where the stub-side counts are part of the scenario semantics.
+  Example: a "Polly retries transient 502 exactly once" scenario asserts
+  on the final 200 response AND on `wireMockServer.LogEntries.Should()
+  .HaveCount(2, "Polly should have retried once after the transient
+  failure")`.
+- **Category trait** — every scenario test class is
+  `[Trait("Category","Integration")]`. Scenarios that hit Testcontainers
+  Postgres also add `[Trait("RequiresDocker","true")]`. CI filters on these
+  traits to separate Docker-dependent tests from non-Docker integration tests.
+- **xUnit collection** — scenario tests that share the Testcontainers
+  Postgres declare `[Collection(DbCollection.Name)]` so they run serially
+  inside the single container session.
+
+## Cross-references
+
+- [`Docs/Testing/Coverage/test-coverage.md`](../Coverage/test-coverage.md) —
+  critical-path coverage inventory; the scenarios documented here cover the
+  `WebApplicationFactory` rows in the Infrastructure Layer table.