# Overview

The Audio Testsuite provides a SDK6 JUnit testsuite which validates the implementation of the low-level Audio API as
well as the audio playback quality.

The testsuite provides 3 classical test classes:

- `AudioFormatTest` which validates the different AudioFormats such as G711, Ogg Vorbis and PCM.
- `AudioSinkTest` which validates audio sinks writing correctness and time duration.
- `AudioSourceTest` which validates audio source reading correctness and time duration.

And an advanced one to validate audio playback quality:

- `AudioQualityTest` which plays a list of audio files then returns their correctness.

## AudioQualityTest

Unlike the classical test classes, AudioQualityTest does not operate in isolation. It relies on two external components
to function: a Client/Server connection and an AudioPlayer. This section describes these dependencies, their roles, and
how they interact within the test flow.

### Architecture Overview

| Class diagram                                      | State diagram                                      |
|----------------------------------------------------|----------------------------------------------------|
| ![Class diagram](./src/diagrams/class_diagram.png) | ![State diagram](./src/diagrams/state_diagram.png) |

#### Client / Server connection

As the device cannot store all the audio files at once, we need to provide them one after another. To do so, and to
avoid flashing the device for each audio file, we are using an HTTP
Client / [Server](../server/audio-testsuite-server/README.md)
connection.
Currently, there is a limitation: the s7 board can only open one socket at a time.

#### Audio player

The device does not analyze audio files to verify their quality, it plays them back so the server can record and analyze
them instead. To do so, both the server and the client must be synchronized, so for each file the client sends a POST
request to the server when starting and stopping the playback. The player controller retrieves results and provides them
to the test suite.

##### Class description

- `WaitForConnectivity`: Provides methods to wait for the device to get an IP address before starting networking.
- `ConnectionInputStream`: Generates an InputStream from an HttpURLConnection and closes the connection and the input
  stream at the same time. This class is needed because of the socket restriction.
- `HttpClient`: The HTTP client. This class communicates with the server to retrieve JSON responses. It also contains
  methods to convert the received information into `InputStream` and `AudioFormat`.
    - `AudioRecord`: Acts like a Java 16 `Record` to store audio file information (file name, encoding, audio format).
- `AudioPlayer`: A simple audio player that plays audio based on an `InputStream` and an `AudioFormat`.
- `AudioPlayerController`: A controller that notifies the server when an audio file playback starts/stops and
  retrieves the analysis computed by the server.
- `AudioQualityTest`: A test that, for each audio file exposed by the server, plays it and asserts its analysis.

### Test flow

The following describes the sequence of operations performed during an `AudioQualityTest` run.

#### Setup

Before the tests begin, the application waits for the device to obtain an IP address (`WaitForConnectivity`). Once
connectivity is established, the `HttpClient` queries the server to retrieve the list of available audio files.
For each audio file, the server also provides the corresponding `AudioFormat` metadata.

> **Note:** The server must be started and ready before the testsuite is launched on the device. Refer to the
> [Server documentation](../server/audio-testsuite-server/README.md) for setup instructions.

#### Per-file playback loop

For each audio file exposed by the server, the following sequence is executed:

1. The `HttpClient` fetches the audio file as a stream from the HTTP server.
2. The `AudioPlayerController` sends a **"Start Recording"** POST request to the server, which triggers the server-side
   audio capture.
3. The `AudioPlayer` plays back the audio stream on the device. The captured output is simultaneously recorded by the
   server.
4. Once playback is complete, the `AudioPlayerController` sends an **"End Recording"** POST request to the server.
5. The server stops the capture, compares the recorded PCM output against the reference file, and computes an analysis
   report.
6. The `AudioPlayerController` retrieves the analysis report from the server.
7. `AudioQualityTest` asserts the result: the test passes if the analysis report indicates the playback matches the
   reference, and fails otherwise.

This loop repeats until all audio files have been played and analyzed. The analysis results are provided at the end of
the test run.

# Usage

The testsuite supports two launch modes:

## CI mode

The testsuite is designed to run in CI using the Gradle plugin `audio-testsuite-server-plugin`, which automatically
starts and stops the server around the test run. In this mode, the entire testsuite can be launched with a single
command: `./gradlew audio-testsuite:test`

The plugin handles server lifecycle management, so no manual server startup is required.

## Manual mode

If the board already has the testsuite flashed, it is possible to start the server independently and trigger a new test
run by simply resetting the board, without reflashing it:

1. Start the [Testsuite Server](../server/audio-testsuite-server/README.md).
2. Reset the board.

This is particularly useful when only the server needs to be modified or reconfigured between runs.

> **Note:** Running `./gradlew audio-testsuite:test` also starts the server automatically, just like in CI mode.

# Requirements

- The target device must be connected and reachable over the network.
- The [Testsuite Server](../server/audio-testsuite-server/README.md) must be running on the host computer before launching the
  testsuite (manual mode only — handled automatically in CI mode).

> **VEE Port:** The VEE Port used to run the testsuite is hardcoded via the `testMicroejVee` directive in
> `audio-testsuite/build.gradle.kts`. Make sure this path matches your local build of the s7-veeport before running the
> testsuite:
> - `testMicroejVee("com.mycompany:vee-port:1.0.0")`

# Dependencies

_All dependencies are retrieved transitively by Gradle_.

# Source

N/A.

# Restrictions

None.

---
_Copyright 2024-2026 MicroEJ Corp. All rights reserved._  
_This library is provided in source code for use, modification and test, subject to license terms._  
_Any modification of the source code will break MicroEJ Corp. warranties on the whole library._
