Update OpenWiki documentation and claims
Some checks failed
Build / build (pull_request) Has been cancelled
Some checks failed
Build / build (pull_request) Has been cancelled
Reference AGENTS.md in CLAUDE.md and record verification claims for the architecture overview and operations runbook. Signed-off-by: Tim Krampitz <Tim.Krampitz@live.com>
This commit is contained in:
Tim Krampitz
@@ -1,14 +1,17 @@
|
||||
---
|
||||
type: Runbook
|
||||
title: Operations, Environment Setup & Testing Guidance
|
||||
description: Operational guide for launching SlipItIn with .NET Aspire, running EF Core PostgreSQL migrations, configuring secrets, and executing client/server verification tests.
|
||||
tags: [operations, runbook, spire, postgresql, migrations, testing, mvvm, offline-queue]
|
||||
description: Operational guide for local development setup, .NET Aspire startup, EF Core PostgreSQL migrations, JWT configuration, and testing verification scenarios.
|
||||
tags: [operations, runbook, aspire, postgresql, migrations, testing, xunit, signalr]
|
||||
openwiki:
|
||||
roles: [operations, testing]
|
||||
change_kinds: [lifecycle, public-api]
|
||||
source_paths: [SlipItIn.AppHost/AppHost.cs, SlipItIn.Server/Program.cs, SlipItIn/MauiProgram.cs]
|
||||
symbols: [AppHost, Program, MauiProgram]
|
||||
validation_commands: ["dotnet build SlipItIn.slnx"]
|
||||
source_paths: [SlipItIn.AppHost/AppHost.cs, SlipItIn.Server/Program.cs, SlipItIn/MauiProgram.cs, SlipItIn.Server.Tests/TestDbHelper.cs]
|
||||
symbols: [AppHost, Program, MauiProgram, TestDbHelper]
|
||||
validation_commands: ["dotnet build SlipItIn.slnx", "dotnet test SlipItIn.Server.Tests"]
|
||||
verified:
|
||||
- by: openwiki/0.5.0
|
||||
at: 2026-09-07T15:04:46.288Z
|
||||
---
|
||||
|
||||
# Operations, Environment Setup & Testing Guidance
|
||||
@@ -38,23 +41,24 @@ dotnet run --project SlipItIn.AppHost/SlipItIn.AppHost.csproj
|
||||
1. Aspire launches a PostgreSQL container (`pgsql`/`postgresdb`).
|
||||
2. Aspire builds and starts `SlipItIn.Server`.
|
||||
3. `Program.cs` automatically executes EF Core migrations (`db.Database.Migrate()`), creating database tables if they do not exist.
|
||||
4. Aspire Dashboard opens in your web browser, displaying live metrics, OpenTelemetry traces, and structured logs for all services.
|
||||
4. `DbSeeder.SeedAsync(db)` populates initial users and phrases when the database is empty.
|
||||
5. Aspire Dashboard opens in your web browser, displaying live metrics, OpenTelemetry traces, and structured logs for all services.
|
||||
|
||||
---
|
||||
|
||||
## 2. Configuration & Secrets Management
|
||||
|
||||
Configuration settings are loaded from `appsettings.json` and environment variables.
|
||||
Configuration settings are loaded from `appsettings.json`, `appsettings.Development.json`, and environment variables.
|
||||
|
||||
### Key Configuration Keys (`SlipItIn.Server`)
|
||||
|
||||
| Key | Default Value | Description |
|
||||
|---|---|---|
|
||||
| `Jwt:Key` | `YourSuperSecretKeyThatIsAtLeast32CharactersLong!` | Secret signing key for JWT tokens (Must be >= 256 bits). |
|
||||
| `Jwt:Key` | _(none in production; dev fallback: `DevOnlyKey-NotForProduction-ChangeMe-0123456789abcdef`)_ | Secret signing key for JWT tokens (Must be >= 32 characters / >= 256 bits). In non-development environments, a missing or short key causes a startup exception. |
|
||||
| `Jwt:Issuer` | `SlipItInServer` | Token issuer claim. |
|
||||
| `Jwt:Audience` | `SlipItInClient` | Token audience claim. |
|
||||
| `Jwt:ExpirationMinutes` | `1440` (24 hours) | JWT token lifespan. |
|
||||
| `ConnectionStrings:postgresdb` | Configured via Aspire | PostgreSQL connection string. |
|
||||
| `ConnectionStrings:postgresdb` | Configured via Aspire | PostgreSQL connection string injected by the Aspire orchestrator. |
|
||||
|
||||
### Production Configuration Security
|
||||
In production deployment, override `Jwt:Key` using environment variables or user secrets (`dotnet user-secrets`):
|
||||
@@ -85,7 +89,42 @@ dotnet ef database update --project SlipItIn.Server --startup-project SlipItIn.S
|
||||
|
||||
---
|
||||
|
||||
## 4. Testing Guidance & Verification Scenarios
|
||||
## 4. Test Project Structure
|
||||
|
||||
The `SlipItIn.Server.Tests` project contains all server-side automated tests. It targets `net10.0` and uses **xUnit** as the test framework, **Moq** for mocking dependencies, and **EF Core InMemory** (`Microsoft.EntityFrameworkCore.InMemory`) for isolated database contexts.
|
||||
|
||||
### Test Infrastructure
|
||||
|
||||
**`TestDbHelper.cs`** — Static helper class that creates isolated test databases and seeds test data:
|
||||
- `CreateFactory()` — Returns an `IDbContextFactory<SlipItInDbContext>` backed by an EF Core InMemory database with a unique name per test, ensuring complete test isolation.
|
||||
- `SeedUser(db, username, email, isActive)` — Inserts a minimal `User` entity and returns it.
|
||||
- `SeedPhrases(db, count)` — Inserts a set of `Phrase` entities (with an auto-created creator user) for card-dealing tests.
|
||||
- `SeedGame(db, host, status)` — Creates a `Game` with a host `Player` attached, returning both for test assertions.
|
||||
|
||||
### Test Files
|
||||
|
||||
| File | Class Under Test | What It Covers |
|
||||
|---|---|---|
|
||||
| `GameServiceTests.cs` | `GameService` | Business logic: game creation, joining, starting, player ready, card dealing, slip submission, challenge creation/resolution, game state queries with round time computation. |
|
||||
| `GameHubTests.cs` | `GameHub` | SignalR hub behavior: lobby creation/join, player ready, game start, slip submission, challenge submission/resolution, authorization enforcement. Uses Moq to mock `IGameService`, `IHubCallerClients`, `IGroupManager`, and `ISingleClientProxy`. InMemory DB is used only for the hub's own player-access validation. |
|
||||
| `AuthControllerTests.cs` | `AuthController` | Registration (token generation, input validation, case-insensitive duplicate detection), login (credential verification, missing-field handling), and the `/auth/me` claims endpoint. |
|
||||
| `DbSeederTests.cs` | `DbSeeder` | Seed idempotency: verifies `SeedAsync` creates users and phrases when the database is empty, but does nothing when data already exists, and is safe to call repeatedly. |
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
dotnet test SlipItIn.Server.Tests/SlipItIn.Server.Tests.csproj
|
||||
```
|
||||
|
||||
For CI-matching behavior (Release configuration):
|
||||
|
||||
```bash
|
||||
dotnet test SlipItIn.Server.Tests/SlipItIn.Server.Tests.csproj --configuration Release
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Testing Guidance & Verification Scenarios
|
||||
|
||||
When developing or extending SlipItIn features, verify the core architecture through these targeted test scenarios:
|
||||
|
||||
@@ -118,13 +157,18 @@ When developing or extending SlipItIn features, verify the core architecture thr
|
||||
|
||||
---
|
||||
|
||||
## 5. Guidance for Future Agents & Developers
|
||||
## 6. Guidance for Future Agents & Developers
|
||||
|
||||
- **When to Consult**: Refer to this runbook for local environment setup, Aspire startup commands, EF Core migration commands, and test verification procedures.
|
||||
- **Invariants**:
|
||||
- Always run migrations using `SlipItIn.Server` as both project and startup-project.
|
||||
- Test offline queue flushing before submitting client-side real-time changes.
|
||||
- **CI Build Commands** (from `.github/workflows/build.yml`):
|
||||
- Server stack: `dotnet build SlipItIn.Shared/SlipItIn.Shared.csproj --no-restore --configuration Release` (and similarly for `ServiceDefaults`, `Server`, `Server.Tests`, `AppHost`).
|
||||
- MAUI client: `dotnet build SlipItIn/SlipItIn.csproj --no-restore --configuration Debug`.
|
||||
- Server tests: `dotnet test SlipItIn.Server.Tests/SlipItIn.Server.Tests.csproj --no-restore --configuration Release`.
|
||||
- **Minimal Validation Command**:
|
||||
```bash
|
||||
dotnet build SlipItIn.slnx
|
||||
dotnet test SlipItIn.Server.Tests
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user