AutoForge/docs/build-and-test.md

375 lines
22 KiB
Markdown

# Build and test
## Prerequisites
- Windows x64, .NET SDK 10.0.402 with its approved .NET 10 patch roll-forward.
- Windows SDK target 10.0.26100.0 and MAUI Windows workload manifest 10.0.110.
- Microsoft Edge WebView2 Runtime to launch the native Blazor Hybrid Client.
The previously verified environment reported runtime 10.0.13, MAUI workload
version 10.0.403 as listed by the installed SDK, and WebView2 Runtime
155.0.4283.62. The Client targets `net10.0-windows10.0.26100.0` and `win-x64`.
All other projects target portable `net10.0`; tests do not require MAUI or
WebView2.
## Restore, build, test and launch
From the repository root in PowerShell, run the full build and both suites
sequentially:
```powershell
dotnet restore .\src\AutoForge.slnx
dotnet build .\src\AutoForge.slnx --configuration Release --no-restore
dotnet test .\src\AutoForge.slnx --configuration Release --no-build
dotnet run --project .\src\AutoForge.Client\AutoForge.Client.csproj --configuration Release --framework net10.0-windows10.0.26100.0
```
The build includes the actual native Client and all nine solution projects.
For an explicit Windows runtime pack restore or direct native build:
```powershell
dotnet restore .\src\AutoForge.Client\AutoForge.Client.csproj --runtime win-x64
dotnet build .\src\AutoForge.Client\AutoForge.Client.csproj --configuration Release --framework net10.0-windows10.0.26100.0 --no-restore
```
Do not pass Windows TFM overrides to the portable test projects. The Client
contains the real UI RCL in a native MAUI BlazorWebView. No automotive driver,
actual vehicle, database, backend, model or cloud account is required.
## Focused tests
```powershell
dotnet test .\src\tests\AutoForge.UnitTests\AutoForge.UnitTests.csproj --configuration Release
dotnet test .\src\tests\AutoForge.IntegrationTests\AutoForge.IntegrationTests.csproj --configuration Release
```
The unit suite covers existing Core/Application behavior, rendered generic
components, profile invariants and strict codec behavior, plus protocol v1
round-trip/snapshot contracts and bounded trace behavior. The integration suite
loads source-controlled profile fixtures through real DI, opens actual
simulation sessions, sends/decodes requests through the transport, verifies
identity/DTC/static signals, virtual clear/readback/reset and independent
session state, exercises deterministic malformed/no-response/timeout/cancelled
faults, renders the diagnostic route against the actual provider, and checks
the nine-project reference graph. Fixtures are never treated as real vehicle
definitions. The internal state oracle is exposed only to the integration-test
assembly.
The accepted Step-02A baseline was 103 unit plus 37 integration tests (140
total). The Step-03 worker report records the full, expanded counts, warnings,
commands and native observations; do not infer acceptance from these earlier
runs. Historical Step-02 had 59 unit and 34 integration cases; it predates the
Step-02A corrections. See the [Step-02 report](../prompts/Step-02-Report.md) and
[Step-02A report](../prompts/Step-02A-Report.md) for historical evidence.
Step-03 worker verification ran the nine-project Release build with zero
warnings/errors, then passed 108 unit and 53 integration cases (161 total,
zero failed/skipped). Its native smoke used the actual Windows Client and
verified explicit synthetic selection, module probes/identity, DTC and static
signals, raw request/reply trace, virtual clear/readback/reset, close, target
metadata, profile, home and not-found routes. Exact observations and limitations
are recorded in the [Step-03 worker report](../prompts/Step-03-Report.md);
the run did not cover the subsequently identified integrity findings and Step-03
was not accepted.
Step-03A added actual failing-before/passing-after regressions for missing and
duplicate request fields, semantic response validation/trace consistency, and
clear acknowledgement versus verified readback. The final sequential Release
verification passed 111 unit tests and 64 integration tests (175 total, zero
failed/skipped), preserving the original 161 cases plus 14 additional test
cases. Exact commands and outcome details are in the
[Step-03A corrective report](../prompts/Step-03A-Report.md). Manual
orchestrator acceptance remains pending.
Step-03B reproduced the probe-only identity-loss defect before the fix through
the real Simulation transport: the regression expected a positive probe but
observed a negative discovery outcome. After the correction, the focused
protocol/UI integration selection passed 35 cases. The complete nine-project
Release build passed with zero warnings and errors, and the complete suite
passed 111 unit plus 72 integration tests (183 total, zero failed/skipped),
preserving all 175 Step-03A cases. Exact commands and AC mapping are recorded in
the [Step-03B corrective report](../prompts/Step-03B-Report.md).
The native Windows Client was launched and the operational baseline was
exercised in its own WebView: explicit example import/profile/revision/provider/
Simulation selection, session open, discovery with expected/probe/identity
counts, configured transmission no-response, engine DTC/static-signal reads,
verified clear with fresh empty readback, raw/decoded trace, reset with initial
DTC restoration, close, and `/execution-targets`, `/vehicle-profiles`, `/`,
and not-found routes. Exact observations and limitations are in the
[Step-03B corrective report](../prompts/Step-03B-Report.md). Native interaction
used a session-local WebView debug port on the worker-launched Client; partial
identity remains covered by real-DI rendered tests because the shipped native
configuration has no fault selector for that scenario.
## Step-04 fixed-step dynamics verification
The Step-04 Release regression ran sequentially against the full solution:
```powershell
dotnet build .\src\AutoForge.slnx --configuration Release --no-restore
dotnet test .\src\AutoForge.slnx --configuration Release --no-build
```
The native Windows-targeted build covered all nine solution projects with zero
warnings/errors. The complete test command passed 115 unit and 75 integration
tests (190 total, zero failed/skipped), preserving the Step-03B 183-test
baseline. The unit numerical gate executes 3,361 deterministic 0.1-second
samples and compares full sampled state across equal runs. The baseline results
were: 10.0 s warm idle at 650.000 rpm; acceleration to 20.1473 m/s in 10.3 s
with four scheduled shifts; all 3,000 cruise samples inside the configured
45-MPH +/- 1-MPH band and fully coupled; braking to 0.0000 m/s in 5.8 s; 10.0 s
return idle; and 0.518387 kg modeled total fuel. These are synthetic model
outputs, not measured vehicle performance or manufacturer predictions.
The actual Windows Client was launched with WebView2 local DevTools enabled for
the native smoke. `/simulation` required explicit selection of profile
`autoforge.synthetic.test-truck` revision 1, provider
`autoforge.simulation.dynamics`, and a configuration with fingerprint
`sha256:v1:e8991ae139b54959ec53a4fe64b08dc9bfc03feb533496cf741f2c9f3a2342da`.
Export/import preserved that fingerprint. A stopped open session returned 17
protocol-v2 dynamic telemetry values at step 4 / 0.4 model seconds after explicit
start/pause/step controls. The accelerated full scenario completed at step
3,361 / 336.1 model seconds with 17 telemetry values and four shifts. Invalid
`{}` import visibly reported the missing required `formatVersion`; exact-config
reset opened a new session at step 0 with the same fingerprint, and close
released it.
The native `/diagnostics` regression separately selected the original
`autoforge.simulation.synthetic` provider, discovered two positive probes out
of three expected endpoints (the transmission remained configured no-response),
and read the original engine DTC plus static 850-rpm and 12.6-V signals through
protocol v1 with trace records. The session was closed. Native route smoke
covered `/execution-targets` (both providers remain metadata), `/vehicle-profiles`,
`/`, and an unmatched not-found route. Numerical fidelity and reproducibility
are established by headless tests, not by visual telemetry.
## Native synthetic diagnostics smoke
Launch the actual Windows Client and visit `/diagnostics`:
1. Confirm the page starts without selecting/importing a profile or opening a
session. Click **Load synthetic truck example**; verify the profile appears
as an available revision but remains unselected.
2. Explicitly select `autoforge.synthetic.test-truck`, revision `1`, provider
`autoforge.simulation.synthetic`, and kind `Simulation`. Click **Open
simulation session** and confirm the visible session/profile/provider/
configuration identity. The session opens in process only.
3. Click **Probe virtual modules**. Engine/body respond; the configured
transmission endpoint visibly reports no response and is not reported as an
actual responder. Inspect the identity and declared implemented services.
4. Read the engine's DTCs and static signals. Values are synthetic static
snapshots with source, unit, quality and logical tick. Expand the bounded
trace to inspect actual request/response JSON and correlation values.
5. Clear the supported engine virtual DTCs, confirm the fresh readback is empty,
and confirm the UI explicitly states that no physical write occurred. Other
module/session state is isolated.
6. Exercise a visible deterministic failure (for example the configured
transmission no-response), then reset to the initial synthetic state and
close the session. Closing releases that session's trace and virtual state.
7. Separately visit `/execution-targets`, `/vehicle-profiles`, `/`, and an
unmatched route. Confirm metadata selection remains separate from an
operational session and the not-found/navigation behavior remains.
The Step-03A report records actual native baseline smoke separately from
headless rendered fault tests. The native Client revalidated explicit
profile/provider selection, successful clear with fresh empty readback,
trace/raw frames, visible no-response, reset/initial-state restoration, close
and existing routes. A deliberately false clear acknowledgement was injected
only in the rendered integration composition; the production Client has no UI
fault selector, so this is not native fault-injection evidence.
## Profile-schema and safety boundaries
See the [schema-v1 guide](vehicle-profile-schema-v1.md) for field, identity,
unknown-value, capability, provenance and strict JSON rules. Important invariants:
- Every v1 field is required; unknown optional facts are explicit JSON `null`.
Unknown fields and duplicate/case-ambiguous properties are rejected.
- Catalog selection requires exact `(profileIdentifier, revision)`. Duplicate
imports do not replace entries, and failed parsing cannot partially register.
- `publishedAt`/`retrievedAt` accept null or complete
`YYYY-MM-DDTHH:mm:ss[.fraction](Z|+HH:mm|-HH:mm)` timestamps only. The exact
fractional and offset limits and no-default policy are in the schema guide.
- A null optional module identity in evidence is an absent constraint. Any
supplied identity must match a known module value; an unknown target or
mismatch is rejected without identity inference.
- Imported profiles and capability/provenance statements are immutable
metadata, not connection, compatibility, a working service or authorization.
- Data remains in memory for the process only. JSON import/export does not write
files or timestamps implicitly.
- Static synthetic diagnostics use the [protocol v1 guide](synthetic-diagnostics-v1.md)
and [simulation definitions](simulation.md); dynamic output uses the separate
documented protocol-v2 provider. Neither is a real vehicle adapter, telemetry
capture, replay provider, calibration/firmware editor or hardware write path.
## Step-04A corrective verification
Step-04A corrects typed import errors for unavailable profile/revision/module or
conflicting calibration references, enforces the supported coupled RPM/redline
envelope, and makes progress, terminal failure and asynchronous runner ownership
explicit. It adds seven unit and five integration cases over the 190-case
Step-04 baseline. The final sequential commands were:
`dotnet build .\src\AutoForge.slnx --configuration Release --no-restore`
`dotnet test .\src\AutoForge.slnx --configuration Release --no-build`
The nine-project Windows Release build succeeded with zero warnings and zero
errors. The full test command passed 122 unit and 80 integration tests (202
total; zero failed/skipped). The warm baseline remains reproducible at 3,361
samples / 336.1 virtual seconds; 10.0 s warm idle at 650 rpm, 10.3 s acceleration
to 20.1473 m/s with four shifts, all 3,000 cruise samples in the original
45-MPH +/- 1-MPH band while coupled, braking to 0.0000 m/s in 5.8 s, 10.0 s
return idle, and 0.518387 kg modeled fuel. The added independent constant-torque
force/mass equation and speed-step equation checks use a `1e-10` acceleration
tolerance; independent locked RPM checks use `1e-8` rpm.
Controlled-pacer unit tests exercised active pause/freeze, resume, stop, reset,
restart, cancellation and disposal without wall-timer polling. Equivalent full
scenario samples were identical at 0.25x and 1000x; only requested pacing delay
changed. Rendered integration tests covered typed/atomic profile, revision and
module import failures; a persistent 0.1-second deadline failure and negative
`DYNAMICS_RUN_FAULTED` response; UI run reentrancy; and stale-run suppression
across reset, close, reopen and delayed open.
Headless numerical/integration coverage also accepts a finite but extreme
torque/gear vector that overflows modeled power during launch. The engine
rolls back to its last finite state/sample, marks the lifecycle Faulted, and the
real v2 session returns a negative `DYNAMICS_RUN_FAULTED` response rather than
encoding poisoned values.
The rebuilt Windows Client was launched at
`src/AutoForge.Client/bin/Release/net10.0-windows10.0.26100.0/win-x64/AutoForge.Client.exe`
and operated through its local WebView2 session. Import of unknown profile,
revision and module references showed recoverable error notices without
changing the selected valid configuration. The short-deadline run visibly ended
Faulted at step 101 / 10.1 model seconds; the failure remained visible after a
dynamic diagnostic read and previously good telemetry rows were cleared. A
valid baseline run completed at step 3,361 / 336.1 model seconds. The active
runner was then paused and held at step 1 while waiting, resumed, stopped,
explicitly stepped, reset to a new step-0 session, read 17 `SYNTHETIC_DYNAMIC`
values at step 0, exported/re-imported the configuration, and closed. The
`/diagnostics`, `/vehicle-profiles`, `/execution-targets`, `/`, and unmatched
not-found routes loaded. The launched Client and its local DevTools listener
were closed and verified absent afterward.
The Step-04 worker report remains historical; the corrective evidence is in the
[Step-04A report](../prompts/Step-04A-Report.md). Step-04/04A/04B are accepted.
All model and telemetry values remain synthetic.
## Step-04B owner-drain corrective verification
Start and resume now reject before changing lifecycle state when a previous
advancement owner is still cleaning up after pause, stop or reset. The real
simulation page reports that rejection as an error rather than a successful
start/resume. Controlled barrier tests reproduced the prior defect: while the
cancelled owner was held in cleanup, Pause-to-Resume changed `Paused` to
`Running`, Stop-to-Start changed `Stopped` to `Running`, and Reset-to-Start
changed `Stopped` at step 0 to `Running`. After the guard, all three complete
status snapshots and sample counts remain unchanged on rejection; releasing
cleanup then permits exactly one retry and one new fixed step.
The final sequential Release build covered all nine solution projects and
succeeded with zero warnings and zero errors. The full solution test command
passed 126 unit and 81 integration tests (207 total; zero failed/skipped),
preserving all 202 Step-04A cases. Focused owner-drain regressions passed 4
unit and 2 integration tests. See the [Step-04B corrective report](../prompts/Step-04B-Report.md)
for exact commands and detailed contract evidence.
The actual native Windows Client smoke exercised start, active pause/resume,
stop/restart, reset, protocol-v2 telemetry read and close. It confirmed stable
paused/stopped steps, a reset session at step 0, `SYNTHETIC_DYNAMIC` telemetry,
and release of the closed session. This manual UI smoke does not claim to force
the cleanup interleaving; that exact race is established by the controlled
headless tests. The Client and its task-local WebView2 debug listener/profile
were stopped and cleaned up. Step-04/04A/04B are accepted; the prior numerical
thresholds and synthetic-only scope are unchanged.
## Step-05A live dashboard corrective verification
The corrected dashboard is shared by the actual `/diagnostics` static-v1 and
`/simulation` dynamics-v2 workflows. Focused headless checks passed:
- `dotnet test .\src\tests\AutoForge.UnitTests\AutoForge.UnitTests.csproj --configuration Release --no-restore --filter FullyQualifiedName~LiveDashboardGaugeRenderingTests`
— 7 passed, 0 failed, 0 skipped.
- `dotnet test .\src\tests\AutoForge.IntegrationTests\AutoForge.IntegrationTests.csproj --configuration Release --no-restore --filter "FullyQualifiedName~LiveDashboard|FullyQualifiedName~RealApplicationAndRenderedRoute"`
— 10 passed, 0 failed, 0 skipped. The selection includes controlled feed,
actual static/dynamic provider, rendered panel, lifecycle and startup
regression cases.
- `dotnet test .\src\tests\AutoForge.IntegrationTests\AutoForge.IntegrationTests.csproj --configuration Release --no-restore --filter FullyQualifiedName~RealApplicationAndRenderedRoute_RunAndReadDynamicTelemetryWithoutOracle`
— 1 passed, 0 failed, 0 skipped; the real `/simulation` route renders the
shared dashboard panel for an open dynamics session.
The required sequential full commands were then run:
```powershell
dotnet build .\src\AutoForge.slnx --configuration Release --no-restore
dotnet test .\src\AutoForge.slnx --configuration Release --no-build
```
The build succeeded for all nine projects, including the native Windows Client,
with 0 warnings and 0 errors. The MAUI XAML source-generation notice was
informational. The complete suites passed 133 unit and 91 integration tests
(224 total, 0 failed, 0 skipped), preserving the 207-case baseline and adding
17 dashboard-focused cases.
The actual Windows Client smoke used .NET SDK 10.0.402/runtime 10.0.13, MAUI
workload 10.0.403 / `maui-windows` manifest 10.0.110, Windows SDK target
10.0.26100.0 and WebView2 Runtime 156.0.4314.50. On `/diagnostics`, the worker
explicitly imported and selected the synthetic truck/profile/provider, opened
the static session, and started monitoring before selecting verified bindings.
The native editor visibly rejected an invalid range and an `rpm` signal bound
to `km/h` without adding a gauge or stopping the feed. A numeric gauge rendered
850 rpm; a bar first rendered 850 rpm below its configured range at 0% geometry,
then after editing to 0..1000 rendered 85%. Removing it and hiding the remaining
gauge did not stop polling. Stop/restart succeeded on the same session. Reset
created a new session with a stopped empty dashboard and no prior gauge values;
a fresh feed started on the replacement session, and close removed the panel.
On `/simulation`, the actual v2 session was paused at step 1 / 0.1 model seconds.
The dashboard rendered `SYNTHETIC_DYNAMIC` engine speed and vehicle speed with
logical request ticks, model step/time, configuration fingerprint and run ID.
After an explicit 200-step command, the readings updated to step 201 /
20.1 seconds (2,795 rpm and 19.7 m/s). Two later polls kept the paused model at
step 201. Reset opened a new step-0 session/run with an empty stopped dashboard;
the first new run sample displayed `dynamics-run-000002`, not the prior run.
Close released the panel. The existing execution-target, profile, home and
not-found routes loaded. Both temporary Client/WebView2 processes and their
isolated user-data profiles were stopped/removed; loopback debug listeners were
verified closed. See the [Step-05A corrective report](../prompts/Step-05A-Report.md)
for the named controlled fault/lifecycle evidence and full acceptance mapping.
After the final source-path cleanup, the rebuilt Client was launched again;
actual static-v1 and dynamics-v2 sessions each reached dashboard cycle 1 and
closed cleanly with the panel removed.
## Step-05B range and boundary verification
The Uncertain projection now computes its range status independently of source
quality. Before the fix, the real-provider regression failed on the actual
Uncertain -10 rpm sample: expected `OutOfRangeLow`, actual `null`. After the
fix, the focused unit suite passed 8 cases and the focused integration selection
passed 3 cases, including real-provider Uncertain -10/1100 readings rendered
through both numeric and bar gauges, Uncertain values at both exact bounds,
atomic invalid-definition vectors, and controlled Stop-drain cleanup.
The full post-fix Release build succeeded for all nine projects with 0 warnings
and 0 errors; the MAUI XAML source-generation notice was informational. The full
Release test suite passed 134 unit and 91 integration tests (225 total, 0
failed, 0 skipped).
On the exact rebuilt native Client and an isolated WebView2 profile, the static
editor configured a horizontal bar from the real `SYNTHETIC_STATIC` engine
signal and displayed 850 rpm. The dynamics editor configured a numeric gauge
from the real `SYNTHETIC_DYNAMIC` engine signal and displayed 260 rpm with
logical tick, model step/time, configuration fingerprint and run identity; the
model was paused at step 1 / 0.1 seconds. Both sessions closed with their
dashboards, the exact test processes and port 9351 were verified stopped, and
the isolated test profile was removed. The older shared WebView2 profile was
left untouched. These native observations confirm the dashboard baseline; the
Uncertain and malformed-input cases are established by controlled tests, not
claimed as native UI injection.
Step-05 worker implementation remains pending manual review; these worker
results are not an orchestrator acceptance.