11 Tests Guide

11 Tests Guide — Reliable End-to-End Verification (V90 Edition)

Theme: Confidence Through Testing

BlazorKeycloak’s testing strategy exists for one purpose:

You should never guess whether authentication works — you should be able to prove it.

This page explains how the following work together as a closed-loop verification system:

• Diagnostics Hub
• DevPrereqChecker
• ScriptTests
• Unit and integration tests
• Playwright End-to-End tests
• TestHarnessCli (the unified runner)

The intended outcome is always the same:

Symptom → Test → Diagnosis → Fix → Test Again → Confidence Restored

---

🧭 Why This Matters — Confidence Through Testing

BlazorKeycloak is engineered around three principles:

1. Every subsystem has a test
2. Every failure maps to a known symptom
3. Every fix is verifiable with evidence

The Diagnostics Hub (/admin/diagnostics) provides server-side truth about:

• OIDC authority
• Redirect and logout URIs
• PKCE and token exchange
• Auth cookies
• JWKS keys
• Client secret parity
• API reachability
• DevPrereqChecker results

Tests turn this truth into executable proof.

---

🔗 V90: Mapping Security Rules → Tests (Read This)

BlazorKeycloak’s security design is only trustworthy if it is observable and repeatable.

This is why the test suite enforces a small set of non-negotiable rules (defined in 03 Security Design) and proves them through specific test categories:

• Canonical authentication trigger is a deep link
  • Proof: Playwright specs navigate directly to protected routes (e.g., /weather-api-demo) and require an observable redirect to Keycloak.
• Keycloak must be detected by URL (not UI affordances)
  • Proof: Playwright waits for a Keycloak authority URL before attempting login; tests do not rely on headings or timing delays.
• Tokens never reach the browser
  • Proof: E2E and integration tests validate server-side token storage and cookie-based sessions (.BK.Auth is HttpOnly + Secure).
• API access must be audience-limited
  • Proof: ScriptTests and API integration tests validate aud = weather-api and reject tokens with incorrect audience.
• Logout is a visible security boundary
  • Proof: Playwright logout specs assert UI-observable signed-out state and do not infer logout from navigation alone.
• Failures must produce artifacts
  • Proof: E2E runs produce traces/screenshots/videos/logs so failures are explainable, not mysterious.

Rule of thumb

If a test does not explicitly observe the Keycloak redirect and the post-login return to the protected route, it is not proving authentication — it is guessing.

This is the V90 contract: observable security behavior beats inferred UI behavior.

---

🧩 The Five Pillars of Confidence

BlazorKeycloak’s test system is intentionally layered. Each layer proves something different.

1. Diagnostics Hub — Server-Side Truth

The Diagnostics Hub is the authoritative source of identity and environment state.

It answers questions such as:

• Is the OIDC authority correct?
• Are redirect and post-logout URIs configured?
• Is PKCE functioning?
• Are JWKS keys loaded?
• Are auth cookies present?
• Is the Web API reachable?
• Does Keycloak match the app’s configuration?
• Are DevPrereq checks passing?

If something is wrong in the identity pipeline, the hub shows it.

2. DevPrereqChecker — Environment Confidence

Before any identity flow runs, the DevPrereqChecker validates:

• Docker availability
• Keycloak reachability
• .NET SDK installation
• Visual Studio installation (Windows)
• mkcert presence and trust
• Port bindings for Web and Web API
• HTTPS certificate validity

Results appear in:

• The Home page
• The Diagnostics Hub

This prevents false failures caused by broken environments.

Home & DevPrereq Component Tests

These tests verify:

• Prerequisite UI indicators render correctly
• Failure messages are actionable
• Transitions to the Welcome screen behave correctly
• Home page and Diagnostics Hub stay in sync

They protect the developer experience itself.

3. ScriptTests — Identity & Configuration Assertions

ScriptTests validate identity plumbing before a browser is involved:

• Client secret parity
• Safe secret rotation
• PKCE and token exchange paths
• Role mappings
• Audience mapping (aud = weather-api)
• Redirect and logout URI parity
• Certificate and port checks
• Docker and Keycloak startup conditions

These tests catch misconfiguration early and cheaply.

4. Playwright E2E Tests — Real Browser Confidence

Playwright verifies the complete user-facing flow:

• Redirect to Keycloak
• Login (admin and non-admin)
• Deep linking (canonical auth trigger)
• Weather API rendering
• PKCE enforcement
• Back-channel logout
• CI-safe behavior across Windows and Linux

Artifacts produced:

• trace.zip
• videos
• screenshots
• browser logs

These artifacts eliminate guesswork when diagnosing failures.

V90 E2E Reliability Rules

Playwright tests are written to be CI-safe and deterministic:

• Prefer deep links to protected routes over clicking “Login”
• Wait for Keycloak by URL (authority + realm endpoints)
• Avoid asserting on headings alone
• Use unambiguous selectors (avoid label collisions)
• Use explicit timeouts suitable for cold starts

If a spec is “green” locally but flakes in CI, the spec is not done yet.

5. Unit and Integration Tests — Code-Level Confidence

Unit and integration tests verify:

• Authorization policies
• Token validation logic
• API behavior under valid and invalid tokens
• Failure paths and edge cases

They ensure the system fails correctly when inputs are wrong.

---

🚀 Running Tests — TestHarnessCli

All tests run through the unified runner:

dotnet run --project TestHarnessCli --

This executes all groups:

• web-unit
• web-int
• api-unit
• api-int
• script
• e2e
• trouble

This is the canonical way to prove system health.

Filtering Individual Tests

dotnet run --project TestHarnessCli -- --only=api-int --filter="FullyQualifiedName~AdminAuthTests"

---

🔧 Which Test Should You Run?

If you suspect environment issues:

dotnet run --project TestHarnessCli -- --only=web-unit,trouble

If you suspect OIDC or login flow issues:

dotnet run --project TestHarnessCli -- --only=e2e

If you suspect API authorization / audience issues:

dotnet run --project TestHarnessCli -- --only=api-int,script

If you are unsure what is broken:

1. Environment tests
2. ScriptTests
3. E2E tests
4. Diagnostics Hub
5. Fix one thing
6. Re-run

---

🧪 Recommended Troubleshooting Workflow

1. Run environment tests
2. Run ScriptTests
3. Run Playwright E2E
4. Inspect Diagnostics Hub
5. Inspect artifacts
6. Fix the root cause
7. Re-run tests
8. Commit with confidence

---

🏁 Summary

BlazorKeycloak delivers confidence through:

• Environment confidence (DevPrereqChecker)
• Identity confidence (ScriptTests)
• Code confidence (unit + integration)
• Browser confidence (Playwright)
• Server-side truth (Diagnostics Hub)

All verified through:

dotnet run --project TestHarnessCli --

Every subsystem has a test.
Every failure has a diagnosis.
Every fix is provable.