Headless Testing in CI Overview

The SmartSpectra SDKs are headless — they ship no built-in UI, so your application (or a test harness) drives the SDK and reads results from callbacks. That same property lets you exercise the SDK unattended in a CI pipeline: on every commit, prove that your integration still builds, starts, and produces readings, without a person holding a phone in front of a camera.

This page is the cross-platform overview. Each SDK has its own guide with the exact sample, commands, and flags — see Per-platform guides.

Two ways to test headlessly

What you can automate depends on how the platform accepts input:

• Video-fed measurement — every SDK can run a full measurement from a recorded video in place of a live camera, so CI can assert that readings came out. No camera or display is needed. On desktop (C++, Node.js) the file input is regular public API. Android and iOS also accept caller-decoded frames through public useCustomInput(). The mobile testing helpers require explicit opt-in: @_spi(Testing) on iOS and @OptIn(SmartSpectraTestingApi::class) on Android.
• Build-integration smoke — the lighter fallback on any platform when you don’t have a recorded clip: prove the SDK builds, links, launches headless, initializes, and surfaces the expected permission/error states.

What you’ll need

For any of the above:

• A SmartSpectra API key, provided to the job as a CI secret (never hard-code it in the repo). Your platform sample accepts it at startup.
• Network access from the CI runner to the SmartSpectra service. Measurement authenticates online — there is no offline mode, so an air-gapped runner can’t complete a measurement.

For video-fed measurement, additionally:

• A short recorded video you supply — around 30–60 seconds of a well-lit, mostly still face, framed like a real measurement (long enough for rates to compute; a few seconds isn’t). Keep the clip in your own test assets. See the platform guide for the container/codec each SDK expects.

The video-fed model

A video-fed headless test is the same shape on every platform:

recorded video  ->  SDK video input  ->  metric callbacks  ->  assertions
        (no camera, no display)

Feed the file, let the SDK run its normal pipeline, and assert on what the callbacks emit. Keep the assertion smoke-level: check that the SDK produced real readings (for example, a pulse rate and a breathing rate appeared), rather than checking exact values. A smoke test confirms the integration and the model pipeline are wired up end-to-end; it is not an accuracy benchmark.

A CI pipeline, in general terms

Whatever CI system you use, the shape is the same:

1. Expose the API key as a job secret.
2. Install or build the SmartSpectra SDK for the platform (follow the platform’s install guide).
3. Run the sample headlessly — feed your recorded video through the platform’s video input (a headless sample on desktop, an instrumented / XCTest run on mobile).
4. Fail the job if the run crashed or didn’t produce the expected output.

A minimal, provider-neutral sketch (GitHub Actions, video-fed) — adapt the install and run steps to your platform’s guide:

name: smartspectra-headless-smoke
on: [push]

jobs:
  headless:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Install the SmartSpectra SDK for your platform (see the platform guide).
      - name: Install SmartSpectra
        run: echo "follow the platform install guide"

      # Run a headless sample against a recorded video you keep in the repo.
      # The sample exits non-zero (failing the job) if it can't measure.
      - name: Headless measurement smoke
        run: |
          ./your_smartspectra_sample \
            --api_key="${{ secrets.SMARTSPECTRA_API_KEY }}" \
            --input_video_path=./test-assets/face.mp4

Per-platform guides

Bring the model above; each guide fills in the concrete sample, flags, and CI steps for its platform (see the sidebar):

• C++ — headless sample with recorded-video input on Linux, macOS, and Windows.
• Node.js — headless sample that plays a recorded video through the SDK.
• Android — video-fed measurement as an instrumented test on an emulator, via the public CustomInput frame handle.
• iOS — video-fed measurement as an XCTest on the iOS Simulator, via public custom input or testing-only @_spi(Testing) file playback.

Limitations

• No offline mode. A measurement authenticates against the SmartSpectra service; the CI runner needs network access.
• iOS file playback is testing-only. Use public custom input for production Android and iOS capture integrations. Keep mobile testing helpers out of production paths.