test: add xUnit suite, coverage gate, and CI for the audio pipeline

Add a SoundButtons.Tests xUnit project with unit and integration tests
covering all openspec/specs requirements, enforcing a >=85% line+branch
coverage gate via coverlet.msbuild. Introduce behavior-preserving
testability seams: IProcessAudioService/IOpenAiService interfaces,
internal static OptionSet builders, IHttpClientFactory-based YouTube
scraping, and ServiceCollectionExtensions.AddSoundButtonsServices.

Add Dockerfile `test` and `report` stages (off the production path) and
a test.yml workflow that runs the suite + gate inside the test stage,
builds the final image, uploads coverage to Codecov (fork-safe), and runs
infra conformance checks (TFM, Dockerfile pins, dumb-init/STOPSIGNAL,
hadolint, helm automount).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: jim60105

.github/workflows/test.yml

@@ -0,0 +1,96 @@
+name: test
+
+# Runs the test suite (with the >=85% line+branch coverage gate enforced inside
+# the Docker `test` stage) and the infrastructure conformance checks. The Docker
+# build fails on any test or coverage-gate failure, so coverage is enforced
+# independently of Codecov.
+on:
+  pull_request:
+  push:
+    branches:
+      - "master"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  conformance:
+    name: Infra conformance checks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Assert .NET target framework and Functions version
+        run: |
+          grep -q '<TargetFramework>net10.0</TargetFramework>' SoundButtons/SoundButtons.csproj
+          grep -q '<AzureFunctionsVersion>v4</AzureFunctionsVersion>' SoundButtons/SoundButtons.csproj
+
+      - name: Assert Dockerfile image and tool pins
+        run: |
+          # .NET 10 base/build/sdk images
+          grep -Eq 'mcr\.microsoft\.com/dotnet/sdk:10\.0' Dockerfile
+          # ffmpeg pinned to 8.1
+          grep -q 'static-ffmpeg-upx:8.1' Dockerfile
+          # dumb-init pinned to v1.2.5 with checksum verification
+          grep -q 'dumb-init/releases/download/v1.2.5/' Dockerfile
+          grep -q 'sha256sum -c -' Dockerfile
+
+      - name: Assert container init process (dumb-init PID 1)
+        run: |
+          grep -q 'ENTRYPOINT \[ "dumb-init"' Dockerfile
+          grep -q 'STOPSIGNAL SIGINT' Dockerfile
+          # dumb-init must come from the dedicated checksum-verified `download` stage,
+          # not be bundled with the ffmpeg image, and must not run with --single-child.
+          grep -q 'COPY .*--from=download /dumb-init' Dockerfile
+          ! grep -q 'single-child' Dockerfile
+
+      - name: Lint Dockerfile (hadolint)
+        uses: hadolint/hadolint-action@v3.1.0
+        with:
+          dockerfile: Dockerfile
+
+      - name: Set up Helm
+        uses: azure/setup-helm@v4
+
+      - name: Assert Kubernetes automountServiceAccountToken disabled by default
+        run: |
+          helm template helm | grep -q 'automountServiceAccountToken: false'
+
+  test:
+    name: Test suite + coverage
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    env:
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          submodules: true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      # The `test` stage runs the suite and enforces the >=85% line+branch gate;
+      # the build fails here on any test or coverage failure. The `report` stage
+      # exports the Cobertura XML + TRX for Codecov.
+      - name: Run tests and export coverage report
+        run: |
+          docker build --target report --output type=local,dest=./out -f Dockerfile .
+
+      # The design requires CI to confirm the production image still builds; the
+      # test/report stages are off the production path, so build `final` explicitly.
+      - name: Build production image (final stage)
+        run: |
+          docker build --target final -t soundbuttons-final-ci -f Dockerfile .
+
+      - name: Upload coverage to Codecov
+        if: ${{ env.CODECOV_TOKEN != '' }}
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./out/testresults/coverage.cobertura.xml
+          fail_ci_if_error: false

.gitignore

@@ -264,3 +264,10 @@ __pycache__/
 *.pyc
 .env
 tmp/**
+
+# Coverage reports
+coverage*.xml
+coverage*.json
+*.cobertura.xml
+SoundButtons.Tests/cov.xml
+/out/

Dockerfile

@@ -61,6 +61,53 @@ COPY SoundButtons/ ./SoundButtons/
 ARG TARGETARCH
 RUN dotnet publish "SoundButtons/SoundButtons.csproj" -a $TARGETARCH -c $BUILD_CONFIGURATION -o /app --no-restore
 
+########################################
+# Test stage
+########################################
+# Runs unit + integration tests on the build platform (tests execute natively, so no
+# cross-arch emulation). The static ffmpeg/ffprobe binaries enable the encoder
+# integration tests; coverage is enforced via the coverlet.msbuild threshold configured
+# in the test project. Results are written to /testresults for the report stage to export.
+FROM build AS test
+
+# ffmpeg/ffprobe for the encoder integration tests (no network required: media is
+# synthesized with lavfi virtual inputs).
+COPY --chmod=775 --from=ghcr.io/jim60105/static-ffmpeg-upx:8.1 /ffmpeg /usr/local/bin/
+COPY --chmod=775 --from=ghcr.io/jim60105/static-ffmpeg-upx:8.1 /ffprobe /usr/local/bin/
+
+# yt-dlp for the generic download-path integration test (driven against a local file://
+# URL, so still no network is required at test time).
+ADD --chmod=775 https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_linux /usr/local/bin/yt-dlp
+
+WORKDIR /source
+
+# Restore the test project (and its reference to the production project) for the build
+# platform so the test host runs natively.
+COPY SoundButtons.Tests/SoundButtons.Tests.csproj ./SoundButtons.Tests/
+RUN dotnet restore "SoundButtons.Tests/SoundButtons.Tests.csproj"
+
+# Copy the rest of the source files (production project already copied is not, so copy both)
+COPY SoundButtons/ ./SoundButtons/
+COPY SoundButtons.Tests/ ./SoundButtons.Tests/
+
+# Run tests with coverage. The coverlet.msbuild Threshold (85, line+branch, total) in the
+# test csproj fails the build if coverage regresses. Cobertura + TRX are emitted for CI.
+RUN dotnet test "SoundButtons.Tests/SoundButtons.Tests.csproj" \
+        -c Debug \
+        --results-directory /testresults \
+        --logger "trx;LogFileName=test-results.trx" \
+        -p:CollectCoverage=true \
+        "-p:CoverletOutputFormat=cobertura%2cjson" \
+        -p:CoverletOutput=/testresults/
+
+########################################
+# Report stage
+########################################
+# Minimal scratch image whose sole purpose is to export the test results/coverage to the
+# host via `docker build --target report --output type=local,dest=...`.
+FROM scratch AS report
+COPY --from=test /testresults /testresults
+
 ########################################
 # Download stage
 ########################################

SoundButtons.Tests/AssemblyInfo.cs

@@ -0,0 +1,6 @@
+using Xunit;
+
+// Several tests mutate process-global state (environment variables, PATH, and the
+// current working directory) to exercise binary discovery and configuration code
+// paths. Disable cross-class parallelization so those mutations cannot race.
+[assembly: CollectionBehavior(DisableTestParallelization = true)]

SoundButtons.Tests/Fakes/BlobMocks.cs

@@ -0,0 +1,61 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Threading;
+using Azure;
+using Azure.Storage.Blobs;
+using Azure.Storage.Blobs.Models;
+using Microsoft.Extensions.Azure;
+using Moq;
+
+namespace SoundButtons.Tests.Fakes;
+
+/// <summary>
+///     Builds mocked Azure Blob Storage clients so functions depending on
+///     <see cref="IAzureClientFactory{BlobServiceClient}" /> can be unit tested without a
+///     real storage account. All blob operations are intercepted in-memory.
+/// </summary>
+public static class BlobMocks
+{
+    public static IAzureClientFactory<BlobServiceClient> CreateFactory(Mock<BlobContainerClient> container)
+    {
+        var service = new Mock<BlobServiceClient>();
+        service.Setup(s => s.GetBlobContainerClient(It.IsAny<string>())).Returns(container.Object);
+
+        var factory = new Mock<IAzureClientFactory<BlobServiceClient>>();
+        factory.Setup(f => f.CreateClient(It.IsAny<string>())).Returns(service.Object);
+        return factory.Object;
+    }
+
+    public static Mock<BlobContainerClient> CreateContainer()
+    {
+        var container = new Mock<BlobContainerClient>();
+        container.Setup(c => c.Name).Returns("sound-buttons");
+        return container;
+    }
+
+    public static Mock<BlobClient> CreateBlob(bool exists, string? readContent = null)
+    {
+        var blob = new Mock<BlobClient>();
+        blob.Setup(b => b.Name).Returns("blob");
+        blob.Setup(b => b.ExistsAsync(It.IsAny<CancellationToken>()))
+            .ReturnsAsync(Response.FromValue(exists, Mock.Of<Response>()));
+        blob.Setup(b => b.Exists(It.IsAny<CancellationToken>()))
+            .Returns(Response.FromValue(exists, Mock.Of<Response>()));
+
+        if (readContent is not null)
+        {
+            blob.Setup(b => b.OpenReadAsync(It.IsAny<long>(), It.IsAny<int?>(), It.IsAny<BlobRequestConditions>(), It.IsAny<CancellationToken>()))
+                .ReturnsAsync(() => new MemoryStream(System.Text.Encoding.UTF8.GetBytes(readContent)));
+        }
+
+        blob.Setup(b => b.UploadAsync(It.IsAny<BinaryData>(), It.IsAny<BlobUploadOptions>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync(Response.FromValue(Mock.Of<BlobContentInfo>(), Mock.Of<Response>()));
+        blob.Setup(b => b.UploadAsync(It.IsAny<string>(), It.IsAny<BlobUploadOptions>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync(Response.FromValue(Mock.Of<BlobContentInfo>(), Mock.Of<Response>()));
+        blob.Setup(b => b.SetMetadataAsync(It.IsAny<IDictionary<string, string>>(), It.IsAny<BlobRequestConditions>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync(Response.FromValue(Mock.Of<BlobInfo>(), Mock.Of<Response>()));
+
+        return blob;
+    }
+}

SoundButtons.Tests/Fakes/FakeHttpClientFactory.cs

@@ -0,0 +1,10 @@
+using System.Net.Http;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace SoundButtons.Tests.Fakes;
+
+/// <summary>Simple <see cref="IHttpClientFactory" /> returning a client over the supplied handler.</summary>
+public sealed class FakeHttpClientFactory(HttpMessageHandler handler) : IHttpClientFactory
+{
+    public HttpClient CreateClient(string name) => new(handler, disposeHandler: false);
+}

SoundButtons.Tests/Fakes/FakeHttpCookies.cs

@@ -0,0 +1,16 @@
+using System.Collections.Generic;
+using Microsoft.Azure.Functions.Worker.Http;
+
+namespace SoundButtons.Tests.Fakes;
+
+/// <summary>No-op <see cref="HttpCookies" /> double; the production code under test does not use cookies.</summary>
+public sealed class FakeHttpCookies : HttpCookies
+{
+    public List<IHttpCookie> Appended { get; } = [];
+
+    public override void Append(string name, string value) => Appended.Add(new HttpCookie(name, value));
+
+    public override void Append(IHttpCookie cookie) => Appended.Add(cookie);
+
+    public override IHttpCookie CreateNew() => new HttpCookie(string.Empty, string.Empty);
+}

SoundButtons.Tests/Fakes/FakeHttpMessageHandler.cs

@@ -0,0 +1,32 @@
+using System;
+using System.Collections.Generic;
+using System.Net;
+using System.Net.Http;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace SoundButtons.Tests.Fakes;
+
+/// <summary>
+///     Test <see cref="HttpMessageHandler" /> returning queued/predicated responses, used
+///     for the OpenAI client and the YouTube-clip scrape. No real network is performed.
+/// </summary>
+public sealed class FakeHttpMessageHandler : HttpMessageHandler
+{
+    private readonly Func<HttpRequestMessage, HttpResponseMessage> _responder;
+
+    public List<HttpRequestMessage> Requests { get; } = [];
+
+    public FakeHttpMessageHandler(Func<HttpRequestMessage, HttpResponseMessage> responder) => _responder = responder;
+
+    public FakeHttpMessageHandler(HttpStatusCode statusCode, string content)
+        : this(_ => new HttpResponseMessage(statusCode) { Content = new StringContent(content) })
+    {
+    }
+
+    protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
+    {
+        Requests.Add(request);
+        return Task.FromResult(_responder(request));
+    }
+}

SoundButtons.Tests/Fakes/FakeHttpRequestData.cs

@@ -0,0 +1,47 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Net;
+using System.Security.Claims;
+using System.Text;
+using Microsoft.Azure.Functions.Worker;
+using Microsoft.Azure.Functions.Worker.Http;
+
+namespace SoundButtons.Tests.Fakes;
+
+/// <summary>
+///     Minimal in-memory <see cref="HttpRequestData" /> double for exercising the HTTP
+///     trigger without the Functions host. The body is supplied as a stream and headers
+///     are mutable.
+/// </summary>
+public sealed class FakeHttpRequestData(FunctionContext functionContext, Stream body, string contentType)
+    : HttpRequestData(functionContext)
+{
+    public override Stream Body { get; } = body;
+
+    public override HttpHeadersCollection Headers { get; } = BuildHeaders(contentType);
+
+    public override IReadOnlyCollection<IHttpCookie> Cookies { get; } = Array.Empty<IHttpCookie>();
+
+    public override Uri Url { get; } = new("https://sound-buttons.click/api/sound-buttons");
+
+    public override IEnumerable<ClaimsIdentity> Identities { get; } = Array.Empty<ClaimsIdentity>();
+
+    public override string Method => "POST";
+
+    public override HttpResponseData CreateResponse() => new FakeHttpResponseData(FunctionContext);
+
+    private static HttpHeadersCollection BuildHeaders(string contentType)
+    {
+        var headers = new HttpHeadersCollection();
+        if (!string.IsNullOrEmpty(contentType))
+        {
+            headers.Add("Content-Type", contentType);
+        }
+
+        return headers;
+    }
+
+    public static FakeHttpRequestData FromText(FunctionContext context, string body, string contentType)
+        => new(context, new MemoryStream(Encoding.UTF8.GetBytes(body)), contentType);
+}

SoundButtons.Tests/Fakes/FakeHttpResponseData.cs

@@ -0,0 +1,29 @@
+using System.IO;
+using System.Net;
+using Microsoft.Azure.Functions.Worker;
+using Microsoft.Azure.Functions.Worker.Http;
+
+namespace SoundButtons.Tests.Fakes;
+
+/// <summary>
+///     Minimal in-memory <see cref="HttpResponseData" /> double. The body is a seekable
+///     <see cref="MemoryStream" /> so tests can read whatever the production code wrote.
+/// </summary>
+public sealed class FakeHttpResponseData(FunctionContext functionContext) : HttpResponseData(functionContext)
+{
+    public override HttpStatusCode StatusCode { get; set; } = HttpStatusCode.OK;
+
+    public override HttpHeadersCollection Headers { get; set; } = new();
+
+    public override Stream Body { get; set; } = new MemoryStream();
+
+    public override HttpCookies Cookies { get; } = new FakeHttpCookies();
+
+    /// <summary>Reads the response body as a UTF-8 string.</summary>
+    public string ReadBodyAsString()
+    {
+        Body.Position = 0;
+        using var reader = new StreamReader(Body, leaveOpen: true);
+        return reader.ReadToEnd();
+    }
+}