# Build & Testing

## Requirements

- .NET 10 SDK
- Windows for the WPF application and WASAPI integration
- Git
- Windows PowerShell for build scripts/icon generation
- Inno Setup 6 when building Setup

See [Requirements](Requirements.md); release users do not need the SDK.

Core code and unit-style validation can run without launching the WPF application, but the full CI pipeline uses Windows.

## Build

From the repository root:

```powershell
dotnet build VxSound.slnx -c Release -m:1
```

Warnings are treated as errors by the shared build properties.

## Run core tests

```powershell
dotnet run --project tests/VxSound.Tests -c Release --no-build
```

The test harness covers areas including:

- filter response;
- shelving behavior;
- automatic headroom;
- bypass continuity;
- left/right isolation;
- limiter behavior;
- streaming block continuity;
- render-loop allocation checks;
- profile validation and storage;
- provenance/export behavior;
- mixer route validation;
- updater download/verification handles on Windows, retry, cancellation, checksum/size failures and installed/portable package selection;
- diagnostic export allowlists and updater/helper log collection;
- listening-test state and persistence;
- generated reference-audio format and signal checks.

## Run the application

```powershell
dotnet run --project src/VxSound.App -c Release
```

Audio-device behavior should be tested on a real Windows system with the relevant output/input endpoints available.

## Publish a portable build

```powershell
dotnet publish src/VxSound.App -c Release -r win-x64 --self-contained true -p:PublishSingleFile=false -o artifacts/VxSound
```

## GitHub Actions pipeline

`.github/workflows/windows.yml` runs on pull requests and pushes to `main`.

The Windows job performs:

1. repository checkout;
2. .NET 10 setup;
3. Release build;
4. DSP/profile/routing/listening tests;
5. self-contained Windows x64 publish;
6. WPF smoke test;
7. packaging;
8. installer build and real install/service/uninstall validation;
9. artifact upload.

The release workflow is triggered by changes to `release-trigger/**` on `main`, validates the version against `Directory.Build.props`, and gates publication on build/tests and installer validation. It uploads Setup, full ZIP and compatibility portable EXE with SHA-256 files, verifies the uploaded assets, then publishes the draft release.

## WPF smoke test

The smoke-test mode constructs and renders all primary application views without requiring real audio hardware. It also exercises the guided-listening UI states. A validation report and screenshots are emitted as CI artifacts.

The smoke test catches many layout/construction failures but is not a substitute for real device playback testing.

## Reference-audio validation

Synthetic reference material is generated during automated validation rather than committed as large binary WAV files. Tests inspect WAV metadata and verify non-silent output.

## Pull request expectations

Before merging a code change:

- build Release successfully;
- keep core tests green;
- keep the WPF smoke test green when UI code changes;
- update documentation for user-visible behavior;
- preserve required third-party notices;
- do not add private/local data as test fixtures.

See [CONTRIBUTING.md](Contributing.md) for contribution workflow.

## Resume an interrupted release upload

The publisher preserves assets only when their size and GitHub SHA-256 digest match the original validated bundle. It verifies all six assets before publishing, refuses to overwrite a different completed asset, and allows up to 120 minutes for slow uploads.

Use **Actions → Resume validated release → Run workflow** with the original release run ID. Alternatively, commit `release-recovery/request.json` on `main` containing `{"source_run_id": 35275085428}` (replace the example ID with the intended run). Recovery waits for any active release, verifies the original main-branch release run and its successful **Build & Tests** and **Installer Validation** jobs, then downloads that run’s unchanged release-ready artifact. It does not rebuild binaries or bypass validation. An already published, matching release is left unchanged.

Release-script checks run on the Ubuntu publishing runner using `python -m unittest discover -s tests/release -v`; they mock GitHub and never upload real assets.