diff --git a/.github/scripts/installer-test.ps1 b/.github/scripts/installer-test.ps1 new file mode 100644 index 00000000..98cf8f9b --- /dev/null +++ b/.github/scripts/installer-test.ps1 @@ -0,0 +1,117 @@ +# Installs, runs, upgrades and removes the packed installers on a clean Windows runner (BRIEF §18): silent mode, +# folder with a space, Add/Remove Programs entry, shortcuts, the .titano file type, upgrade in place (files of the +# previous version removed), user data kept, the uninstaller removing itself, and the documented exit codes. +param( + [Parameter(Mandatory)] [string] $Setup1, + [Parameter(Mandatory)] [string] $Setup2, + [Parameter(Mandatory)] [string] $UploaderSetup, + [Parameter(Mandatory)] [string] $Version1, + [Parameter(Mandatory)] [string] $Version2, + [Parameter(Mandatory)] [string] $Screenshots +) + +$ErrorActionPreference = 'Stop' +Set-StrictMode -Version Latest + +# Relative paths are taken from the PowerShell location: .NET resolves them from the process directory, which a +# Set-Location does not move, and the programs get the screenshot folder as an argument. +$Setup1 = (Resolve-Path -LiteralPath $Setup1).Path +$Setup2 = (Resolve-Path -LiteralPath $Setup2).Path +$UploaderSetup = (Resolve-Path -LiteralPath $UploaderSetup).Path +$Screenshots = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($Screenshots) + +function Invoke-Program([string] $Exe, [string[]] $Arguments) { + $start = [System.Diagnostics.ProcessStartInfo]::new($Exe) + foreach ($argument in $Arguments) { $start.ArgumentList.Add($argument) } + $start.UseShellExecute = $false + $process = [System.Diagnostics.Process]::Start($start) + if (-not $process.WaitForExit(600000)) { + $process.Kill($true) + throw "$Exe $Arguments did not finish in 10 minutes" + } + Write-Host "$(Split-Path $Exe -Leaf) $Arguments -> exit $($process.ExitCode)" + return $process.ExitCode +} + +function Assert-True([bool] $Condition, [string] $Message) { + if (-not $Condition) { throw "FAILED: $Message" } + Write-Host "ok: $Message" +} + +function Wait-Removed([string] $Path) { + for ($i = 0; $i -lt 120 -and (Test-Path -LiteralPath $Path); $i++) { Start-Sleep -Milliseconds 500 } + return -not (Test-Path -LiteralPath $Path) +} + +function Get-DefaultValue([string] $Key) { + if (-not (Test-Path -LiteralPath $Key)) { return $null } + return (Get-Item -LiteralPath $Key).GetValue('') +} + +$dir = Join-Path $env:RUNNER_TEMP 'Titano Test' +$entryKey = 'HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\Titano' +$programs = [Environment]::GetFolderPath('Programs') +$desktop = [Environment]::GetFolderPath('DesktopDirectory') +$links = @( + (Join-Path $programs 'Titano.lnk'), (Join-Path $programs 'Titano Uploader.lnk'), + (Join-Path $desktop 'Titano.lnk'), (Join-Path $desktop 'Titano Uploader.lnk')) +$userData = Join-Path $env:LOCALAPPDATA 'Titano' +$userFile = Join-Path $userData 'kept-by-setup.txt' +New-Item -ItemType Directory -Force -Path $userData | Out-Null +Set-Content -LiteralPath $userFile -Value 'user data' + +Write-Host '--- Arguments' +Assert-True ((Invoke-Program $Setup1 @('/BOGUS')) -eq 2) 'an unknown switch exits with 2 (invalid arguments)' +Assert-True ((Invoke-Program $Setup1 @('/S', '/uninstall')) -eq 6) 'removing a product that is not installed exits with 6' + +Write-Host "--- Install $Version1 into '$dir'" +Assert-True ((Invoke-Program $Setup1 @('/S', "/DIR=$dir")) -eq 0) 'silent install exits with 0' +foreach ($file in 'Titano.exe', 'Titano.Uploader.exe', 'Uninstall Titano.exe', 'install-log.json', 'legacy.txt') { + Assert-True (Test-Path -LiteralPath (Join-Path $dir $file)) "$file installed" +} +$entry = Get-ItemProperty -LiteralPath $entryKey +Assert-True ($entry.DisplayVersion -eq $Version1) "Add/Remove Programs lists version $Version1" +Assert-True ($entry.InstallLocation -eq $dir) 'Add/Remove Programs lists the chosen folder' +Assert-True ($entry.QuietUninstallString -eq "`"$(Join-Path $dir 'Uninstall Titano.exe')`" /uninstall /S") 'quiet uninstall command points at the uninstaller' +foreach ($link in $links) { Assert-True (Test-Path -LiteralPath $link) "shortcut '$link' created" } +Assert-True ((Get-DefaultValue 'HKCU:\Software\Classes\.titano') -eq 'Titano.Project') '.titano opens with Titano' +Assert-True ((Get-DefaultValue 'HKCU:\Software\Classes\Titano.Project\shell\open\command') -eq "`"$(Join-Path $dir 'Titano.exe')`" `"%1`"") 'Titano.Project opens the installed Titano.exe' + +Write-Host '--- Run the installed programs' +foreach ($program in 'Titano.exe', 'Titano.Uploader.exe') { + $before = @(Get-ChildItem -Path $Screenshots -Filter *.png -ErrorAction SilentlyContinue).Count + $code = Invoke-Program (Join-Path $dir $program) @('--capture', $Screenshots) + $count = @(Get-ChildItem -Path $Screenshots -Filter *.png -ErrorAction SilentlyContinue).Count - $before + Assert-True ($code -eq 0 -and $count -gt 0) "installed $program starts and draws its screens ($count screenshot(s))" +} + +Write-Host "--- Upgrade in place to $Version2" +Assert-True ((Invoke-Program $Setup2 @('/S')) -eq 0) 'silent upgrade exits with 0' +Assert-True ((Get-ItemProperty -LiteralPath $entryKey).DisplayVersion -eq $Version2) "Add/Remove Programs lists version $Version2" +Assert-True ((Get-Content -Raw -LiteralPath (Join-Path $dir 'install-log.json') | ConvertFrom-Json).version -eq $Version2) "install log records version $Version2" +Assert-True (Test-Path -LiteralPath (Join-Path $dir 'Titano.exe')) 'Titano.exe still installed' +Assert-True (-not (Test-Path -LiteralPath (Join-Path $dir 'legacy.txt'))) 'a file only the previous version had is removed' +foreach ($link in $links) { Assert-True (Test-Path -LiteralPath $link) "shortcut '$link' kept" } +Assert-True (Test-Path -LiteralPath $userFile) 'user data kept by the upgrade' + +Write-Host '--- Uninstall with the installed uninstaller' +Assert-True ((Invoke-Program (Join-Path $dir 'Uninstall Titano.exe') @('/uninstall', '/S')) -eq 0) 'silent uninstall exits with 0' +Assert-True (Wait-Removed $dir) 'install folder removed, uninstaller included' +Assert-True (-not (Test-Path -LiteralPath $entryKey)) 'Add/Remove Programs entry removed' +foreach ($link in $links) { Assert-True (-not (Test-Path -LiteralPath $link)) "shortcut '$link' removed" } +Assert-True (-not (Test-Path -LiteralPath 'HKCU:\Software\Classes\Titano.Project')) 'Titano.Project file type removed' +Assert-True ($null -eq (Get-DefaultValue 'HKCU:\Software\Classes\.titano')) '.titano no longer opens with Titano' +Assert-True (Test-Path -LiteralPath $userFile) 'user data kept by the uninstall' + +Write-Host '--- Uploader installer: default folder, removal through the installer itself' +$uploaderDir = Join-Path $env:LOCALAPPDATA 'Programs\Titano Uploader' +$uploaderKey = 'HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\TitanoUploader' +Assert-True ((Invoke-Program $UploaderSetup @('/S')) -eq 0) 'silent Uploader install exits with 0' +Assert-True (Test-Path -LiteralPath (Join-Path $uploaderDir 'Titano.Uploader.exe')) 'Uploader installed in %LOCALAPPDATA%\Programs\Titano Uploader' +Assert-True (Test-Path -LiteralPath $uploaderKey) 'Uploader listed in Add/Remove Programs' +Assert-True ((Invoke-Program $UploaderSetup @('/uninstall', '/S')) -eq 0) 'silent Uploader removal exits with 0' +Assert-True (Wait-Removed $uploaderDir) 'Uploader folder removed' +Assert-True (-not (Test-Path -LiteralPath $uploaderKey)) 'Uploader entry removed' +Assert-True (Test-Path -LiteralPath $userFile) 'user data kept' + +Write-Host 'Installer test passed.' diff --git a/.github/scripts/postgres-ci-setup.sh b/.github/scripts/postgres-ci-setup.sh new file mode 100644 index 00000000..78239047 --- /dev/null +++ b/.github/scripts/postgres-ci-setup.sh @@ -0,0 +1,56 @@ +#!/usr/bin/env bash +# Prepares a PostgreSQL service container for the wire-protocol tests that need more than the image's defaults +# (BRIEF §6.3): one role per authentication method (MD5, cleartext, trust) with its pg_hba line ahead of the image's +# catch-all SCRAM line, and TLS with a self-signed certificate valid for localhost and 127.0.0.1. +# Usage: bash .github/scripts/postgres-ci-setup.sh CONTAINER SUPERUSER DATABASE CERTIFICATE_FOLDER +# The certificate (server.crt) stays in CERTIFICATE_FOLDER: the verify-full test trusts it as its root. +set -euo pipefail +container=$1 +superuser=$2 +database=$3 +certificates=$4 + +sql() { docker exec -i "$container" psql -v ON_ERROR_STOP=1 -U "$superuser" -d "$database" -Atq "$@"; } + +mkdir -p "$certificates" +openssl req -x509 -newkey rsa:2048 -nodes -days 2 -subj "/CN=localhost" \ + -addext "subjectAltName=DNS:localhost,IP:127.0.0.1" \ + -keyout "$certificates/server.key" -out "$certificates/server.crt" 2>/dev/null + +data=$(sql -c "SHOW data_directory") +hba=$(sql -c "SHOW hba_file") +docker cp "$certificates/server.crt" "$container:$data/server.crt" +docker cp "$certificates/server.key" "$container:$data/server.key" +# The server refuses a key that others can read. +docker exec "$container" sh -c "chown postgres:postgres '$data/server.crt' '$data/server.key' && chmod 600 '$data/server.key'" + +# The first matching line wins, so these go above the image's 'host all all all scram-sha-256'. +docker exec "$container" sh -c "{ printf '%s\n' 'host all titano_md5 all md5' 'host all titano_clear all password' \ + 'host all titano_trust all trust'; cat '$hba'; } > /tmp/pg_hba.conf && cat /tmp/pg_hba.conf > '$hba'" + +sql > /dev/null <<'SQL' +SET password_encryption = 'md5'; +CREATE ROLE titano_md5 LOGIN PASSWORD 'md5-ci'; +RESET password_encryption; +CREATE ROLE titano_clear LOGIN PASSWORD 'clear-ci'; +CREATE ROLE titano_trust LOGIN; +ALTER SYSTEM SET ssl = on; +SELECT pg_reload_conf(); +SQL + +# A reload that fails keeps the old settings silently: report the rejected lines, then wait for TLS to be on. +errors=$(sql -c "SELECT line_number || ': ' || error FROM pg_hba_file_rules WHERE error IS NOT NULL + UNION ALL SELECT name || ': ' || error FROM pg_file_settings WHERE error IS NOT NULL") +if [ -n "$errors" ]; then + echo "::error title=PostgreSQL setup::$errors" + exit 1 +fi +for _ in $(seq 1 20); do + if [ "$(sql -c "SHOW ssl")" = "on" ]; then + echo "PostgreSQL in $container: MD5, cleartext and trust roles, TLS on" + exit 0 + fi + sleep 0.5 +done +echo "::error title=PostgreSQL setup::TLS did not turn on after the reload" +exit 1 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 89163587..4ff097e7 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -99,6 +99,7 @@ jobs: timeout-minutes: 10 run: | set +e + failed=0 for exe in src/Titano.App/bin/Release/net10.0-windows/Titano.exe src/Titano.Uploader/bin/Release/net10.0-windows/Titano.Uploader.exe \ src/Titano.Setup/bin/Release/net10.0-windows/Titano.Setup.exe; do name=$(basename "$exe" .exe) @@ -109,8 +110,29 @@ jobs: cat "out/capture-$name.log" count=$(( $(ls out/screenshots/*.png 2>/dev/null | wc -l) - before )) echo "$name capture exit code $code, $count screenshot(s)" - if [ "$count" -eq 0 ]; then echo "::warning title=Screenshots::$name --capture produced no images (exit $code)"; fi + # A capture that crashed or wrote nothing fails the job; the pictures it did write are still published. + if [ "$code" -ne 0 ] || [ "$count" -eq 0 ]; then + echo "::error title=Screenshots::$name --capture failed (exit $code, $count screenshot(s))" + failed=1 + fi done + exit $failed + + # BRIEF §20.2 visual regression against tests/visual/baselines: a screen beyond the tolerance fails, and so does one + # without a baseline once any baseline is committed; before the first ones the step warns that it compared nothing + # (the baselines README says how to add them). + - name: Screenshot diff + if: runner.os == 'Windows' && !cancelled() && hashFiles('out/screenshots/*.png') != '' + run: dotnet "$TOOLS" screenshots diff out/screenshots --baseline tests/visual/baselines --out out/screenshot-diff + + - name: Upload screenshot diffs + if: runner.os == 'Windows' && !cancelled() && hashFiles('out/screenshot-diff/*.png') != '' + continue-on-error: true + uses: actions/upload-artifact@v4 + with: + name: screenshot-diff + path: out/screenshot-diff/ + retention-days: 7 # Handed to the screenshots job through the cache: it does not count against the artifact storage quota. - name: Keep screenshots for the screenshots job @@ -180,6 +202,69 @@ jobs: git commit -q -m "Screenshots of ${{ github.event.pull_request.head.sha }}" git push -q -f "https://x-access-token:${{ github.token }}@github.com/${{ github.repository }}.git" HEAD:refs/heads/ci-screenshots + # BRIEF §18 on a clean runner: the real installers (published programs, TPK1 payload) installed silently, run, + # upgraded in place, uninstalled; .github/scripts/installer-test.ps1 checks every step. + installer: + name: Installer (windows-latest) + runs-on: windows-latest + timeout-minutes: 45 + defaults: + run: + shell: pwsh + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-dotnet@v4 + with: + global-json-file: global.json + + # As release.yml publishes them, without ReadyToRun (only start-up time differs). + - name: Publish App, Uploader and Setup (win-x64, self-contained single file) + run: | + foreach ($p in 'Titano.App', 'Titano.Uploader', 'Titano.Setup') { + dotnet publish "src/$p/$p.csproj" -c Release -r win-x64 --self-contained -p:PublishSingleFile=true ` + -p:IncludeNativeLibrariesForSelfExtract=true -p:PublishReadyToRun=false -o "out/publish/$p" + if ($LASTEXITCODE -ne 0) { throw "dotnet publish $p failed" } + } + + - name: Build Titano.Tools + run: | + dotnet build src/Titano.Tools/Titano.Tools.csproj -c Release + if ($LASTEXITCODE -ne 0) { throw 'Titano.Tools did not build' } + + # Version 1 ships one more file than version 2: the upgrade must remove it. + - name: Pack the installers + run: | + Copy-Item -Recurse out/publish/Titano.App out/app-v1 + Set-Content -LiteralPath out/app-v1/legacy.txt -Value 'only in version 1' + $installers = @( + @('--product', 'Titano', '--version', '1.0.0', '--component', 'Titano=out/app-v1', + '--component', 'Uploader=out/publish/Titano.Uploader', '--out', 'out/installers/Titano-Setup-1.0.0.exe'), + @('--product', 'Titano', '--version', '1.0.1', '--component', 'Titano=out/publish/Titano.App', + '--component', 'Uploader=out/publish/Titano.Uploader', '--out', 'out/installers/Titano-Setup-1.0.1.exe'), + @('--product', 'Titano Uploader', '--version', '1.0.1', '--component', 'Uploader=out/publish/Titano.Uploader', + '--out', 'out/installers/Titano-Uploader-Setup-1.0.1.exe')) + foreach ($installer in $installers) { + dotnet $env:TOOLS pack-installer --setup out/publish/Titano.Setup/Titano.Setup.exe @installer + if ($LASTEXITCODE -ne 0) { throw "pack-installer $installer failed" } + } + + - name: Install, run, upgrade and remove + run: | + ./.github/scripts/installer-test.ps1 -Setup1 out/installers/Titano-Setup-1.0.0.exe -Setup2 out/installers/Titano-Setup-1.0.1.exe ` + -UploaderSetup out/installers/Titano-Uploader-Setup-1.0.1.exe -Version1 1.0.0 -Version2 1.0.1 -Screenshots out/installer-screenshots + + - name: Setup logs + if: always() + run: | + $logs = Join-Path ([System.IO.Path]::GetTempPath()) 'Titano Setup' + if (-not (Test-Path -LiteralPath $logs)) { Write-Host "No setup log in '$logs'"; exit 0 } + Get-ChildItem -LiteralPath $logs -Filter *.log -File | Sort-Object Name | ForEach-Object { + Write-Host "::group::$($_.Name)" + Get-Content -LiteralPath $_.FullName + Write-Host '::endgroup::' + } + postgres: name: PostgreSQL ${{ matrix.pg }} integration strategy: @@ -201,11 +286,22 @@ jobs: --health-interval 5s --health-timeout 5s --health-retries 20 env: TITANO_TEST_PG: Host=127.0.0.1;Port=5432;Database=titano_test;Username=titano;Password=titano-ci;SslMode=disable + # Roles, pg_hba lines and TLS made by postgres-ci-setup.sh: with these set, the wire tests of MD5, cleartext, trust + # and TLS (BRIEF §6.3) run, and a server that refuses TLS fails them instead of skipping them. + TITANO_TEST_PG_MD5: Host=127.0.0.1;Port=5432;Database=titano_test;Username=titano_md5;Password=md5-ci;SslMode=disable + TITANO_TEST_PG_CLEARTEXT: Host=127.0.0.1;Port=5432;Database=titano_test;Username=titano_clear;Password=clear-ci;SslMode=disable + TITANO_TEST_PG_TRUST: Host=127.0.0.1;Port=5432;Database=titano_test;Username=titano_trust;SslMode=disable + TITANO_TEST_PG_TLS: "1" steps: - uses: actions/checkout@v4 - uses: actions/setup-dotnet@v4 with: global-json-file: global.json + # The image starts with TLS off and SCRAM only. + - name: Configure PostgreSQL (MD5, cleartext, trust, TLS) + run: | + bash .github/scripts/postgres-ci-setup.sh "${{ job.services.postgres.id }}" titano titano_test "$RUNNER_TEMP/pg-tls" + echo "TITANO_TEST_PG_ROOT_CERT=$RUNNER_TEMP/pg-tls/server.crt" >> "$GITHUB_ENV" - name: Test · Data (PostgreSQL) run: dotnet run --project tests/Titano.Data.Tests -c Release -- --junit out/junit/data-pg${{ matrix.pg }}.xml - name: Test · Server (PostgreSQL) diff --git a/README.md b/README.md index de869086..6a9b8712 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,8 @@ dotnet run --project tests/Titano.Tools.Tests -c Release dotnet run --project tests/Titano.Core.Windows.Tests -c Release # Windows dotnet run --project tests/Titano.App.Tests -c Release # Windows -# PostgreSQL integration tests (16 or 17) +# PostgreSQL integration tests (16 or 17); the MD5, cleartext, trust and TLS tests also read TITANO_TEST_PG_MD5, +# _CLEARTEXT, _TRUST, _TLS=1 and _ROOT_CERT (.github/scripts/postgres-ci-setup.sh prepares a server for them) TITANO_TEST_PG="Host=127.0.0.1;Port=5432;Database=titano_test;Username=titano;Password=…;SslMode=disable" \ dotnet run --project tests/Titano.Data.Tests -c Release @@ -38,6 +39,7 @@ dotnet run --project src/Titano.Tools -- package-guard dotnet run --project src/Titano.Tools -- i18n check dotnet run --project src/Titano.Tools -- xaml-lint dotnet format whitespace Titano.slnx --verify-no-changes +dotnet run --project src/Titano.Tools -- screenshots diff out/screenshots # Windows, after --capture (tests/visual/baselines/README.md) # CC0 RAW samples for the decoder tests (tests/fixtures/manifest.json explains how to fill in URLs) dotnet run --project src/Titano.Tools -- fixtures @@ -59,7 +61,7 @@ The server reads `/data/server.json` (`TITANO_DATA_PATH`) and `TITANO_*` environ | Workflow | When | What | |---|---|---| -| `.github/workflows/ci.yml` | push to `main`, pull requests | Windows + Linux build (warnings are errors), all tests, package guard, i18n check, XAML lint, format check, YAML check of workflows and public issue forms, CC0 fixtures (a warning per missing sample), screenshots (`--capture`, also pushed to the `ci-screenshots` branch for same-repository PRs), Windows program artifacts, PostgreSQL 16/17 integration, Docker image smoke test | +| `.github/workflows/ci.yml` | push to `main`, pull requests | Windows + Linux build (warnings are errors), all tests, package guard, i18n check, XAML lint, format check, YAML check of workflows and public issue forms, CC0 fixtures (a warning per missing sample), screenshots (`--capture`, also pushed to the `ci-screenshots` branch for same-repository PRs) and their pixel diff against `tests/visual/baselines`, Windows program artifacts, installer test (install, run, upgrade in place, uninstall), PostgreSQL 16/17 integration (SCRAM, MD5, cleartext, trust, TLS), Docker image smoke test | | `.github/workflows/docker.yml` | nightly | `ghcr.io//titano-server:nightly` (multi-arch) | | `.github/workflows/perf.yml` | weekly, manual | Performance gates on SQLite and PostgreSQL 17; timings in the job summary | | `.github/workflows/release.yml` | tag `v*`, manual re-publish | The release (below) | diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 3d0afd64..df191f33 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -16,7 +16,7 @@ Companion to `docs/BRIEF.md` (scope, behaviour) and `docs/ui/DESIGN.md` (looks). | `src/Titano.App` | WPF exe `Titano.exe` | Desktop client | | `src/Titano.Uploader` | WPF exe | Uploader (tray, watch folders, resumable queue) | | `src/Titano.Setup` | WPF exe | In-house installer/uninstaller (TPK1 payload) | -| `src/Titano.Tools` | net10.0 exe | CLI: `make-icon`, `i18n` (check, export, missing, import), `xaml-lint`, `package-guard`, `changelog`, `pack-installer`, `selftest`, `diagnose`, `fixtures` | +| `src/Titano.Tools` | net10.0 exe | CLI: `make-icon`, `i18n` (check, export, missing, import), `xaml-lint`, `package-guard`, `changelog`, `pack-installer`, `selftest`, `diagnose`, `fixtures`, `screenshots` (diff, accept) | | `tests/Titano.Testing` | net10.0 | In-house test framework (`[Test]`, `[Theory]`+`[Case]`, `[Category]`, `[RequiresEnvironment]`, `[WindowsOnly]`, `[Serial]`, `Assert`, `TestContext`, JUnit) | | `tests/Titano.*.Tests` | exe | One test program per area; `dotnet run --project tests/X -- --junit out.xml` | @@ -72,15 +72,15 @@ Dependencies point one way: `Core` ← `Core.Windows`, `Data`, `Protocol` ← `S | `Archive` | `CurrentArchive`, `ArchiveTree`, figures for the charts, maintenance reports, mass rename and move, delete and trash dialogs (`SequenceDeletion`, `DeletePlans`), `ArchiveFailures` | | `Server` | `ServerSession`, `ConnectFlow` (trust on first use), `SyncHost` (sync engine, agent, metered hold, editor connections, Export Sync), sync table, `RemoteSequenceApi` | | `Jobs`, `Settings`, `About` | Job list and buffering; settings rows, encoder and format inventories, `ProcessingTuning` (Settings › Rendering and Analysis applied to each job), `InterfacePriority`, language catalog, naming preview; update check and download | -| `Infrastructure` | `AppServices` (composition root), `AppSettings`, `AppEnvironment` (installed or portable), `UiLanguage`, `LiveRegion`, `RenderNodeHost`, `DiagnosticsBundle`, `ShellActions` (BRIEF §8.6), device monitor | -| `DesignTime` | `SampleData`: the archive, jobs and server the screenshots and smoke tests run on | +| `Infrastructure` | `AppServices` (composition root), `AppSettings`, `AppEnvironment` (installed or portable), `AppClock` (today's date, frozen by `--capture`), `UiLanguage`, `LiveRegion`, `RenderNodeHost`, `DiagnosticsBundle`, `ShellActions` (BRIEF §8.6), device monitor | +| `DesignTime` | `SampleData`: the archive, jobs and server the screenshots and smoke tests run on, dated from the fixed `SampleData.Now` | ### 2.4 Titano.Ui and Titano.Server | Folder | Content | |---|---| | `Ui/Themes`, `Ui/Theming` | DESIGN tokens (light, dark), typography, control styles, `ThemeManager` | -| `Ui/Controls` | `TitanoWindow` (chrome, language direction), `NavRail`, `JobBar`, `ToastHost`, `Field` (placeholder, icon, error), `Chip`, `AutoSlider`, `StatusGlyph`, `EmptyState`, `Icon`, `Bidi` (right-to-left rules) | +| `Ui/Controls` | `TitanoWindow` (chrome, language direction), `NavRail`, `JobBar`, `ToastHost`, `Field` (placeholder, icon, error), `Chip`, `AutoSlider`, `StatusGlyph`, `EmptyState`, `Icon`, `Bidi` (right-to-left rules), `Motion` (animations off for screenshots) | | `Ui/Visuals` | `DrawingElement` (hover readout, item keyboard and activation) and its charts (`BarChart`, `SeriesChart`, `StackedBar`, `HeatmapStrip`, `TimelineBands`), `Filmstrip`, `PreviewViewport`, `CurveEditor`, `SequenceCard`, `VirtualizingWrapPanel`, `SegmentedControl`, `SplitButton` | | `Server/Api`, `Server/Events` | Endpoint groups (`XxxEndpoints.Map`), API errors, the WebSocket `EventHub` | | `Server/Security` | Accounts, password hashing, tokens, session cookies, login guard, access rules, audit log | @@ -224,6 +224,9 @@ run as server jobs whose progress comes from the events. - Framework: `Titano.Testing`. Test classes are `public sealed`; constructor may take `TestContext` (temp directories, cancellation, log). `[WindowsOnly]` for OS-specific tests, `[RequiresEnvironment("TITANO_TEST_PG")]` for PostgreSQL integration tests. +- Classes run in parallel. A test that changes or observes process-wide state (the UI language, unobserved task + exceptions, the managed heap) belongs in a `[Serial]` class; the App and Core test programs fail a test outside one + that switches the language away from English, after switching it back (`TestContext.Current`). - Put tests under `tests/Titano..Tests//Tests.cs`, mirroring the source folder. - `Titano.App.Tests` targets net10.0-windows and runs on Windows CI only: keep logic in plain classes. - Fixtures are synthetic and generated in code wherever possible; tiny binary fixtures may go in `tests/fixtures/` @@ -234,7 +237,17 @@ run as server jobs whose progress comes from the events. 500,000-photo library (Library open < 1 s on a new connection pool, filters < 200 ms; the OS cache is warm from building it) and the 100,000-frame rebuild from sidecars (400 sequences of 250 real photos, every column compared, < 120 s), each on SQLite and PostgreSQL. `.github/workflows/perf.yml` runs them weekly against PostgreSQL 17. -- `Titano.Tools.Tests` covers the tools whose output CI relies on (fixtures annotations and exit codes). +- `Titano.Tools.Tests` covers the tools whose output CI relies on (fixtures annotations and exit codes, the screenshot + diff) and the test runner's outcomes. +- Visual regression: CI compares the `--capture` screenshots with `tests/visual/baselines` (`Titano.Tools screenshots + diff`; its README says how baselines are added). Once any baseline is committed, a screen without one fails too; + before that the step warns that it compared nothing. The capture draws the same pixels on any day: the sample's + clock is fixed, formats are English and nothing animates. +- Media Foundation output plays back (`Titano.Core.Windows.Tests`): MediaPlayer opens it where Windows Media Player + is installed (skipped, with the reason, where it is not) and a source reader decodes its first frame everywhere. +- PostgreSQL: CI prepares the service containers with `.github/scripts/postgres-ci-setup.sh` (MD5, cleartext and + trust roles, TLS), so every authentication method and TLS mode of BRIEF §6.3 runs; `TITANO_TEST_PG_TLS=1` makes a + server without TLS fail the TLS tests. ## 7. Localization @@ -258,7 +271,7 @@ dotnet format whitespace Titano.slnx --verify-no-changes | Workflow | Trigger | Does | |---|---|---| -| `ci.yml` | push to `main`, pull requests | Windows + Linux build and tests, guards, i18n, XAML lint, format, fixtures (warnings when missing), screenshots, PostgreSQL 16/17, Docker smoke test | +| `ci.yml` | push to `main`, pull requests | Windows + Linux build and tests, guards, i18n, XAML lint, format, fixtures (warnings when missing), screenshots and their pixel diff, installer test (install, run, upgrade, uninstall), PostgreSQL 16/17 (every authentication method, TLS), Docker smoke test | | `release.yml` | tag `v*` (or manual re-publish) | Tests, self-contained publish, optional signing, installers, portable and server zips, SHA256SUMS, release notes, multi-arch GHCR image, public releases repository update and GitHub release | | `docker.yml` | nightly | `ghcr.io//titano-server:nightly` | | `perf.yml` | weekly, manual | Performance gates (SQLite, PostgreSQL 17) with timings in the job summary | diff --git a/src/Titano.App/Archive/SampleReports.cs b/src/Titano.App/Archive/SampleReports.cs index e5d13298..d630cca5 100644 --- a/src/Titano.App/Archive/SampleReports.cs +++ b/src/Titano.App/Archive/SampleReports.cs @@ -1,3 +1,4 @@ +using Titano.App.DesignTime; using Titano.Core.Archiving; using Titano.Data.Archiving; using Titano.Data.Repositories; @@ -34,18 +35,18 @@ public static class SampleReports /// The trash dialog's rows: the first two sample sequences, deleted an hour and a day ago (nothing moves on disk). public static IReadOnlyList Trash(Guid archiveId, IReadOnlyList sequences) { - var now = DateTimeOffset.UtcNow; + var now = SampleData.Now; return [ .. sequences.Take(2).Select((s, i) => new TrashEntry(archiveId, s.Id.ToString("N"), s.Id, s.Title ?? s.Folder, s.Folder, 1_200 * (i + 1), 1_206 * (i + 1), - 31_457_280L * 1_200 * (i + 1), now.AddHours(-1 - (23 * i)), Environment.UserName)), + 31_457_280L * 1_200 * (i + 1), now.AddHours(-1 - (23 * i)), "alberto")), ]; } /// What the rebuild dialog counts: a sidecar in every sequence folder but the last two, read by metadata instead. public static IReadOnlyList Folders(IReadOnlyList sequences) { - var stamp = new FileStamp(4_096, DateTime.UtcNow); + var stamp = new FileStamp(4_096, SampleData.Now.UtcDateTime); return [.. sequences.Select((s, i) => new SequenceFolder(s.Folder, i < sequences.Count - 2 ? stamp : null, stamp))]; } } diff --git a/src/Titano.App/DesignTime/SampleData.cs b/src/Titano.App/DesignTime/SampleData.cs index 31096066..612a0ae7 100644 --- a/src/Titano.App/DesignTime/SampleData.cs +++ b/src/Titano.App/DesignTime/SampleData.cs @@ -39,6 +39,13 @@ public sealed class SampleData { public const string ServerFingerprint = "9A:3C:71:E0:5B:12:C4:88:0F:6D:2A:91:E7:44:B3:5C:19:D2:6F:80:A1:3E:57:C9:0B:64:F8:2D:93:A6:71:CE"; + /// + /// The sample's "now": every time it stores (jobs, transfers, renders, cards, the trash) is set from it, never from + /// the computer's clock, and --capture freezes at it, so the screenshots are the same + /// on any day (the running render's log reads 10:14 to 10:15). + /// + public static readonly DateTimeOffset Now = new(2026, 10, 2, 10, 18, 0, TimeSpan.Zero); + private const string ServerAddress = "https://nas.local:8443"; private readonly AppServices _services; @@ -85,7 +92,7 @@ public sealed class SampleData var settings = _services.Settings; var root = Path.Combine(_services.Environment.DataDirectory, "archive"); Directory.CreateDirectory(root); - var archive = new Archive { Id = Guid.CreateVersion7(), Name = "TitanoArchive", RootPath = root, Created = DateTimeOffset.UtcNow.AddYears(-2) }; + var archive = new Archive { Id = Guid.CreateVersion7(), Name = "TitanoArchive", RootPath = root, Created = Now.AddYears(-2) }; await db.Archives.UpsertAsync(archive); var paths = new ArchivePaths(root); Directory.CreateDirectory(paths.MetaDirectory); @@ -132,7 +139,7 @@ public sealed class SampleData { var db = _db ?? throw new InvalidOperationException("FillAsync first."); async Task LocalAsync(string text) => (await db.Sequences.ListAsync(new Data.Repositories.SequenceQuery { Text = text, Limit = 1 })).Items[0]; - var now = DateTimeOffset.UtcNow; + var now = Now; Job Transfer(JobKind kind, Guid target, string label, string parameters, JobState state, long done, long total) => new() { Id = Guid.CreateVersion7(), @@ -169,8 +176,16 @@ public sealed class SampleData { var db = _db ?? throw new InvalidOperationException("FillAsync first."); var service = _services.Sync.Service ?? throw new InvalidOperationException("The index is not open."); + // The history is kept whatever the date: the sample's finished jobs are dated from Now, not from today. await using var engine = new JobEngine(db, service.CreateJobHandlers(_services.Sync), - new JobEngineOptions { Workers = 1, WorkerId = "sample-proxies", Kinds = [JobKind.Download], PollInterval = TimeSpan.FromMilliseconds(50) }); + new JobEngineOptions + { + Workers = 1, + WorkerId = "sample-proxies", + Kinds = [JobKind.Download], + PollInterval = TimeSpan.FromMilliseconds(50), + HistoryRetention = TimeSpan.FromDays(36_500), + }); await engine.StartAsync(); var job = await service.EnqueueDownloadAsync(engine, ServerAddress, _sunrise, "Sunrise over Superga", SyncDownloadMode.Proxies, null); for (var i = 0; i < 200 && await db.Jobs.GetAsync(job.Id) is { State: JobState.Queued or JobState.Running }; i++) await Task.Delay(50); @@ -248,14 +263,14 @@ public sealed class SampleData Folder = "2026/2026-07-02 Sony ILCE-7M4", CameraMake = "SONY", CameraModel = "ILCE-7M4", - FirstCapture = DateTime.Today.AddDays(-96).AddHours(5.2), - LastCapture = DateTime.Today.AddDays(-96).AddHours(6.8), + FirstCapture = new DateTime(2026, 7, 2).AddHours(5.2), + LastCapture = new DateTime(2026, 7, 2).AddHours(6.8), MedianInterval = 2, FrameCount = 2_880, TotalBytes = 2_880 * 21_000_000L, Status = SequenceStatus.ProxiesBuilt | SequenceStatus.ThumbsBuilt, RenderedCount = 1, - UpdatedAt = DateTimeOffset.UtcNow, + UpdatedAt = Now, }), null, 3); _lakeComo = _remote.Add(SampleSyncRemote.Dto(new Sequence { @@ -265,13 +280,13 @@ public sealed class SampleData Folder = "2026/2026-08-21 Canon EOS R5", CameraMake = "Canon", CameraModel = "Canon EOS R5", - FirstCapture = DateTime.Today.AddDays(-46).AddHours(16.5), - LastCapture = DateTime.Today.AddDays(-46).AddHours(17.3), + FirstCapture = new DateTime(2026, 8, 21).AddHours(16.5), + LastCapture = new DateTime(2026, 8, 21).AddHours(17.3), MedianInterval = 2, FrameCount = 1_450, TotalBytes = 1_450 * 45_000_000L, Status = SequenceStatus.ThumbsBuilt, - UpdatedAt = DateTimeOffset.UtcNow, + UpdatedAt = Now, }), null, 3); static string DeflickerWindow(int frames) => @@ -334,7 +349,7 @@ public sealed class SampleData Fps = 24, DurationSeconds = 5, Bytes = bytes, - Created = DateTimeOffset.UtcNow.AddDays(-daysAgo), + Created = Now.AddDays(-daysAgo), ProducedBy = "studio-pc", }); } @@ -345,7 +360,7 @@ public sealed class SampleData public async Task MarkAnalysingAsync(Guid sequenceId) { var db = _db ?? throw new InvalidOperationException("OpenEmptyAsync first."); - var now = DateTimeOffset.UtcNow; + var now = Now; await db.Jobs.EnqueueAsync(new Job { Id = Guid.CreateVersion7(), @@ -357,7 +372,7 @@ public sealed class SampleData ProgressDone = 40, ProgressTotal = 96, ItemsPerSecond = 12, - NodeId = Environment.MachineName, + NodeId = _services.WorkerId, Attempts = 1, Created = now.AddSeconds(-5), Started = now.AddSeconds(-4), @@ -478,7 +493,7 @@ public sealed class SampleData WarningCount = warnings, Origin = origin, SyncState = sync, - UpdatedAt = DateTimeOffset.UtcNow, + UpdatedAt = Now, }, colours, raw); } @@ -599,7 +614,7 @@ public sealed class SampleData private IEnumerable Jobs(IReadOnlyList s, Guid archiveId) { - var now = DateTimeOffset.UtcNow; + var now = Now; var here = _services.WorkerId; Job Make(JobKind kind, Sequence? target, string label, JobState state, long done, long total, double? rate = null, TimeSpan? eta = null, TimeSpan? startedAgo = null, TimeSpan? runFor = null, string? node = null, string? error = null, string? log = null, @@ -653,7 +668,7 @@ public sealed class SampleData private sealed class SampleServerApi(SampleData sample, Uri baseAddress, IReadOnlyCollection trusted) : IServerApi { private UserDto User => new(Guid.Empty, "alberto", "Alberto", "editor", (long)sample._permissions, 5_000_000_000_000, 2_100_000_000_000, false, false, - new DateTimeOffset(2025, 1, 1, 0, 0, 0, TimeSpan.Zero), DateTimeOffset.UtcNow); + new DateTimeOffset(2025, 1, 1, 0, 0, 0, TimeSpan.Zero), Now); public Uri BaseAddress { get; } = baseAddress; @@ -669,7 +684,7 @@ public sealed class SampleData public Task LoginAsync(string username, string password, CancellationToken ct) { Token = "sample-token"; - return Task.FromResult(new LoginResponse(Token, User, false, DateTimeOffset.UtcNow.AddDays(30))); + return Task.FromResult(new LoginResponse(Token, User, false, Now.AddDays(30))); } public Task MeAsync(CancellationToken ct) => @@ -745,7 +760,7 @@ public sealed class SampleData lock (_sequences) { var (dto, settings, frames) = _sequences[id]; - var updated = dto with { SettingsVersion = dto.SettingsVersion + 1, UpdatedAt = DateTimeOffset.UtcNow }; + var updated = dto with { SettingsVersion = dto.SettingsVersion + 1, UpdatedAt = Now }; _sequences[id] = (updated, request.SettingsJson ?? settings, frames); return Task.FromResult(updated); } @@ -780,7 +795,7 @@ public sealed class SampleData public Task CreateJobAsync(CreateJobRequest request, CancellationToken cancellationToken) { var job = new JobDto(Guid.CreateVersion7(), request.Kind, request.Target, null, "queued", "user", 0, 0, null, null, null, null, 0, null, - DateTimeOffset.UtcNow, null, null); + Now, null, null); lock (_jobs) _jobs[job.Id] = job; return Task.FromResult(job); } @@ -788,7 +803,7 @@ public sealed class SampleData /// A job of running for , of frames. public void Run(Guid sequenceId, string kind, long done, long total) { - var now = DateTimeOffset.UtcNow; + var now = Now; var job = new JobDto(Guid.CreateVersion7(), kind, [sequenceId], null, "running", "user", done, total, 11.3, (total - done) / 11.3, null, "studio-pc", 1, null, now.AddMinutes(-2), now.AddMinutes(-2), null); lock (_jobs) _jobs[job.Id] = job; @@ -810,7 +825,7 @@ public sealed class SampleData } public Task CancelJobAsync(Guid id, CancellationToken cancellationToken) => - Task.FromResult(Update(id, job => job with { State = "cancelled", Finished = DateTimeOffset.UtcNow })); + Task.FromResult(Update(id, job => job with { State = "cancelled", Finished = Now })); public Task RetryJobAsync(Guid id, CancellationToken cancellationToken) => Task.FromResult(Update(id, job => job with { State = "queued", Error = null, Finished = null })); diff --git a/src/Titano.App/Import/SampleCards.cs b/src/Titano.App/Import/SampleCards.cs index 72df396c..1d09495d 100644 --- a/src/Titano.App/Import/SampleCards.cs +++ b/src/Titano.App/Import/SampleCards.cs @@ -1,4 +1,5 @@ using System.IO; +using Titano.App.DesignTime; using Titano.Core.Archiving; using Titano.Core.Codecs.Jpeg; using Titano.Core.Imaging; @@ -61,7 +62,7 @@ public static class SampleCards CameraModel = "Canon EOS R5", CameraSerial = "0431", FirstSeen = LastImport.AddMonths(-7), - LastSeen = DateTimeOffset.UtcNow, + LastSeen = SampleData.Now, }; await db.MediaCards.UpsertAsync(known); await db.MediaCards.RecordImportsAsync([new ImportRecord(known.Id, new ImportKey("DCIM/100CANON/IMG_9001.CR2", 24_000_000, LastImport), null, null, null, diff --git a/src/Titano.App/Infrastructure/AppClock.cs b/src/Titano.App/Infrastructure/AppClock.cs new file mode 100644 index 00000000..415a67fc --- /dev/null +++ b/src/Titano.App/Infrastructure/AppClock.cs @@ -0,0 +1,17 @@ +namespace Titano.App.Infrastructure; + +/// +/// Today's date for screens that lay themselves out around it (the Library timeline's years, the months of the +/// Archive heatmap). --capture freezes it at the sample's moment, so the screenshots draw the same pixels on +/// any day and the pixel diff against their baselines stays meaningful. +/// +public static class AppClock +{ + private static DateTimeOffset? _frozen; + + /// The local date: the frozen moment's while frozen, the computer's otherwise. + public static DateTime Today => (_frozen?.ToLocalTime().DateTime ?? DateTime.Now).Date; + + /// Stops the clock at for the rest of the process (screenshots only). + public static void Freeze(DateTimeOffset moment) => _frozen = moment; +} diff --git a/src/Titano.App/Sections/ArchiveViewModel.cs b/src/Titano.App/Sections/ArchiveViewModel.cs index 9f4cf246..29da745a 100644 --- a/src/Titano.App/Sections/ArchiveViewModel.cs +++ b/src/Titano.App/Sections/ArchiveViewModel.cs @@ -469,7 +469,7 @@ public sealed class ArchiveViewModel : SectionViewModel { _withoutProxies = withoutProxies; Tiles = ArchiveFigures.Tiles(stats); - MonthRows = [.. ArchiveFigures.PhotosPerMonth(stats, DateTime.Today).Select(r => new ChartRow(r.Label, r.Values, r.ToolTips))]; + MonthRows = [.. ArchiveFigures.PhotosPerMonth(stats, AppClock.Today).Select(r => new ChartRow(r.Label, r.Values, r.ToolTips))]; StorageBars = Bars(ArchiveFigures.StorageByYear(stats)); CameraBars = Bars(ArchiveFigures.ByCamera(stats)); FormatBars = Bars(ArchiveFigures.ByFormat(stats)); diff --git a/src/Titano.App/Sections/LibraryViewModel.cs b/src/Titano.App/Sections/LibraryViewModel.cs index 9b680bdc..410dc7b6 100644 --- a/src/Titano.App/Sections/LibraryViewModel.cs +++ b/src/Titano.App/Sections/LibraryViewModel.cs @@ -729,7 +729,7 @@ public sealed class LibraryViewModel : SectionViewModel try { var stats = LibraryFacets.Of(local, _remote, _origin.Value); - _timeline = LibraryTimeline.From(stats, DateTime.Today); + _timeline = LibraryTimeline.From(stats, AppClock.Today); var year = _year.Value; var camera = _camera.Value; Years = WithChosen([AnyYear(), .. stats.ByYear.OrderByDescending(y => y.Year).Select(y => new FilterOption(y.Year, YearText(y.Year), YearText(y.Year)))], diff --git a/src/Titano.App/Shell/ScreenCapture.cs b/src/Titano.App/Shell/ScreenCapture.cs index b9332acf..59545bd3 100644 --- a/src/Titano.App/Shell/ScreenCapture.cs +++ b/src/Titano.App/Shell/ScreenCapture.cs @@ -1,3 +1,4 @@ +using System.Globalization; using System.IO; using System.Windows; using System.Windows.Media; @@ -12,6 +13,7 @@ using Titano.App.Library; using Titano.App.Server; using Titano.App.Settings; using Titano.Core.Diagnostics; +using Titano.Ui.Controls; using Titano.Ui.Theming; namespace Titano.App.Shell; @@ -21,8 +23,10 @@ namespace Titano.App.Shell; /// <screen>-<theme>.png from (first run on an empty index, then a populated /// one, then the sync table with transfers, a conflict and its confirmation, then the sequence editor on an archive /// sequence and on a server sequence with proxies, its server job and a read-only account), plus the Library, the -/// editor's Exposure tab and the import plan in Arabic (*-rtl-dark.png, right to left), for visual review and -/// phase reports (BRIEF §20.2), then exits. +/// editor's Exposure tab and the import plan in Arabic (*-rtl-dark.png, right to left), for visual review, +/// the pixel diff against tests/visual/baselines and phase reports (BRIEF §20.2), then exits. The pictures are +/// the same on any day and machine: the clock stands at , formats are English and nothing +/// animates. /// public static class ScreenCapture { @@ -34,6 +38,9 @@ public static class ScreenCapture try { Directory.CreateDirectory(directory); + AppClock.Freeze(SampleData.Now); + CultureInfo.CurrentCulture = CultureInfo.DefaultThreadCurrentCulture = CultureInfo.GetCultureInfo("en"); + Motion.SetIsEnabled(window, false); window.WindowStartupLocation = WindowStartupLocation.Manual; window.Left = -20000; window.Top = -20000; @@ -196,6 +203,7 @@ public static class ScreenCapture dialog.Top = -20000; dialog.ShowActivated = false; dialog.ShowInTaskbar = false; + Motion.SetIsEnabled(dialog, false); dialog.Show(); try { diff --git a/src/Titano.Tools/Commands/ScreenshotsCommand.cs b/src/Titano.Tools/Commands/ScreenshotsCommand.cs new file mode 100644 index 00000000..3b20cb5b --- /dev/null +++ b/src/Titano.Tools/Commands/ScreenshotsCommand.cs @@ -0,0 +1,310 @@ +using System.Globalization; +using System.Text; +using Titano.Core.Codecs.Png; + +namespace Titano.Tools.Commands; + +/// +/// Visual regression for the --capture screenshots (BRIEF §20.2). screenshots diff <dir> compares every +/// PNG with the baseline of the same name (tests/visual/baselines unless --baseline): a pixel differs when +/// one of its channels moves by more than --tolerance (of 255), and a screen fails when more than --max-diff +/// of its pixels differ (a fraction), when its size changed, or when a baseline has no screenshot any more. A screen +/// without a baseline fails once the baseline folder holds any PNG, so a screen added later cannot stay ungated; before +/// the first baselines are committed nothing is compared, and the run says so in a warning and in its summary instead +/// of passing for a clean diff. Every screen with differing pixels gets <name>-diff.png in --out (the +/// baseline faded to grey, the differing pixels magenta) and the run a summary.md there, copied to the job summary +/// in GitHub Actions. screenshots accept <dir> copies the screenshots over the baselines. +/// +internal sealed class ScreenshotsCommand : ICommand +{ + /// Absorbs the last-bit noise of anti-aliased edges, not a changed colour. + public const int DefaultTolerance = 8; + + /// + /// 0.05 %: about 650 pixels of a 1440×900 screen. A few digits of a measured value (latency, the last comparison's + /// time) stay below it; a moved or resized control, a new colour or a missing picture do not. + /// + public const double DefaultMaxDiff = 0.0005; + + public string Name => "screenshots"; + public string Summary => "Pixel diff of --capture screenshots against tests/visual/baselines (diff [--baseline, --out, --tolerance, --max-diff]; accept )"; + + public Task RunAsync(string[] args) => Task.FromResult(Run(args, Environment.GetEnvironmentVariable, Console.Out)); + + /// The command with its environment passed in: tests run it without GitHub annotations or job summary. + internal static int Run(string[] args, Func environment, TextWriter output) + { + var a = new Args(args); + if (a.Positional is not [var verb, var directory]) throw new ToolException("Usage: screenshots diff [--baseline ] [--out ] [--tolerance 0-255] [--max-diff fraction] | screenshots accept [--baseline ]"); + if (!Directory.Exists(directory)) throw new ToolException($"Screenshot folder not found: {directory}"); + var baseline = a.Get("baseline") ?? Path.Combine(Args.RepoRoot(), "tests", "visual", "baselines"); + switch (verb) + { + case "diff": + var options = new DiffOptions( + directory, + baseline, + a.Get("out") ?? Path.TrimEndingDirectorySeparator(Path.GetFullPath(directory)) + "-diff", + ParseTolerance(a.Get("tolerance")), + ParseMaxDiff(a.Get("max-diff"))); + var actions = environment("GITHUB_ACTIONS") == "true"; + var summary = actions ? environment("GITHUB_STEP_SUMMARY") : null; + return Diff(options, output, annotate: actions, stepSummary: summary).Fails ? 1 : 0; + case "accept": + Directory.CreateDirectory(baseline); + var accepted = 0; + foreach (var file in Directory.EnumerateFiles(directory, "*.png").Order(StringComparer.Ordinal)) + { + File.Copy(file, Path.Combine(baseline, Path.GetFileName(file)), overwrite: true); + accepted++; + } + output.WriteLine($"{accepted} screenshot(s) copied to {baseline}"); + return 0; + default: + throw new ToolException($"Unknown screenshots verb '{verb}' (use diff or accept)."); + } + } + + internal sealed record DiffOptions(string Directory, string Baseline, string Output, int Tolerance, double MaxDiff); + + internal enum Verdict + { + /// No pixel beyond the tolerance. + Same, + + /// Some pixels beyond the tolerance, no more than the allowed fraction. + Within, + + Changed, + Resized, + Unreadable, + + /// A screenshot without a baseline while the baseline folder holds none at all: warns only. + New, + + /// A screenshot without a baseline while other screens have one. + Unbased, + + /// A baseline whose screen was not captured. + Missing, + } + + internal sealed record ScreenResult(string Name, Verdict Verdict, long Differing, long Pixels, string? Detail = null) + { + public double Fraction => Pixels == 0 ? 0 : (double)Differing / Pixels; + public bool Fails => Verdict is Verdict.Changed or Verdict.Resized or Verdict.Unreadable or Verdict.Unbased or Verdict.Missing; + } + + /// The baseline folder holds at least one PNG: from then on every screen needs its own. + internal sealed record DiffReport(IReadOnlyList Screens, bool Armed) + { + public bool Fails => Screens.Any(s => s.Fails); + } + + /// RGBA, 8 bits per channel, top-down. + internal sealed record Picture(int Width, int Height, byte[] Pixels); + + /// Compares the folders, writes the diff images and summary.md, and reports every screen. + internal static DiffReport Diff(DiffOptions options, TextWriter output, bool annotate, string? stepSummary) + { + var captured = PngNames(options.Directory); + var baselines = Directory.Exists(options.Baseline) ? PngNames(options.Baseline) : new SortedSet(StringComparer.OrdinalIgnoreCase); + var armed = baselines.Count > 0; + // Diffs of an earlier run must not pass for this run's. + if (Directory.Exists(options.Output)) + { + foreach (var old in Directory.EnumerateFiles(options.Output, "*-diff.png")) File.Delete(old); + } + Directory.CreateDirectory(options.Output); + + var results = new List(); + foreach (var name in captured) + { + if (!baselines.Contains(name)) + { + results.Add(new ScreenResult(name, armed ? Verdict.Unbased : Verdict.New, 0, 0)); + continue; + } + results.Add(CompareFiles(name, Path.Combine(options.Baseline, name), Path.Combine(options.Directory, name), options)); + } + results.AddRange(baselines.Where(b => !captured.Contains(b)).Select(b => new ScreenResult(b, Verdict.Missing, 0, 0))); + results.Sort((x, y) => StringComparer.OrdinalIgnoreCase.Compare(x.Name, y.Name)); + + foreach (var r in results) output.WriteLine($"{Label(r.Verdict),-11} {r.Name}{Describe(r, options)}"); + var report = new DiffReport(results, armed); + var markdown = Markdown(report, options); + File.WriteAllText(Path.Combine(options.Output, "summary.md"), markdown); + if (stepSummary is not null) File.AppendAllText(stepSummary, markdown); + output.WriteLine(Totals(report)); + if (annotate) + { + foreach (var r in results.Where(r => r.Fails)) + { + var title = r.Verdict == Verdict.Unbased ? "Screenshot without baseline" : "Screenshot " + Label(r.Verdict); + output.WriteLine($"::error title={Escape(title, property: true)}::{Escape(r.Name + Describe(r, options), property: false)}"); + } + // One warning for them all (GitHub shows only ten): before the first baselines every screen is new. + var unbased = results.Where(r => r.Verdict == Verdict.New).Select(r => r.Name).ToList(); + if (unbased.Count > 0) + { + var names = string.Join(", ", unbased.Take(5)) + (unbased.Count > 5 ? ", …" : string.Empty); + output.WriteLine($"::warning title={Escape("No screenshot baselines", property: true)}::" + + Escape($"{NotArmed} {unbased.Count} screenshot(s) without a baseline ({names}); tests/visual/baselines/README.md says how to add them.", property: false)); + } + } + return report; + } + + private static ScreenResult CompareFiles(string name, string baselinePath, string capturedPath, DiffOptions options) + { + Picture expected, actual; + try + { + expected = Read(baselinePath); + actual = Read(capturedPath); + } + catch (InvalidDataException ex) + { + return new ScreenResult(name, Verdict.Unreadable, 0, 0, ex.Message); + } + if (expected.Width != actual.Width || expected.Height != actual.Height) + return new ScreenResult(name, Verdict.Resized, 0, 0, $"{actual.Width}×{actual.Height}, baseline {expected.Width}×{expected.Height}"); + + var (differing, diff) = Compare(expected, actual, options.Tolerance); + var pixels = (long)actual.Width * actual.Height; + if (differing == 0) return new ScreenResult(name, Verdict.Same, 0, pixels); + File.WriteAllBytes(Path.Combine(options.Output, Path.GetFileNameWithoutExtension(name) + "-diff.png"), + PngEncoder.Encode(diff, actual.Width, actual.Height, PngColorType.Rgb, level: System.IO.Compression.CompressionLevel.Fastest)); + var verdict = (double)differing / pixels > options.MaxDiff ? Verdict.Changed : Verdict.Within; + return new ScreenResult(name, verdict, differing, pixels); + } + + /// + /// Counts the pixels where a channel differs by more than and draws the diff image: the + /// baseline as faded grey, differing pixels magenta. + /// + internal static (long Differing, byte[] Diff) Compare(Picture expected, Picture actual, int tolerance) + { + if (expected.Width != actual.Width || expected.Height != actual.Height) throw new ArgumentException("The pictures differ in size."); + var count = expected.Width * expected.Height; + var diff = new byte[count * 3]; + long differing = 0; + var e = expected.Pixels; + var a = actual.Pixels; + for (var i = 0; i < count; i++) + { + var p = i * 4; + var delta = Math.Max(Math.Max(Math.Abs(e[p] - a[p]), Math.Abs(e[p + 1] - a[p + 1])), Math.Max(Math.Abs(e[p + 2] - a[p + 2]), Math.Abs(e[p + 3] - a[p + 3]))); + var q = i * 3; + if (delta > tolerance) + { + differing++; + diff[q] = 255; + diff[q + 1] = 0; + diff[q + 2] = 255; + continue; + } + // Rec.709 luma of the baseline, over its alpha, squeezed into 112..207 so magenta stands out in light and dark themes. + var luma = (e[p] * 54 + e[p + 1] * 183 + e[p + 2] * 19) >> 8; + var grey = (byte)(112 + luma * e[p + 3] / 255 * 3 / 8); + diff[q] = diff[q + 1] = diff[q + 2] = grey; + } + return (differing, diff); + } + + /// Decodes a PNG of any colour type and depth to (16-bit samples keep their high byte). + internal static Picture Read(string path) + { + var png = PngDecoder.Decode(File.ReadAllBytes(path)); + var count = png.Width * png.Height; + var rgba = new byte[count * 4]; + var channels = png.Channels; + for (var i = 0; i < count; i++) + { + byte Sample(int c) => png.Pixels8 is { } p8 ? p8[i * channels + c] : (byte)(png.Pixels16![i * channels + c] >> 8); + var (r, g, b, alpha) = channels switch + { + 1 => (Sample(0), Sample(0), Sample(0), (byte)255), + 2 => (Sample(0), Sample(0), Sample(0), Sample(1)), + 3 => (Sample(0), Sample(1), Sample(2), (byte)255), + _ => (Sample(0), Sample(1), Sample(2), Sample(3)), + }; + rgba[i * 4] = r; + rgba[i * 4 + 1] = g; + rgba[i * 4 + 2] = b; + rgba[i * 4 + 3] = alpha; + } + return new Picture(png.Width, png.Height, rgba); + } + + private static SortedSet PngNames(string directory) => + new(Directory.EnumerateFiles(directory, "*.png").Select(f => Path.GetFileName(f)), StringComparer.OrdinalIgnoreCase); + + private static string Label(Verdict verdict) => verdict switch + { + Verdict.Same => "same", + Verdict.Within => "tolerated", + Verdict.Changed => "changed", + Verdict.Resized => "resized", + Verdict.Unreadable => "unreadable", + Verdict.New => "new", + Verdict.Unbased => "no baseline", + _ => "missing", + }; + + private static string Describe(ScreenResult r, DiffOptions options) => r.Verdict switch + { + Verdict.Same => string.Empty, + Verdict.Within or Verdict.Changed => $": {Percent(r.Fraction)} of the pixels differ ({r.Differing.ToString("N0", CultureInfo.InvariantCulture)}; limit {Percent(options.MaxDiff)})", + Verdict.Resized or Verdict.Unreadable => $": {r.Detail}", + Verdict.New => ": no baseline", + Verdict.Unbased => ": no baseline, while other screens have one (screenshots accept adds it)", + _ => ": a baseline without a screenshot", + }; + + /// What a run before the first baselines must not hide: it compared nothing, so it could not have failed. + private const string NotArmed = "The baseline folder holds no PNG: nothing was compared, and no visual change can fail this step until baselines are committed."; + + private static string Percent(double fraction) => (fraction * 100).ToString("0.###", CultureInfo.InvariantCulture) + " %"; + + private static string Totals(DiffReport report) + { + int Count(params Verdict[] verdicts) => report.Screens.Count(s => verdicts.Contains(s.Verdict)); + return $"{Count(Verdict.Same, Verdict.Within, Verdict.Changed, Verdict.Resized, Verdict.Unreadable)} compared: {Count(Verdict.Same, Verdict.Within)} within tolerance, " + + $"{Count(Verdict.Changed, Verdict.Resized, Verdict.Unreadable)} changed; {Count(Verdict.New, Verdict.Unbased)} without a baseline; {Count(Verdict.Missing)} missing."; + } + + private static string Markdown(DiffReport report, DiffOptions options) + { + var md = new StringBuilder(); + md.AppendLine("### Screenshot diff").AppendLine(); + md.AppendLine(CultureInfo.InvariantCulture, $"Tolerance {options.Tolerance} of 255 per channel, at most {Percent(options.MaxDiff)} of the pixels.").AppendLine(); + if (!report.Armed) md.AppendLine(CultureInfo.InvariantCulture, $"**{NotArmed}**").AppendLine(); + var listed = report.Screens.Where(s => s.Verdict != Verdict.Same).ToList(); + if (listed.Count > 0) + { + md.AppendLine("| Screen | Result | Detail |").AppendLine("|---|---|---|"); + foreach (var r in listed) md.AppendLine(CultureInfo.InvariantCulture, $"| {r.Name} | {Label(r.Verdict)} | {Describe(r, options).TrimStart(':', ' ')} |"); + md.AppendLine(); + } + md.AppendLine(Totals(report)).AppendLine(); + return md.ToString(); + } + + private static int ParseTolerance(string? value) => + value is null ? DefaultTolerance + : int.TryParse(value, NumberStyles.None, CultureInfo.InvariantCulture, out var t) && t is >= 0 and <= 255 ? t + : throw new ToolException($"--tolerance takes 0 to 255, not '{value}'."); + + private static double ParseMaxDiff(string? value) => + value is null ? DefaultMaxDiff + : double.TryParse(value, NumberStyles.Float, CultureInfo.InvariantCulture, out var f) && f is >= 0 and <= 1 ? f + : throw new ToolException($"--max-diff takes a fraction from 0 to 1, not '{value}'."); + + /// Workflow-command escaping (properties also escape ':' and ','). + private static string Escape(string value, bool property) + { + var escaped = value.Replace("%", "%25", StringComparison.Ordinal).Replace("\r", "%0D", StringComparison.Ordinal).Replace("\n", "%0A", StringComparison.Ordinal); + return property ? escaped.Replace(":", "%3A", StringComparison.Ordinal).Replace(",", "%2C", StringComparison.Ordinal) : escaped; + } +} diff --git a/src/Titano.Tools/Program.cs b/src/Titano.Tools/Program.cs index 1e573c1f..a9b4c7a7 100644 --- a/src/Titano.Tools/Program.cs +++ b/src/Titano.Tools/Program.cs @@ -12,6 +12,7 @@ var commands = new ICommand[] new SelfTestCommand(), new DiagnoseCommand(), new FixturesCommand(), + new ScreenshotsCommand(), }; if (args.Length == 0 || args[0] is "-h" or "--help" or "help") diff --git a/src/Titano.Ui/Controls/Motion.cs b/src/Titano.Ui/Controls/Motion.cs new file mode 100644 index 00000000..99583972 --- /dev/null +++ b/src/Titano.Ui/Controls/Motion.cs @@ -0,0 +1,18 @@ +using System.Windows; + +namespace Titano.Ui.Controls; + +/// +/// Whether controls animate, inherited down the visual tree from where it is set. The screenshots (--capture) +/// turn it off on their windows: an indeterminate bar then stands still, so a screen draws the same pixels every run +/// and the pixel diff against its baseline compares like with like. +/// +public static class Motion +{ + public static readonly DependencyProperty IsEnabledProperty = DependencyProperty.RegisterAttached( + "IsEnabled", typeof(bool), typeof(Motion), new FrameworkPropertyMetadata(true, FrameworkPropertyMetadataOptions.Inherits)); + + public static bool GetIsEnabled(DependencyObject d) => (bool)d.GetValue(IsEnabledProperty); + + public static void SetIsEnabled(DependencyObject d, bool value) => d.SetValue(IsEnabledProperty, value); +} diff --git a/src/Titano.Ui/Themes/Controls.xaml b/src/Titano.Ui/Themes/Controls.xaml index 158b26f7..25e8abf6 100644 --- a/src/Titano.Ui/Themes/Controls.xaml +++ b/src/Titano.Ui/Themes/Controls.xaml @@ -611,7 +611,8 @@ - + + @@ -625,17 +626,23 @@ - + + + + + + + - - + + - - + + diff --git a/src/Titano.Uploader/DesignTime/SampleData.cs b/src/Titano.Uploader/DesignTime/SampleData.cs index c772e824..3d2d80a3 100644 --- a/src/Titano.Uploader/DesignTime/SampleData.cs +++ b/src/Titano.Uploader/DesignTime/SampleData.cs @@ -20,6 +20,9 @@ public sealed class SampleData private const int FileCount = 4_812; private const long FileSize = 20_000_000; + /// The sample's "now" (when the failed file failed): fixed, so the screenshots are the same on any day. + private static readonly DateTime Now = new(2026, 9, 28, 19, 2, 0, DateTimeKind.Utc); + private readonly SampleSession _session = new(); private readonly UploadQueue _queue = new(); private MainViewModel? _vm; @@ -88,7 +91,7 @@ public sealed class SampleData _queue.Items[2_201].State = UploadItemState.Uploading; _queue.Items[2_201].BytesSent = FileSize * 46 / 100; _queue.Items[2_202].State = UploadItemState.Hashing; - _queue.Fail(_queue.Items[2_203], UploadFailure.FileUnreadable, null, DateTime.UtcNow); + _queue.Fail(_queue.Items[2_203], UploadFailure.FileUnreadable, null, Now); } private sealed class SampleSession : IServerSession diff --git a/src/Titano.Uploader/Shell/ScreenCapture.cs b/src/Titano.Uploader/Shell/ScreenCapture.cs index 9cfc8df9..ddf97bf0 100644 --- a/src/Titano.Uploader/Shell/ScreenCapture.cs +++ b/src/Titano.Uploader/Shell/ScreenCapture.cs @@ -1,9 +1,11 @@ +using System.Globalization; using System.IO; using System.Windows; using System.Windows.Media; using System.Windows.Media.Imaging; using System.Windows.Threading; using Titano.Core.Diagnostics; +using Titano.Ui.Controls; using Titano.Ui.Theming; using Titano.Uploader.DesignTime; @@ -11,8 +13,9 @@ namespace Titano.Uploader.Shell; /// /// Titano.Uploader.exe --capture <dir>: renders the window at its default 760×700 — first run (connect), -/// queue running, settings panel — from in the dark and light themes, then once more in -/// Arabic (right to left, dark), and exits. +/// queue running, settings panel — from in the dark and light themes, in English whatever the +/// computer's language, then once more in Arabic (right to left, dark), and exits. Nothing animates, so the pictures +/// compare with their baselines pixel for pixel. /// public static class ScreenCapture { @@ -20,7 +23,7 @@ public static class ScreenCapture private const double Height = 700; /// Where the PNG files go. - /// Switches the UI language (a culture name; null = the OS language). + /// Switches the UI language (a culture name). public static void Run(string directory, Action applyLanguage) { Directory.CreateDirectory(directory); @@ -28,7 +31,8 @@ public static class ScreenCapture { try { - applyLanguage(null); + CultureInfo.CurrentCulture = CultureInfo.DefaultThreadCurrentCulture = CultureInfo.GetCultureInfo("en"); + applyLanguage("en"); CaptureScreens(directory, string.Empty, [AppTheme.Dark, AppTheme.Light]); // Mirrored layout with paths, addresses and file names kept left to right (BRIEF §16). applyLanguage("ar"); @@ -62,6 +66,7 @@ public static class ScreenCapture ShowActivated = false, ShowInTaskbar = false, }; + Motion.SetIsEnabled(window, false); window.Show(); try { diff --git a/tests/Titano.App.Tests/Archive/ArchiveLanguageTests.cs b/tests/Titano.App.Tests/Archive/ArchiveLanguageTests.cs new file mode 100644 index 00000000..2fbbce94 --- /dev/null +++ b/tests/Titano.App.Tests/Archive/ArchiveLanguageTests.cs @@ -0,0 +1,61 @@ +using System.Globalization; +using Titano.App.Archiving; +using Titano.Core.Archiving; +using Titano.Core.Localization; +using Titano.Testing; +using static Titano.App.Tests.Archiving.ArchiveLogicTests; + +namespace Titano.App.Tests.Archiving; + +/// +/// Archive texts in other languages. They switch the process-wide UI language, so the class is serial: in parallel it +/// would race with the English assertions of the classes running beside it. +/// +[Serial] +public sealed class ArchiveLanguageTests +{ + public ArchiveLanguageTests() => Loc.SetCulture(CultureInfo.GetCultureInfo("en")); + + [Test] + public void MonthColumnsAreInitialsOnlyWhereTheyAreLetters() + { + var numbers = Enumerable.Range(1, 12).Select(m => m.ToString(CultureInfo.InvariantCulture)).ToArray(); + try + { + Assert.Equal("J F M A M J J A S O N D", string.Join(' ', ArchiveFigures.MonthLabels())); + Loc.SetCulture(CultureInfo.GetCultureInfo("it")); + Assert.Equal("G F M A M G L A S O N D", string.Join(' ', ArchiveFigures.MonthLabels())); + // Numbered abbreviations ("10月", "Tháng 10") would read "1" for October to December, or "T" for every month. + foreach (var culture in new[] { "ja", "ko", "zh-Hans", "zh-Hant", "vi", "th", "ar", "he" }) + { + Loc.SetCulture(CultureInfo.GetCultureInfo(culture)); + Assert.SequenceEqual(numbers, ArchiveFigures.MonthLabels(), culture); + } + } + finally + { + Loc.SetCulture(CultureInfo.GetCultureInfo("en")); + } + } + + [Test] + public void TreeRowsShowTheirWholeTitleAndTheKeysOfTheReadingDirection() + { + var harbour = Seq("Construction cam · weekly", new DateTime(2026, 9, 28), 3_600, 72_000_000_000); + var tree = ArchiveTree.Build(Main, ArchiveAvailability.Online, [harbour]); + var year = new ArchiveTreeRowViewModel(tree.Root.Children[0], ArchiveAvailability.Online, _ => { }); + var sequence = new ArchiveTreeRowViewModel(tree.Root.Children[0].Children[0], ArchiveAvailability.Online, _ => { }); + Assert.Equal("Construction cam · weekly · 3,600 photos · 72 GB", sequence.RowToolTip); + Assert.Equal("2026 · 1 sequence · 72 GB · Right arrow opens the year, Left arrow closes it", year.RowToolTip); + try + { + Loc.SetCulture(CultureInfo.GetCultureInfo("he")); + Assert.Equal(Loc.L("Tooltips.Archive.YearRowRtl", "2026" + Loc.Separator + year.Detail), year.RowToolTip, "the arrow keys of a mirrored tree"); + Assert.Contains("‏", year.RowToolTip, "right-to-left marks keep the year and its figures apart"); + } + finally + { + Loc.SetCulture(CultureInfo.GetCultureInfo("en")); + } + } +} diff --git a/tests/Titano.App.Tests/Archive/ArchiveLogicTests.cs b/tests/Titano.App.Tests/Archive/ArchiveLogicTests.cs index 25ad9d8d..4bd6cca6 100644 --- a/tests/Titano.App.Tests/Archive/ArchiveLogicTests.cs +++ b/tests/Titano.App.Tests/Archive/ArchiveLogicTests.cs @@ -17,11 +17,11 @@ namespace Titano.App.Tests.Archiving; public sealed class ArchiveLogicTests { - private static readonly Core.Model.Archive Main = new() { Id = Guid.CreateVersion7(), Name = "TitanoArchive", RootPath = "/archive" }; + internal static readonly Core.Model.Archive Main = new() { Id = Guid.CreateVersion7(), Name = "TitanoArchive", RootPath = "/archive" }; public ArchiveLogicTests() => Loc.SetCulture(CultureInfo.GetCultureInfo("en")); - private static Sequence Seq(string title, DateTime? first, int frames = 100, long bytes = 1_000_000, params string[] tags) => new() + internal static Sequence Seq(string title, DateTime? first, int frames = 100, long bytes = 1_000_000, params string[] tags) => new() { Id = Guid.CreateVersion7(), ArchiveId = Main.Id, @@ -170,28 +170,6 @@ public sealed class ArchiveLogicTests Assert.Empty(ArchiveFigures.PhotosPerMonth(Stats() with { ByMonth = [] }, DateTime.Today)); } - [Test] - public void MonthColumnsAreInitialsOnlyWhereTheyAreLetters() - { - var numbers = Enumerable.Range(1, 12).Select(m => m.ToString(CultureInfo.InvariantCulture)).ToArray(); - try - { - Assert.Equal("J F M A M J J A S O N D", string.Join(' ', ArchiveFigures.MonthLabels())); - Loc.SetCulture(CultureInfo.GetCultureInfo("it")); - Assert.Equal("G F M A M G L A S O N D", string.Join(' ', ArchiveFigures.MonthLabels())); - // Numbered abbreviations ("10月", "Tháng 10") would read "1" for October to December, or "T" for every month. - foreach (var culture in new[] { "ja", "ko", "zh-Hans", "zh-Hant", "vi", "th", "ar", "he" }) - { - Loc.SetCulture(CultureInfo.GetCultureInfo(culture)); - Assert.SequenceEqual(numbers, ArchiveFigures.MonthLabels(), culture); - } - } - finally - { - Loc.SetCulture(CultureInfo.GetCultureInfo("en")); - } - } - [Test] public void TilesAndHealthSummariseTheIndex() { @@ -246,27 +224,6 @@ public sealed class ArchiveLogicTests Assert.Equal(Loc.L("Archive.Error.StalePlan"), ArchiveFailures.Cause(new StaleRenamePlanException(Guid.NewGuid()))); } - [Test] - public void TreeRowsShowTheirWholeTitleAndTheKeysOfTheReadingDirection() - { - var harbour = Seq("Construction cam · weekly", new DateTime(2026, 9, 28), 3_600, 72_000_000_000); - var tree = ArchiveTree.Build(Main, ArchiveAvailability.Online, [harbour]); - var year = new ArchiveTreeRowViewModel(tree.Root.Children[0], ArchiveAvailability.Online, _ => { }); - var sequence = new ArchiveTreeRowViewModel(tree.Root.Children[0].Children[0], ArchiveAvailability.Online, _ => { }); - Assert.Equal("Construction cam · weekly · 3,600 photos · 72 GB", sequence.RowToolTip); - Assert.Equal("2026 · 1 sequence · 72 GB · Right arrow opens the year, Left arrow closes it", year.RowToolTip); - try - { - Loc.SetCulture(CultureInfo.GetCultureInfo("he")); - Assert.Equal(Loc.L("Tooltips.Archive.YearRowRtl", "2026" + Loc.Separator + year.Detail), year.RowToolTip, "the arrow keys of a mirrored tree"); - Assert.Contains("\u200F", year.RowToolTip, "right-to-left marks keep the year and its figures apart"); - } - finally - { - Loc.SetCulture(CultureInfo.GetCultureInfo("en")); - } - } - [Test] public void RenameTemplatesAreCheckedAndThePlanListedByMode() { diff --git a/tests/Titano.App.Tests/Import/CardPoolTests.cs b/tests/Titano.App.Tests/Import/CardPoolTests.cs index 91e7f88e..02875fd6 100644 --- a/tests/Titano.App.Tests/Import/CardPoolTests.cs +++ b/tests/Titano.App.Tests/Import/CardPoolTests.cs @@ -8,9 +8,9 @@ namespace Titano.App.Tests.Import; public sealed class CardPoolTests { - private static readonly CardDevice CardA = new(@"F:\", "EOS_DIGITAL", 0x3F2A9C11, 128_000_000_000, 31_800_000_000, true, true); + internal static readonly CardDevice CardA = new(@"F:\", "EOS_DIGITAL", 0x3F2A9C11, 128_000_000_000, 31_800_000_000, true, true); private static readonly CardDevice GoPro = new(@"E:\", "GOPRO", 0x11112222, 64_000_000_000, 52_600_000_000, true, true); - private static readonly CardDevice Usb = new(@"G:\", "BACKUP", 0x99990000, 2_000_000_000_000, 1_800_000_000_000, true, false); + internal static readonly CardDevice Usb = new(@"G:\", "BACKUP", 0x99990000, 2_000_000_000_000, 1_800_000_000_000, true, false); public CardPoolTests() => Loc.SetCulture(CultureInfo.GetCultureInfo("en")); @@ -77,25 +77,6 @@ public sealed class CardPoolTests Assert.Equal(@"Folder · D:\Shoots\2026", pool[2].ToolTip); } - [Test] - public void PathsAndSerialsStayLeftToRightInARightToLeftLanguage() - { - try - { - Loc.SetCulture(CultureInfo.GetCultureInfo("he")); - var pool = CardPool.Build([Usb with { Label = string.Empty }, CardA], [], @"D:\Shoots\"); - Assert.Equal("\u202AG:\\\u202C", pool[1].Title, "a drive root keeps its separator at its end"); - Assert.Equal("\u202AD:\\Shoots\\\u202C", pool[2].Title); - Assert.Equal("\u202AD:\\Shoots\\\u202C", pool[2].Subtitle); - Assert.Contains("\u202A3F2A-9C11\u202C", pool[0].IdentityText); - Assert.Equal("EOS_DIGITAL", pool[0].Title, "a label is left to bidi"); - } - finally - { - Loc.SetCulture(CultureInfo.GetCultureInfo("en")); - } - } - [Test] public void AKnownCardWithoutDcimIsStillACard() { diff --git a/tests/Titano.App.Tests/Import/ImportLanguageTests.cs b/tests/Titano.App.Tests/Import/ImportLanguageTests.cs new file mode 100644 index 00000000..c9150447 --- /dev/null +++ b/tests/Titano.App.Tests/Import/ImportLanguageTests.cs @@ -0,0 +1,55 @@ +using System.Globalization; +using Titano.App.Import; +using Titano.Core.Localization; +using Titano.Testing; +using static Titano.App.Tests.Import.CardPoolTests; +using static Titano.App.Tests.Import.ImportPlansTests; + +namespace Titano.App.Tests.Import; + +/// +/// Import texts in a right-to-left language. They switch the process-wide UI language, so the class is serial: in +/// parallel it would race with the English assertions of the classes running beside it. +/// +[Serial] +public sealed class ImportLanguageTests +{ + public ImportLanguageTests() => Loc.SetCulture(CultureInfo.GetCultureInfo("en")); + + [Test] + public void PathsAndSerialsStayLeftToRightInARightToLeftLanguage() + { + try + { + Loc.SetCulture(CultureInfo.GetCultureInfo("he")); + var pool = CardPool.Build([Usb with { Label = string.Empty }, CardA], [], @"D:\Shoots\"); + Assert.Equal("\u202AG:\\\u202C", pool[1].Title, "a drive root keeps its separator at its end"); + Assert.Equal("\u202AD:\\Shoots\\\u202C", pool[2].Title); + Assert.Equal("\u202AD:\\Shoots\\\u202C", pool[2].Subtitle); + Assert.Contains("\u202A3F2A-9C11\u202C", pool[0].IdentityText); + Assert.Equal("EOS_DIGITAL", pool[0].Title, "a label is left to bidi"); + } + finally + { + Loc.SetCulture(CultureInfo.GetCultureInfo("en")); + } + } + + [Test] + public void ARightToLeftLanguageReadsTheSessionTimesWithItsOwnArrow() + { + var plan = ThreeSessions(); + Assert.Contains("→", ImportPlans.Sessions(plan, ImportDestinationKind.Archive, new HashSet())[0].TimeText); + try + { + Loc.SetCulture(CultureInfo.GetCultureInfo("he")); + var time = ImportPlans.Sessions(plan, ImportDestinationKind.Archive, new HashSet())[0].TimeText; + Assert.Contains("←", time); + Assert.False(time.Contains('→'), "a right-to-left reader would see the arrow point back to the start"); + } + finally + { + Loc.SetCulture(CultureInfo.GetCultureInfo("en")); + } + } +} diff --git a/tests/Titano.App.Tests/Import/ImportPlansTests.cs b/tests/Titano.App.Tests/Import/ImportPlansTests.cs index 4be55830..797c5ab0 100644 --- a/tests/Titano.App.Tests/Import/ImportPlansTests.cs +++ b/tests/Titano.App.Tests/Import/ImportPlansTests.cs @@ -11,7 +11,7 @@ public sealed class ImportPlansTests { public ImportPlansTests() => Loc.SetCulture(CultureInfo.GetCultureInfo("en")); - private static ImportPlan ThreeSessions(long? available = 200_000_000) + internal static ImportPlan ThreeSessions(long? available = 200_000_000) { var duplicate = Guid.CreateVersion7(); return Plan(available, [new ImportProblem("DCIM/100CANON/IMG_0099.CR2", "Access denied")], @@ -140,24 +140,6 @@ public sealed class ImportPlansTests Assert.Equal("Split at IMG_0002.CR2", file.SplitName); } - [Test] - public void ARightToLeftLanguageReadsTheSessionTimesWithItsOwnArrow() - { - var plan = ThreeSessions(); - Assert.Contains("→", ImportPlans.Sessions(plan, ImportDestinationKind.Archive, new HashSet())[0].TimeText); - try - { - Loc.SetCulture(CultureInfo.GetCultureInfo("he")); - var time = ImportPlans.Sessions(plan, ImportDestinationKind.Archive, new HashSet())[0].TimeText; - Assert.Contains("←", time); - Assert.False(time.Contains('→'), "a right-to-left reader would see the arrow point back to the start"); - } - finally - { - Loc.SetCulture(CultureInfo.GetCultureInfo("en")); - } - } - [Test] public void TheNamePreviewShowsTheFirstThreeCopiedFiles() { diff --git a/tests/Titano.App.Tests/Program.cs b/tests/Titano.App.Tests/Program.cs index e4838431..d6dc628f 100644 --- a/tests/Titano.App.Tests/Program.cs +++ b/tests/Titano.App.Tests/Program.cs @@ -1,8 +1,24 @@ +using System.Globalization; +using Titano.Core.Localization; using Titano.Testing; namespace Titano.App.Tests; internal static class TestMain { - public static Task Main(string[] args) => TestRunner.RunAsync(args, typeof(TestMain).Assembly); + public static Task Main(string[] args) + { + // The UI language is process-wide: a test that leaves English outside a serial class races with the English + // assertions of the classes running beside it, so it fails at the switch instead of making another one flaky. + // English comes back before the failure, so the classes beside it never see the other language (switching back + // passes this guard). + Loc.CultureChanged += (_, _) => + { + if (TestContext.Current is not { IsSerial: false } test || Loc.Culture.TwoLetterISOLanguageName == "en") return; + var culture = Loc.Culture.Name; + Loc.SetCulture(CultureInfo.GetCultureInfo("en")); + throw new AssertionException($"{test.TestName} switched the UI language to '{culture}' outside a [Serial] class"); + }; + return TestRunner.RunAsync(args, typeof(TestMain).Assembly); + } } diff --git a/tests/Titano.Core.Tests/Decoding/FrameWindowIsolationTests.cs b/tests/Titano.Core.Tests/Decoding/FrameWindowIsolationTests.cs new file mode 100644 index 00000000..021b643f --- /dev/null +++ b/tests/Titano.Core.Tests/Decoding/FrameWindowIsolationTests.cs @@ -0,0 +1,67 @@ +using Titano.Core.Imaging; +using Titano.Testing; +using static Titano.Core.Tests.Decoding.FrameWindowTests; + +namespace Titano.Core.Tests.Decoding; + +/// +/// cancellation (BRIEF §20.4 cancellation gate). Unobserved task exceptions are counted +/// process-wide, so the class is serial: a faulted task another test left behind would otherwise be blamed on it. +/// +[Serial] +public sealed class FrameWindowIsolationTests(TestContext context) +{ + [Test] + [Timeout(10_000)] + public async Task CancellationLeavesNoSpillFileAndNoUnobservedErrors() + { + // Faulted tasks the earlier tests left for the finalizer are reported now, before this test starts counting. + GC.Collect(); + GC.WaitForPendingFinalizers(); + var unobserved = 0; + void OnUnobserved(object? sender, UnobservedTaskExceptionEventArgs e) => Interlocked.Increment(ref unobserved); + TaskScheduler.UnobservedTaskException += OnUnobserved; + try + { + var dir = context.CreateTempDirectory(); + var source = new Source(); + string? spill; + using var cts = new CancellationTokenSource(); + var window = new FrameWindow(50, source.Load, new FrameWindowOptions { Behind = 3, Ahead = 2, MemoryBudget = 2 * FrameBytes, SpillDirectory = dir }); + try + { + for (var i = 0; i < 6; i++) + { + window.MoveTo(i); + using var a = await window.GetAsync(i); + if (i > 0) + { + using var b = await window.GetAsync(i - 1); + } + } + spill = window.SpillPath; + Assert.NotNull(spill); + Assert.FileExists(spill!); + source.Delay = TimeSpan.FromSeconds(30); + window.MoveTo(20); + var pending = window.GetAsync(20, cts.Token); + cts.CancelAfter(50); + await Assert.ThrowsAsync(async () => await pending); + } + finally + { + await window.DisposeAsync(); + } + Assert.FileMissing(spill!); + Assert.Equal(0, source.Live()); + await Assert.ThrowsAsync(async () => await window.GetAsync(1)); + } + finally + { + GC.Collect(); + GC.WaitForPendingFinalizers(); + TaskScheduler.UnobservedTaskException -= OnUnobserved; + } + Assert.Equal(0, unobserved); + } +} diff --git a/tests/Titano.Core.Tests/Decoding/FrameWindowTests.cs b/tests/Titano.Core.Tests/Decoding/FrameWindowTests.cs index 06edd17b..1a2305b2 100644 --- a/tests/Titano.Core.Tests/Decoding/FrameWindowTests.cs +++ b/tests/Titano.Core.Tests/Decoding/FrameWindowTests.cs @@ -3,15 +3,15 @@ using Titano.Testing; namespace Titano.Core.Tests.Decoding; -/// : memory bound independent of sequence length, spill round trip, read-ahead, -/// cancellation and deterministic disposal (BRIEF §8.4, §20.4 memory and cancellation gates). +/// : memory bound independent of sequence length, spill round trip, read-ahead and +/// deterministic disposal (BRIEF §8.4, §20.4 memory gate; the cancellation gate is in ). public sealed class FrameWindowTests(TestContext context) { private const int Size = 64; - private const long FrameBytes = Size * Size * 3 * sizeof(float); + internal const long FrameBytes = Size * Size * 3 * sizeof(float); /// Synthetic loader whose frames encode their index; records every buffer it hands out. - private sealed class Source + internal sealed class Source { private readonly List _made = []; public int Loads; @@ -126,57 +126,6 @@ public sealed class FrameWindowTests(TestContext context) Assert.Equal(4, source.Loads); } - [Test] - [Timeout(10_000)] - public async Task CancellationLeavesNoSpillFileAndNoUnobservedErrors() - { - var unobserved = 0; - void OnUnobserved(object? sender, UnobservedTaskExceptionEventArgs e) => Interlocked.Increment(ref unobserved); - TaskScheduler.UnobservedTaskException += OnUnobserved; - try - { - var dir = context.CreateTempDirectory(); - var source = new Source(); - string? spill; - using var cts = new CancellationTokenSource(); - var window = new FrameWindow(50, source.Load, new FrameWindowOptions { Behind = 3, Ahead = 2, MemoryBudget = 2 * FrameBytes, SpillDirectory = dir }); - try - { - for (var i = 0; i < 6; i++) - { - window.MoveTo(i); - using var a = await window.GetAsync(i); - if (i > 0) - { - using var b = await window.GetAsync(i - 1); - } - } - spill = window.SpillPath; - Assert.NotNull(spill); - Assert.FileExists(spill!); - source.Delay = TimeSpan.FromSeconds(30); - window.MoveTo(20); - var pending = window.GetAsync(20, cts.Token); - cts.CancelAfter(50); - await Assert.ThrowsAsync(async () => await pending); - } - finally - { - await window.DisposeAsync(); - } - Assert.FileMissing(spill!); - Assert.Equal(0, source.Live()); - await Assert.ThrowsAsync(async () => await window.GetAsync(1)); - } - finally - { - GC.Collect(); - GC.WaitForPendingFinalizers(); - TaskScheduler.UnobservedTaskException -= OnUnobserved; - } - Assert.Equal(0, unobserved); - } - [Test] public async Task LoaderFailuresSurfaceAndCanBeRetried() { diff --git a/tests/Titano.Core.Tests/Localization/LanguageGuardTests.cs b/tests/Titano.Core.Tests/Localization/LanguageGuardTests.cs new file mode 100644 index 00000000..6d84d20f --- /dev/null +++ b/tests/Titano.Core.Tests/Localization/LanguageGuardTests.cs @@ -0,0 +1,62 @@ +using System.Globalization; +using Titano.Core.Localization; +using Titano.Testing; + +namespace Titano.Core.Tests.Localization; + +/// +/// The guard installs: a test outside a [Serial] class that leaves English fails, and English is +/// back before anything else runs. Serial itself: the fixture it runs switches the language for a moment. +/// +[Serial] +public sealed class LanguageGuardTests +{ + /// A fixture (assembly discovery leaves nested classes out) that runs beside others and switches to Hebrew. + public sealed class SwitchesBesideOthers + { + [Test] + public void Body() + { + Loc.SetCulture(CultureInfo.GetCultureInfo("he")); + Assert.Fail("the switch went through"); + } + } + + [Test] + public async Task ATestBesideOthersThatLeavesEnglishFailsAndEnglishIsBackAtOnce() + { + Loc.SetCulture(CultureInfo.GetCultureInfo("en")); + var cultures = new List(); + void Record(object? sender, EventArgs e) => cultures.Add(Loc.Culture.Name); + Loc.CultureChanged += Record; + try + { + var result = await TestRunner.ExecuteAsync(TestRunner.Discover(typeof(SwitchesBesideOthers)).Single()); + + Assert.Equal(TestOutcome.Failed, result.Outcome); + Assert.Equal(typeof(SwitchesBesideOthers).FullName + ".Body switched the UI language to 'he' outside a [Serial] class", result.Message); + Assert.Equal("en", Loc.Culture.Name); + // The guard runs first and switches back inside the change, so later listeners only ever hear of English. + Assert.SequenceEqual(new[] { "en" }, cultures); + } + finally + { + Loc.CultureChanged -= Record; + Loc.SetCulture(CultureInfo.GetCultureInfo("en")); + } + } + + [Test] + public void ASerialTestMaySwitchTheLanguage() + { + try + { + Loc.SetCulture(CultureInfo.GetCultureInfo("he")); + Assert.Equal("he", Loc.Culture.Name); + } + finally + { + Loc.SetCulture(CultureInfo.GetCultureInfo("en")); + } + } +} diff --git a/tests/Titano.Core.Tests/Program.cs b/tests/Titano.Core.Tests/Program.cs index 905d7a45..cd6c1560 100644 --- a/tests/Titano.Core.Tests/Program.cs +++ b/tests/Titano.Core.Tests/Program.cs @@ -1,8 +1,24 @@ +using System.Globalization; +using Titano.Core.Localization; using Titano.Testing; namespace Titano.Core.Tests; internal static class TestMain { - public static Task Main(string[] args) => TestRunner.RunAsync(args, typeof(TestMain).Assembly); + public static Task Main(string[] args) + { + // The UI language is process-wide: a test that leaves English outside a serial class races with the English + // assertions of the classes running beside it, so it fails at the switch instead of making another one flaky. + // English comes back before the failure, so the classes beside it never see the other language (switching back + // passes this guard). + Loc.CultureChanged += (_, _) => + { + if (TestContext.Current is not { IsSerial: false } test || Loc.Culture.TwoLetterISOLanguageName == "en") return; + var culture = Loc.Culture.Name; + Loc.SetCulture(CultureInfo.GetCultureInfo("en")); + throw new AssertionException($"{test.TestName} switched the UI language to '{culture}' outside a [Serial] class"); + }; + return TestRunner.RunAsync(args, typeof(TestMain).Assembly); + } } diff --git a/tests/Titano.Core.Tests/Render/RenderIsolationTests.cs b/tests/Titano.Core.Tests/Render/RenderIsolationTests.cs index 50456937..5ac8bf13 100644 --- a/tests/Titano.Core.Tests/Render/RenderIsolationTests.cs +++ b/tests/Titano.Core.Tests/Render/RenderIsolationTests.cs @@ -16,6 +16,9 @@ public sealed class RenderIsolationTests [Test] public async Task FailuresLeaveNoUnobservedTaskExceptions() { + // Faulted tasks the earlier tests left for the finalizer are reported now, before this test starts counting. + GC.Collect(); + GC.WaitForPendingFinalizers(); var unobserved = 0; void Handler(object? sender, UnobservedTaskExceptionEventArgs e) => Interlocked.Increment(ref unobserved); TaskScheduler.UnobservedTaskException += Handler; diff --git a/tests/Titano.Core.Windows.Tests/MediaFoundation/MediaFoundationEncoderTests.cs b/tests/Titano.Core.Windows.Tests/MediaFoundation/MediaFoundationEncoderTests.cs index 7ec92670..41715bb8 100644 --- a/tests/Titano.Core.Windows.Tests/MediaFoundation/MediaFoundationEncoderTests.cs +++ b/tests/Titano.Core.Windows.Tests/MediaFoundation/MediaFoundationEncoderTests.cs @@ -65,6 +65,61 @@ public sealed class MediaFoundationEncoderTests(TestContext context) Assert.Count(1, Directory.GetFiles(dir)); // no temporary file left behind } + /// + /// BRIEF §20.2: what the encoder writes plays in Windows. MediaPlayer (Windows Media Player's pipeline) opens it at + /// the encoded size and length. Where Windows Media Player is missing or unusable (Windows Server, "N" editions) the + /// test is skipped with that reason, and is the check. + /// + [Test] + [WindowsOnly] + [Timeout(120_000)] + public void MediaPlayerOpensTheSoftwareH264Output() + { + RequireEncoder(VideoCodec.H264, hardware: false, tenBit: false); + RequireMediaPlayer(); + var opened = OpenWithMediaPlayer(Encoded("playback.mp4", VideoCodec.H264, 8, hardware: false)); + context.Log($"MediaPlayer: {opened}"); + Assert.Equal(1280, opened.Width); + Assert.Equal(720, opened.Height); + Assert.Approximately(2.0, opened.Duration.TotalSeconds, 0.05); + } + + /// + /// BRIEF §20.2: a Media Foundation source reader decodes the encoder's first frame to the picture that was encoded. + /// It needs no Windows Media Player, so it runs on every Windows with Media Foundation, Server editions included. + /// + [Test] + [WindowsOnly] + [Timeout(60_000)] + public void SourceReaderDecodesTheSoftwareH264Output() + { + RequireEncoder(VideoCodec.H264, hardware: false, tenBit: false); + var frame = Mp4Playback.DecodeFirstFrame(Encoded("decode.mp4", VideoCodec.H264, 8, hardware: false)); + context.Log($"source reader: {frame.Width}×{frame.Height}, {frame.Duration}, luma square {frame.LumaAt(100, 360)}, corner {frame.LumaAt(4, 4)}"); + Assert.Equal(1280, frame.Width); + Assert.Equal(720, frame.Height); + Assert.Approximately(2.0, frame.Duration.TotalSeconds, 0.05); + // Frame 0 as WriteFrames drew it: the white square centred at (100, 360) on a dark blue corner. + Assert.Greater(frame.LumaAt(100, 360), 200); + Assert.Less(frame.LumaAt(4, 4), 60); + } + + /// The hardware HEVC Main10 output opens in MediaPlayer at its size and length, where Windows can decode HEVC. + [Test] + [WindowsOnly] + [Timeout(120_000)] + public void MediaPlayerOpensTheHardwareHevcMain10Output() + { + RequireEncoder(VideoCodec.Hevc, hardware: true, tenBit: true); + RequireMediaPlayer(); + if (!Mp4Playback.HasDecoder(VideoCodec.Hevc)) TestContext.Skip("No HEVC decoder on this machine (HEVC Video Extensions)"); + var opened = OpenWithMediaPlayer(Encoded("main10.mp4", VideoCodec.Hevc, 10, hardware: true)); + context.Log($"MediaPlayer: {opened}"); + Assert.Equal(1280, opened.Width); + Assert.Equal(720, opened.Height); + Assert.Approximately(2.0, opened.Duration.TotalSeconds, 0.05); + } + [Test] [WindowsOnly] [Timeout(60_000)] @@ -139,6 +194,42 @@ public sealed class MediaFoundationEncoderTests(TestContext context) } } + /// Two seconds of (60 frames at 30 fps, 1280×720) in a new temporary file. + private string Encoded(string name, VideoCodec codec, int bitDepth, bool hardware) + { + var settings = Settings(Path.Combine(context.CreateTempDirectory(), name), codec, bitDepth) with { PreferHardware = hardware }; + using (var session = new MediaFoundationEncoderProvider().Open(settings)) + { + Assert.Equal(hardware, session.IsHardware); + context.Log("encoder: " + session.EncoderName); + WriteFrames(session, 60, bitDepth); + session.Complete(); + } + return settings.OutputPath; + } + + /// + /// , skipped when WPF finds Windows Media Player present but unusable + /// (its , "version 10 or later is required"). + /// + private static Mp4Playback.Opened OpenWithMediaPlayer(string path) + { + try + { + return Mp4Playback.OpenWithMediaPlayer(path, TimeSpan.FromSeconds(60)); + } + catch (NotSupportedException ex) + { + TestContext.Skip("Windows Media Player cannot be used: " + ex.Message); + throw; + } + } + + private static void RequireMediaPlayer() + { + if (!Mp4Playback.HasMediaPlayer) TestContext.Skip("Windows Media Player is not installed (Windows Server, \"N\" editions); the source reader test checks playback"); + } + private static void RequireMediaFoundation() { if (!MediaFoundationRuntime.IsAvailable) TestContext.Skip("Media Foundation is not installed (Windows N or Server without Media Foundation)"); diff --git a/tests/Titano.Core.Windows.Tests/MediaFoundation/Mp4Playback.cs b/tests/Titano.Core.Windows.Tests/MediaFoundation/Mp4Playback.cs new file mode 100644 index 00000000..887ffe96 --- /dev/null +++ b/tests/Titano.Core.Windows.Tests/MediaFoundation/Mp4Playback.cs @@ -0,0 +1,289 @@ +using System.Runtime.ExceptionServices; +using System.Runtime.InteropServices; +using System.Runtime.InteropServices.Marshalling; +using System.Windows.Media; +using System.Windows.Threading; +using Titano.Core.Video; +using Titano.Core.Windows.Interop; +using Titano.Core.Windows.MediaFoundation; + +namespace Titano.Core.Windows.Tests.MediaFoundation; + +/// +/// How Windows plays a written MP4 back (BRIEF §20.2): WPF's , which runs on Windows Media +/// Player's pipeline, and a Media Foundation source reader that decodes the first frame, which also works where Windows +/// Media Player is not installed (Windows Server, "N" editions). +/// +internal static partial class Mp4Playback +{ + /// What a player reports once the file is open. + public sealed record Opened(int Width, int Height, TimeSpan Duration); + + /// The first decoded frame: its size, the file's duration and the luma plane (8 bits, top-down, no padding). + public sealed record FirstFrame(int Width, int Height, TimeSpan Duration, byte[] Luma) + { + public byte LumaAt(int x, int y) => Luma[y * Width + x]; + } + + /// True when can work: it needs Windows Media Player (wmp.dll). + public static bool HasMediaPlayer + { + get + { + if (!NativeLibrary.TryLoad("wmp.dll", out var handle)) return false; + NativeLibrary.Free(handle); + return true; + } + } + + /// + /// True when Media Foundation has a decoder for : always for H.264, only with the HEVC Video + /// Extensions for HEVC, which MediaPlayer needs as much as the source reader does. + /// + public static unsafe bool HasDecoder(VideoCodec codec) + { + using var runtime = MediaFoundationRuntime.Acquire(); + var input = new MftRegisterTypeInfo { MajorType = MfGuids.MediaTypeVideo, Subtype = MediaFoundationEncoders.Subtype(codec) }; + const uint flags = MfNative.EnumHardware | MfNative.EnumAsync | MfNative.EnumSync | MfNative.EnumSortAndFilter; + if (MfNative.MFTEnumEx(VideoDecoderCategory, flags, &input, null, out var array, out var count) < 0) return false; + try + { + for (var i = 0; i < count; i++) Marshal.Release(Marshal.ReadIntPtr(array, i * IntPtr.Size)); + } + finally + { + Marshal.FreeCoTaskMem(array); + } + return count > 0; + } + + /// + /// Opens with on its own dispatcher thread and returns what it + /// reports at . Throws, on the calling thread, when it raises + /// , when neither event comes within , and with WPF's + /// own exception when the player cannot be made or opened at all (a where Windows + /// Media Player 10 or later is not usable): nothing escapes the dispatcher thread, where it would end the test program. + /// + public static Opened OpenWithMediaPlayer(string path, TimeSpan timeout) + { + Opened? opened = null; + Exception? failure = null; + var thread = new Thread(() => + { + var dispatcher = Dispatcher.CurrentDispatcher; + MediaPlayer? player = null; + DispatcherTimer? deadline = null; + var finished = false; + // The first outcome counts; the player is closed and the dispatcher stopped once. + void Finish(Opened? result, Exception? error) + { + if (finished) return; + finished = true; + (opened, failure) = (result, error); + deadline?.Stop(); + try + { + player?.Close(); + } + catch (Exception ex) + { + failure ??= ex; + } + dispatcher.InvokeShutdown(); + } + try + { + player = new MediaPlayer(); + player.MediaOpened += (_, _) => + { + // A handler that threw would leave Dispatcher.Run with the player still open. + try + { + Finish(new Opened(player.NaturalVideoWidth, player.NaturalVideoHeight, + player.NaturalDuration.HasTimeSpan ? player.NaturalDuration.TimeSpan : TimeSpan.Zero), null); + } + catch (Exception ex) + { + Finish(null, ex); + } + }; + player.MediaFailed += (_, e) => + Finish(null, new InvalidDataException($"MediaPlayer could not open '{path}': {e.ErrorException?.Message}", e.ErrorException)); + // This constructor starts the timer. + deadline = new DispatcherTimer(timeout, DispatcherPriority.Normal, (_, _) => + Finish(null, new TimeoutException($"MediaPlayer neither opened nor failed on '{path}' within {timeout.TotalSeconds:0} s")), dispatcher); + player.Open(new Uri(path, UriKind.Absolute)); + Dispatcher.Run(); + } + catch (Exception ex) + { + if (finished) failure ??= ex; + else Finish(null, ex); + } + }) + { + IsBackground = true, + Name = "MediaPlayer check", + }; + thread.SetApartmentState(ApartmentState.STA); + thread.Start(); + thread.Join(); + // Rethrown with the dispatcher thread's stack trace and its own type: a NotSupportedException stays one. + if (failure is not null) ExceptionDispatchInfo.Throw(failure); + return opened ?? throw new InvalidOperationException("MediaPlayer stopped without a result"); + } + + /// Decodes the first video frame of to NV12 with a Media Foundation source reader. + public static unsafe FirstFrame DecodeFirstFrame(string path) + { + using var runtime = MediaFoundationRuntime.Acquire(); + ComObjects.Check(MFCreateSourceReaderFromURL(path, 0, out var readerPointer), "MFCreateSourceReaderFromURL"); + var reader = ComObjects.Attach(readerPointer); + try + { + var duration = TimeSpan.Zero; + var variant = stackalloc byte[PropVariantSize]; + new Span(variant, PropVariantSize).Clear(); + if (reader.GetPresentationAttribute(MediaSource, PresentationDuration, (nint)variant) >= 0) + { + if (*(ushort*)variant == VtUi8) duration = TimeSpan.FromTicks((long)*(ulong*)(variant + 8)); + PropVariantClear((nint)variant); + } + + // The reader inserts the H.264/HEVC decoder itself once NV12 is asked for. + ComObjects.Check(MfNative.MFCreateMediaType(out var typePointer), "MFCreateMediaType"); + var type = ComObjects.Attach(typePointer); + try + { + ComObjects.Check(type.SetGUID(MfGuids.MajorType, MfGuids.MediaTypeVideo), "MF_MT_MAJOR_TYPE"); + ComObjects.Check(type.SetGUID(MfGuids.Subtype, MfGuids.FormatNv12), "MF_MT_SUBTYPE"); + var native = ComObjects.GetPointer(type); + try + { + ComObjects.Check(reader.SetCurrentMediaType(FirstVideoStream, 0, native), "SetCurrentMediaType(NV12)"); + } + finally + { + Marshal.Release(native); + } + } + finally + { + ComObjects.Release(type); + } + + var sample = ReadFirstSample(reader); + try + { + ComObjects.Check(reader.GetCurrentMediaType(FirstVideoStream, out var currentPointer), "GetCurrentMediaType"); + var current = ComObjects.Attach(currentPointer); + ulong size; + try + { + ComObjects.Check(current.GetUINT64(MfGuids.FrameSize, out size), "MF_MT_FRAME_SIZE"); + } + finally + { + ComObjects.Release(current); + } + var (width, height) = ((int)(size >> 32), (int)(size & 0xFFFF_FFFF)); + return new FirstFrame(width, height, duration, CopyLuma(sample, width, height)); + } + finally + { + ComObjects.Release(sample); + } + } + finally + { + ComObjects.Release(reader); + } + } + + /// Reads until the first video sample; stream ticks and format changes come without one. + private static IMFSample ReadFirstSample(IMFSourceReader reader) + { + for (var attempt = 0; attempt < 100; attempt++) + { + ComObjects.Check(reader.ReadSample(FirstVideoStream, 0, out _, out var flags, out _, out var samplePointer), "ReadSample"); + if (samplePointer != 0) return ComObjects.Attach(samplePointer); + if ((flags & (ReaderError | ReaderEndOfStream)) != 0) throw new InvalidDataException($"The source reader returned no frame (flags 0x{flags:X})"); + } + throw new InvalidDataException("The source reader returned no frame in 100 reads"); + } + + /// Copies the Y plane out of the sample's buffer, honouring the decoder's row pitch. + private static unsafe byte[] CopyLuma(IMFSample sample, int width, int height) + { + ComObjects.Check(sample.ConvertToContiguousBuffer(out var bufferPointer), "ConvertToContiguousBuffer"); + var buffer = ComObjects.Attach(bufferPointer); + try + { + var luma = new byte[width * height]; + if (buffer is IMF2DBuffer twoD && twoD.Lock2D(out var scanline0, out var pitch) >= 0) + { + try + { + for (var y = 0; y < height; y++) new ReadOnlySpan((byte*)scanline0 + (long)y * pitch, width).CopyTo(luma.AsSpan(y * width)); + } + finally + { + twoD.Unlock2D(); + } + return luma; + } + ComObjects.Check(buffer.Lock(out var data, out _, out var length), "IMFMediaBuffer.Lock"); + try + { + // A contiguous NV12 frame: the Y rows, then half as many interleaved chroma rows, all of one pitch. + var stride = (int)(length / (uint)(height + height / 2)); + if (stride < width) throw new InvalidDataException($"An NV12 buffer of {length} bytes is too small for {width}×{height}"); + for (var y = 0; y < height; y++) new ReadOnlySpan((byte*)data + (long)y * stride, width).CopyTo(luma.AsSpan(y * width)); + return luma; + } + finally + { + buffer.Unlock(); + } + } + finally + { + ComObjects.Release(buffer); + } + } + + private const uint FirstVideoStream = 0xFFFF_FFFC; // MF_SOURCE_READER_FIRST_VIDEO_STREAM + private const uint MediaSource = 0xFFFF_FFFF; // MF_SOURCE_READER_MEDIASOURCE + private const uint ReaderError = 0x1, ReaderEndOfStream = 0x2; // MF_SOURCE_READERF_ERROR, _ENDOFSTREAM + private const ushort VtUi8 = 21; + private const int PropVariantSize = 24; // PROPVARIANT on 64-bit Windows + + /// MFT_CATEGORY_VIDEO_DECODER. + private static readonly Guid VideoDecoderCategory = new("d6c02d4b-6833-45b4-971a-05a4b04bab91"); + + /// MF_PD_DURATION: the presentation's length in 100 ns units. + private static readonly Guid PresentationDuration = new("6c990d33-bb8e-477a-8598-0d5d96fcd88a"); + + [LibraryImport("mfreadwrite.dll", StringMarshalling = StringMarshalling.Utf16)] + private static partial int MFCreateSourceReaderFromURL(string url, nint attributes, out nint reader); + + [LibraryImport("ole32.dll")] + private static partial int PropVariantClear(nint variant); +} + +/// IMFSourceReader (mfreadwrite.h) in vtable order. +[GeneratedComInterface] +[Guid("70ae66f2-c809-4e4f-8915-bdcb406b7993")] +internal partial interface IMFSourceReader +{ + [PreserveSig] int GetStreamSelection(uint streamIndex, out int selected); + [PreserveSig] int SetStreamSelection(uint streamIndex, int selected); + [PreserveSig] int GetNativeMediaType(uint streamIndex, uint mediaTypeIndex, out nint mediaType); + [PreserveSig] int GetCurrentMediaType(uint streamIndex, out nint mediaType); + [PreserveSig] int SetCurrentMediaType(uint streamIndex, nint reserved, nint mediaType); + [PreserveSig] int SetCurrentPosition(in Guid timeFormat, nint position); + [PreserveSig] int ReadSample(uint streamIndex, uint controlFlags, out uint actualStreamIndex, out uint streamFlags, out long timestamp, out nint sample); + [PreserveSig] int Flush(uint streamIndex); + [PreserveSig] int GetServiceForStream(uint streamIndex, in Guid service, in Guid iid, out nint instance); + [PreserveSig] int GetPresentationAttribute(uint streamIndex, in Guid attribute, nint value); +} diff --git a/tests/Titano.Core.Windows.Tests/Titano.Core.Windows.Tests.csproj b/tests/Titano.Core.Windows.Tests/Titano.Core.Windows.Tests.csproj index 0da39c1c..62d597f6 100644 --- a/tests/Titano.Core.Windows.Tests/Titano.Core.Windows.Tests.csproj +++ b/tests/Titano.Core.Windows.Tests/Titano.Core.Windows.Tests.csproj @@ -4,6 +4,10 @@ net10.0-windows Titano.Core.Windows.Tests + + + + diff --git a/tests/Titano.Data.Tests/Infrastructure/DatabaseTest.cs b/tests/Titano.Data.Tests/Infrastructure/DatabaseTest.cs index cb2a015f..8566872e 100644 --- a/tests/Titano.Data.Tests/Infrastructure/DatabaseTest.cs +++ b/tests/Titano.Data.Tests/Infrastructure/DatabaseTest.cs @@ -29,6 +29,11 @@ internal static class PgTestServer public static string Optional(string variable) => Environment.GetEnvironmentVariable(variable) is { Length: > 0 } cs ? cs : throw new SkipException($"{variable} not set"); + /// Set to 1 where the server was set up with TLS (CI): a server that refuses TLS then fails the TLS tests. + public const string TlsVariable = "TITANO_TEST_PG_TLS"; + + public static bool TlsExpected => Environment.GetEnvironmentVariable(TlsVariable) is "1" or "true"; + public static async Task CreateSchemaAsync(CancellationToken cancellationToken) { var name = "titano_t_" + Guid.NewGuid().ToString("N")[..16]; diff --git a/tests/Titano.Data.Tests/Postgres/PgWireTests.cs b/tests/Titano.Data.Tests/Postgres/PgWireTests.cs index 132c549b..c6552862 100644 --- a/tests/Titano.Data.Tests/Postgres/PgWireTests.cs +++ b/tests/Titano.Data.Tests/Postgres/PgWireTests.cs @@ -1,4 +1,5 @@ using System.Diagnostics; +using System.Diagnostics.CodeAnalysis; using System.Security.Authentication; using Titano.Data.Postgres; using Titano.Data.Tests.Infrastructure; @@ -6,7 +7,11 @@ using Titano.Testing; namespace Titano.Data.Tests.Postgres; -/// Protocol-level tests against a live server (TITANO_TEST_PG; optional TITANO_TEST_PG_MD5/_CLEARTEXT/_TRUST). +/// +/// Protocol-level tests against a live server (TITANO_TEST_PG). Optional: TITANO_TEST_PG_MD5/_CLEARTEXT/_TRUST (roles +/// of the other authentication methods), TITANO_TEST_PG_TLS=1 (the server offers TLS) and TITANO_TEST_PG_ROOT_CERT (the +/// PEM its certificate chains to). CI sets them all up (.github/scripts/postgres-ci-setup.sh). +/// [RequiresEnvironment(PgTestServer.Variable)] public sealed class PgWireTests(TestContext context) : DatabaseTest(context) { @@ -15,6 +20,14 @@ public sealed class PgWireTests(TestContext context) : DatabaseTest(context) private async Task OpenAsync(string? extra = null) => (PostgresDatabase)Own(DatabaseFactory.Open(await NewOptionsAsync(extraPostgres: extra))); + /// A server without TLS skips the TLS tests, unless it was set up with TLS (). + [DoesNotReturn] + private static void WithoutTls(DatabaseConnectionException refusal) + { + if (PgTestServer.TlsExpected) Assert.Fail($"{PgTestServer.TlsVariable} says the server offers TLS, but it refused: {refusal.Message}"); + TestContext.Skip("server has no TLS"); + } + private async Task AuthenticateAsync(string connectionString) { var database = Own(new PostgresDatabase(PostgresSettings.Parse(connectionString))); @@ -61,7 +74,7 @@ public sealed class PgWireTests(TestContext context) : DatabaseTest(context) } catch (DatabaseConnectionException ex) when (ex.Message.Contains("does not support TLS", StringComparison.Ordinal)) { - TestContext.Skip("server has no TLS"); + WithoutTls(ex); return; } await using var session = await database.OpenAsync(Ct); @@ -83,13 +96,22 @@ public sealed class PgWireTests(TestContext context) : DatabaseTest(context) } catch (DatabaseConnectionException ex) when (ex.Message.Contains("does not support TLS", StringComparison.Ordinal)) { - TestContext.Skip("server has no TLS"); + WithoutTls(ex); } catch (AuthenticationException) { } } + [Test] + public async Task VerifyFullAcceptsACertificateThatChainsToTheConfiguredRoot() + { + var root = PgTestServer.Optional("TITANO_TEST_PG_ROOT_CERT"); + var database = await OpenAsync($"SslMode=VerifyFull;Root Certificate={root}"); + await using var session = await database.OpenAsync(Ct); + Assert.True(await session.ScalarAsync("SELECT ssl FROM pg_stat_ssl WHERE pid = pg_backend_pid()", [], Ct)); + } + [Test] public async Task DecodesEveryMappedResultType() { diff --git a/tests/Titano.Testing/TestContext.cs b/tests/Titano.Testing/TestContext.cs index 3c31cc3d..d5fcb401 100644 --- a/tests/Titano.Testing/TestContext.cs +++ b/tests/Titano.Testing/TestContext.cs @@ -9,18 +9,33 @@ namespace Titano.Testing; /// public sealed class TestContext : IDisposable { + private static readonly AsyncLocal CurrentTest = new(); private readonly ConcurrentQueue _log = new(); private readonly List _tempDirectories = []; private readonly Lock _gate = new(); - internal TestContext(string testName, CancellationToken cancellation) + internal TestContext(string testName, bool isSerial, CancellationToken cancellation) { TestName = testName; + IsSerial = isSerial; Cancellation = cancellation; } + /// + /// The test running on this flow of execution (its constructor, body and the tasks it starts); null outside tests. + /// Lets a test program guard process-wide state, which only a serial test may change. + /// + public static TestContext? Current + { + get => CurrentTest.Value; + internal set => CurrentTest.Value = value; + } + public string TestName { get; } + /// True when the test's class is : no other test runs beside it. + public bool IsSerial { get; } + /// Signalled when the test times out or the run is aborted. public CancellationToken Cancellation { get; } diff --git a/tests/Titano.Testing/TestRunner.cs b/tests/Titano.Testing/TestRunner.cs index 3b0576f6..91c18b07 100644 --- a/tests/Titano.Testing/TestRunner.cs +++ b/tests/Titano.Testing/TestRunner.cs @@ -100,30 +100,41 @@ public static class TestRunner } foreach (var type in types.Where(t => t is { IsClass: true, IsPublic: true } && !t.IsAbstract).OrderBy(t => t.FullName, StringComparer.Ordinal)) + list.AddRange(Discover(type)); + return list; + } + + /// + /// The tests of one class, in declaration order. Assembly discovery takes top-level classes only, so a class nested + /// in a test class is a fixture that runs only when a test hands it to . + /// + public static IReadOnlyList Discover(Type type) + { + var list = new List(); + foreach (var method in type.GetMethods(BindingFlags.Public | BindingFlags.Instance | BindingFlags.Static).OrderBy(m => m.MetadataToken)) { - foreach (var method in type.GetMethods(BindingFlags.Public | BindingFlags.Instance | BindingFlags.Static).OrderBy(m => m.MetadataToken)) + if (method.GetCustomAttribute() is not null) { - if (method.GetCustomAttribute() is not null) - { - list.Add(new TestCase(type, method, null, null)); - } - else if (method.GetCustomAttribute() is not null) - { - foreach (var c in method.GetCustomAttributes()) - list.Add(new TestCase(type, method, c.Arguments, c.Name)); - } + list.Add(new TestCase(type, method, null, null)); + } + else if (method.GetCustomAttribute() is not null) + { + foreach (var c in method.GetCustomAttributes()) + list.Add(new TestCase(type, method, c.Arguments, c.Name)); } } return list; } - private static async Task ExecuteAsync(TestCase test) + /// Runs one test (constructor, body, disposal) under its timeout and returns its outcome. + public static async Task ExecuteAsync(TestCase test) { + ArgumentNullException.ThrowIfNull(test); if (test.StaticSkipReason is { } reason) return new TestResult(test, TestOutcome.Skipped, TimeSpan.Zero, reason, null, string.Empty); using var cts = new CancellationTokenSource(); - using var context = new TestContext(test.FullName, cts.Token); + using var context = new TestContext(test.FullName, test.Serial, cts.Token); var sw = Stopwatch.StartNew(); try { @@ -152,29 +163,21 @@ public static class TestRunner private static async Task InvokeAsync(TestCase test, TestContext context) { + TestContext.Current = context; object? instance = null; try { if (!test.Method.IsStatic) { var ctor = test.Type.GetConstructor([typeof(TestContext)]); - instance = ctor is not null + instance = Unwrapped(() => ctor is not null ? ctor.Invoke([context]) - : Activator.CreateInstance(test.Type); + : Activator.CreateInstance(test.Type)); } var parameters = test.Method.GetParameters(); var args = BuildArguments(test, parameters, context); - object? returned; - try - { - returned = test.Method.Invoke(instance, args); - } - catch (TargetInvocationException tie) when (tie.InnerException is not null) - { - ExceptionDispatchInfo.Capture(tie.InnerException).Throw(); - throw; - } + var returned = Unwrapped(() => test.Method.Invoke(instance, args)); switch (returned) { @@ -200,6 +203,23 @@ public static class TestRunner } } + /// + /// Makes a reflection call and rethrows what the constructor or method threw, so a skip stays a skip and a failure + /// carries its own message and stack trace instead of "Exception has been thrown by the target of an invocation". + /// + private static object? Unwrapped(Func call) + { + try + { + return call(); + } + catch (TargetInvocationException tie) when (tie.InnerException is not null) + { + ExceptionDispatchInfo.Capture(tie.InnerException).Throw(); + throw; + } + } + private static object?[] BuildArguments(TestCase test, ParameterInfo[] parameters, TestContext context) { var supplied = test.Arguments ?? []; diff --git a/tests/Titano.Tools.Tests/ScreenshotsCommandTests.cs b/tests/Titano.Tools.Tests/ScreenshotsCommandTests.cs new file mode 100644 index 00000000..626d69fd --- /dev/null +++ b/tests/Titano.Tools.Tests/ScreenshotsCommandTests.cs @@ -0,0 +1,188 @@ +using Titano.Core.Codecs.Png; +using Titano.Testing; +using Titano.Tools.Commands; +using static Titano.Tools.Commands.ScreenshotsCommand; + +namespace Titano.Tools.Tests; + +/// +/// The screenshot diff fails on changed screens and tolerates noise (BRIEF §20.2); a screen without a baseline fails +/// once any baseline exists, and a run before the first baselines says that it compared nothing. +/// +public sealed class ScreenshotsCommandTests(TestContext context) +{ + private const int Size = 100; + + /// A 100×100 RGB screen: a dark background with a light panel, then applied. + private static void WriteScreen(string folder, string name, Action? change = null, int width = Size, int height = Size) + { + var pixels = new byte[width * height * 3]; + for (var y = 0; y < height; y++) + { + for (var x = 0; x < width; x++) + { + var v = (byte)(x is >= 20 and < 80 && y is >= 30 and < 60 ? 230 : 32); + pixels[(y * width + x) * 3] = pixels[(y * width + x) * 3 + 1] = pixels[(y * width + x) * 3 + 2] = v; + } + } + change?.Invoke(pixels); + File.WriteAllBytes(Path.Combine(folder, name), PngEncoder.Encode(pixels, width, height, PngColorType.Rgb)); + } + + /// Adds to the red channel of the first pixels. + private static Action Shift(int count, int delta) => pixels => + { + for (var i = 0; i < count; i++) pixels[i * 3] = (byte)(pixels[i * 3] + delta); + }; + + private (string Captured, string Baseline, string Output) Folders() + { + var root = context.CreateTempDirectory(); + var folders = (Path.Combine(root, "screenshots"), Path.Combine(root, "baselines"), Path.Combine(root, "diff")); + Directory.CreateDirectory(folders.Item1); + Directory.CreateDirectory(folders.Item2); + return folders; + } + + private static DiffReport Run(string captured, string baseline, string output, StringWriter log, int tolerance = DefaultTolerance, double maxDiff = DefaultMaxDiff) => + ScreenshotsCommand.Diff(new DiffOptions(captured, baseline, output, tolerance, maxDiff), log, annotate: true, stepSummary: null); + + [Test] + public void ChangedScreensFailAndNoiseWithinTheToleranceDoesNot() + { + var (captured, baseline, output) = Folders(); + foreach (var name in new[] { "library-dark.png", "jobs-dark.png", "about-dark.png", "server-dark.png" }) WriteScreen(baseline, name); + WriteScreen(captured, "library-dark.png"); + // Every pixel a little off: anti-aliasing noise below the per-channel tolerance. + WriteScreen(captured, "jobs-dark.png", Shift(Size * Size, DefaultTolerance)); + // Four pixels clearly off: 0.04 % of the screen, under the 0.05 % allowed. + WriteScreen(captured, "about-dark.png", Shift(4, 100)); + // A whole row moved: 1 % of the screen. + WriteScreen(captured, "server-dark.png", Shift(Size, 100)); + + using var log = new StringWriter(); + var report = Run(captured, baseline, output, log); + + Assert.True(report.Fails); + Assert.SequenceEqual(new[] { Verdict.Within, Verdict.Same, Verdict.Same, Verdict.Changed }, report.Screens.Select(s => s.Verdict)); + Assert.SequenceEqual(new[] { "about-dark.png", "jobs-dark.png", "library-dark.png", "server-dark.png" }, report.Screens.Select(s => s.Name)); + Assert.Equal(Size, report.Screens[3].Differing); + Assert.FileExists(Path.Combine(output, "server-dark-diff.png")); + Assert.FileExists(Path.Combine(output, "about-dark-diff.png")); + Assert.FileMissing(Path.Combine(output, "library-dark-diff.png")); + Assert.Contains("::error title=Screenshot changed::server-dark.png: 1 %25 of the pixels differ (100; limit 0.05 %25)", log.ToString()); + Assert.Contains("| server-dark.png | changed | 1 % of the pixels differ (100; limit 0.05 %) |", File.ReadAllText(Path.Combine(output, "summary.md"))); + } + + [Test] + public void TheDiffImageShowsTheDifferingPixelsInMagentaOverTheFadedBaseline() + { + var (captured, baseline, output) = Folders(); + WriteScreen(baseline, "a.png"); + WriteScreen(captured, "a.png", Shift(Size, 100)); + using var log = new StringWriter(); + Run(captured, baseline, output, log); + + var diff = ScreenshotsCommand.Read(Path.Combine(output, "a-diff.png")); + Assert.Equal(Size, diff.Width); + Assert.SequenceEqual(new byte[] { 255, 0, 255, 255 }, diff.Pixels[..4], "a differing pixel"); + var panel = ((40 * Size) + 50) * 4; + var background = ((90 * Size) + 50) * 4; + Assert.Greater(diff.Pixels[panel], diff.Pixels[background], "the baseline's light panel stays lighter than its background"); + Assert.InRange(diff.Pixels[background], 112, 207); + } + + [Test] + public void BeforeTheFirstBaselinesTheRunWarnsThatItComparedNothing() + { + var (captured, baseline, output) = Folders(); + WriteScreen(captured, "welcome-dark.png"); + WriteScreen(captured, "about-dark.png"); + // A README is not a baseline: the folder as committed before the first screens are accepted. + File.WriteAllText(Path.Combine(baseline, "README.md"), "# Screenshot baselines"); + foreach (var folder in new[] { baseline, Path.Combine(baseline, "not-there") }) + { + using var log = new StringWriter(); + var report = Run(captured, folder, output, log); + + Assert.False(report.Fails); + Assert.False(report.Armed); + Assert.True(report.Screens.All(s => s.Verdict == Verdict.New)); + Assert.Contains("::warning title=No screenshot baselines::The baseline folder holds no PNG: nothing was compared, and no visual change can fail " + + "this step until baselines are committed. 2 screenshot(s) without a baseline (about-dark.png, welcome-dark.png);", log.ToString()); + Assert.False(log.ToString().Contains("::error", StringComparison.Ordinal)); + Assert.Contains("0 compared", log.ToString()); + Assert.Contains("**The baseline folder holds no PNG: nothing was compared", File.ReadAllText(Path.Combine(output, "summary.md"))); + } + } + + [Test] + public void OnceAnyBaselineExistsAScreenWithoutOneFails() + { + var (captured, baseline, output) = Folders(); + WriteScreen(baseline, "library-dark.png"); + WriteScreen(captured, "library-dark.png"); + // A screen added after the baselines were committed, whose baseline nobody accepted. + WriteScreen(captured, "library-new-dark.png"); + using var log = new StringWriter(); + var report = Run(captured, baseline, output, log); + + Assert.True(report.Armed); + Assert.True(report.Fails); + Assert.SequenceEqual(new[] { Verdict.Same, Verdict.Unbased }, report.Screens.Select(s => s.Verdict)); + Assert.Contains("::error title=Screenshot without baseline::library-new-dark.png: no baseline, while other screens have one (screenshots accept adds it)", log.ToString()); + Assert.False(log.ToString().Contains("::warning", StringComparison.Ordinal), "the not-compared warning belongs to a run before the first baselines"); + Assert.Contains("1 compared: 1 within tolerance, 0 changed; 1 without a baseline; 0 missing.", log.ToString()); + Assert.False(File.ReadAllText(Path.Combine(output, "summary.md")).Contains("holds no PNG", StringComparison.Ordinal)); + } + + [Test] + public void AResizedScreenAndABaselineWithoutItsScreenFail() + { + var (captured, baseline, output) = Folders(); + WriteScreen(baseline, "settings-dark.png"); + WriteScreen(baseline, "setup-failed-dark.png"); + WriteScreen(captured, "settings-dark.png", width: Size + 1); + using var log = new StringWriter(); + var report = Run(captured, baseline, output, log); + + Assert.SequenceEqual(new[] { Verdict.Resized, Verdict.Missing }, report.Screens.Select(s => s.Verdict)); + Assert.True(report.Screens.All(s => s.Fails)); + Assert.Contains("settings-dark.png: 101×100, baseline 100×100", log.ToString()); + } + + [Test] + public void ThePerChannelToleranceIsInclusive() + { + var expected = new Picture(2, 1, [10, 10, 10, 255, 10, 10, 10, 255]); + var actual = new Picture(2, 1, [18, 10, 10, 255, 10, 10, 10, 247]); + Assert.Equal(0L, ScreenshotsCommand.Compare(expected, actual, tolerance: 8).Differing); + Assert.Equal(2L, ScreenshotsCommand.Compare(expected, actual, tolerance: 7).Differing, "alpha counts like a colour"); + } + + [Test] + public void TheCommandExitsWithOneOnAChangeAndAcceptCopiesTheBaselines() + { + var (captured, baseline, output) = Folders(); + WriteScreen(baseline, "a.png"); + WriteScreen(captured, "a.png", Shift(Size * 2, 120)); + WriteScreen(captured, "b.png"); + using var log = new StringWriter(); + int Run(params string[] args) => ScreenshotsCommand.Run(args, _ => null, log); + + Assert.Equal(1, Run("diff", captured, "--baseline", baseline, "--out", output, "--tolerance", "8", "--max-diff", "0.001")); + // a.png is now within the limit, but b.png still has no baseline beside a.png's. + Assert.Equal(1, Run("diff", captured, "--baseline", baseline, "--out", output, "--max-diff", "0.05")); + Assert.FileExists(Path.Combine(output, "a-diff.png")); + File.Copy(Path.Combine(captured, "b.png"), Path.Combine(baseline, "b.png")); + Assert.Equal(0, Run("diff", captured, "--baseline", baseline, "--out", output, "--max-diff", "0.05")); + Assert.Equal(0, Run("accept", captured, "--baseline", baseline)); + Assert.FileExists(Path.Combine(baseline, "b.png")); + Assert.Equal(0, Run("diff", captured, "--baseline", baseline, "--out", output)); + // The diff of the earlier run is removed with the change it showed. + Assert.FileMissing(Path.Combine(output, "a-diff.png")); + Assert.False(log.ToString().Contains("::", StringComparison.Ordinal), "no workflow commands outside GitHub Actions"); + Assert.Throws(() => Run("diff", captured, "--baseline", baseline, "--tolerance", "300")); + Assert.Throws(() => Run("compare", captured)); + } +} diff --git a/tests/Titano.Tools.Tests/TestRunnerTests.cs b/tests/Titano.Tools.Tests/TestRunnerTests.cs new file mode 100644 index 00000000..3328d6fe --- /dev/null +++ b/tests/Titano.Tools.Tests/TestRunnerTests.cs @@ -0,0 +1,102 @@ +using Titano.Testing; + +namespace Titano.Tools.Tests; + +/// +/// The in-house runner reports what a test class did, not how reflection called it (BRIEF §20.1). The nested classes +/// are fixtures: assembly discovery leaves them out, and each test hands one to the runner. +/// +public sealed class TestRunnerTests(TestContext context) +{ + public sealed class SkippingConstructor + { + public SkippingConstructor() => TestContext.Skip("no server configured"); + + [Test] + public void Body() => Assert.Fail("the body ran after the constructor skipped"); + } + + public sealed class FailingConstructor + { + public FailingConstructor(TestContext context) => Assert.Fail($"{context.TestName} could not start its fixture"); + + [Test] + public void Body() => Assert.Fail("the body ran after the constructor failed"); + } + + public sealed class ThrowingFieldInitializer + { + private readonly string _root = Environment.GetEnvironmentVariable("TITANO_NO_SUCH_VARIABLE") ?? throw new InvalidOperationException("no root folder"); + + [Test] + public void Body() => Assert.Fail("the body ran with " + _root); + } + + public sealed class BesideOthers + { + [Test] + public async Task SeesItsOwnContext(TestContext context) + { + Assert.Same(context, TestContext.Current); + Assert.False(context.IsSerial); + await Task.Yield(); + Assert.Same(context, await Task.Run(() => TestContext.Current)); + } + } + + [Serial] + public sealed class Alone + { + [Test] + public void KnowsItRunsAlone(TestContext context) => Assert.True(context.IsSerial && TestContext.Current == context); + } + + private static async Task RunAsync() + { + var test = TestRunner.Discover(typeof(T)).Single(); + return await TestRunner.ExecuteAsync(test); + } + + [Test] + public void NestedFixturesAreNotDiscoveredWithTheAssembly() + { + var names = TestRunner.Discover(typeof(TestRunnerTests).Assembly).Select(t => t.FullName).ToList(); + Assert.Contains(typeof(TestRunnerTests).FullName + "." + nameof(NestedFixturesAreNotDiscoveredWithTheAssembly), names); + Assert.False(names.Any(n => n.Contains('+', StringComparison.Ordinal)), "a nested class would run as a real test"); + } + + [Test] + public async Task ASkipInTheConstructorSkipsTheTest() + { + var result = await RunAsync(); + Assert.Equal(TestOutcome.Skipped, result.Outcome); + Assert.Equal("no server configured", result.Message); + } + + [Test] + public async Task AFailureInTheConstructorKeepsItsMessage() + { + var result = await RunAsync(); + Assert.Equal(TestOutcome.Failed, result.Outcome); + Assert.Equal(typeof(FailingConstructor).FullName + ".Body could not start its fixture", result.Message); + Assert.Contains(nameof(FailingConstructor), result.StackTrace); + } + + [Test] + public async Task AnExceptionInAFieldInitializerIsReportedAsItself() + { + var result = await RunAsync(); + Assert.Equal(TestOutcome.Failed, result.Outcome); + Assert.Equal("System.InvalidOperationException: no root folder", result.Message); + } + + [Test] + public async Task TheCurrentContextFollowsEachTestAndItsTasks() + { + var parallel = await RunAsync(); + Assert.Equal(TestOutcome.Passed, parallel.Outcome, parallel.Message); + var alone = await RunAsync(); + Assert.Equal(TestOutcome.Passed, alone.Outcome, alone.Message); + Assert.Same(context, TestContext.Current); + } +} diff --git a/tests/visual/baselines/README.md b/tests/visual/baselines/README.md new file mode 100644 index 00000000..7ac9013f --- /dev/null +++ b/tests/visual/baselines/README.md @@ -0,0 +1,52 @@ +# Screenshot baselines + +The approved look of every screen, one PNG per `--capture` screenshot (`-.png`, as `Titano.exe`, +`Titano.Uploader.exe` and `Titano.Setup.exe --capture ` write them). CI compares each new screenshot with the +file of the same name here (BRIEF §20.2, visual regression with a pixel-diff tolerance): + +``` +dotnet run --project src/Titano.Tools -- screenshots diff out/screenshots --out out/screenshot-diff +``` + +- A pixel differs when one of its channels moves by more than `--tolerance` (default 8 of 255); a screen fails when + more than `--max-diff` of its pixels differ (default 0.0005, that is 0.05 %), when its size changed, or when a + baseline here has no screenshot any more. +- A screenshot without a baseline fails as soon as this folder holds any PNG: a pull request that adds a screen adds its + baselines too. +- While this folder holds no PNG nothing is compared: the step passes, with a warning and a bold line in the job summary + saying that no visual change can fail it. +- `out/screenshot-diff` gets `-diff.png` for every screen with differing pixels (the baseline faded to grey, the + differences magenta) and `summary.md`; CI uploads them as the `screenshot-diff` artifact and adds the summary to the + job page. + +## The pictures are reproducible + +The capture runs on sample data whose clock stands at `SampleData.Now` (2026-10-02 10:18 UTC), in English with English +formats and with animations off, so the same code draws the same pixels on any day. Two things still come from the +machine: + +- the time zone: times are shown in local time, and the baselines are made on the CI runner (`windows-latest`, UTC); +- a few measured values: the server's response time and the time and duration of the last sync comparison. They change + a few dozen pixels, well inside the allowed fraction. + +## Adding or updating baselines + +Take them from CI, never from a local run (fonts, scaling and the time zone differ). Every same-repository pull request +pushes its screenshots to the `ci-screenshots` branch (one commit, the PNGs at its root). After checking them: + +``` +git fetch origin ci-screenshots +git worktree add ../ci-screenshots origin/ci-screenshots +dotnet run --project src/Titano.Tools -- screenshots accept ../ci-screenshots +git worktree remove ../ci-screenshots +``` + +`screenshots accept ` copies every PNG of `` here. Commit only the screens whose change is intended, and delete +the baseline of a screen that no longer exists. + +## The first baselines + +None is committed yet. Screenshots captured before the capture was made reproducible cannot serve: their times and +dates follow the moment they were taken (a job finished at "12:18 AM", sample sequences dated from that day). The first +baselines are accepted, all at once, from the `ci-screenshots` commit of the first green `windows-latest` run whose +code captures at `SampleData.Now`; from that commit on, every screen is gated.