# Where to Find the Amnezia VPN Client Testing Suite: Files, Build Steps, and Qt Test Framework

> Locate the Amnezia VPN client testing suite in the amnezia-vpn/amnezia-client repository. Discover build steps and learn how to compile the tests with CMake and the Qt Test framework.

- Repository: [Amnezia VPN/amnezia-client](https://github.com/amnezia-vpn/amnezia-client)
- Tags: how-to-guide
- Published: 2026-07-28

---

**The Amnezia VPN client testing suite lives in the repository’s top-level `tests/` directory, is built with CMake using the Qt Test framework, and compiles into the `amnezia-client-tests` executable.**

If you are contributing to or auditing the open-source **Amnezia VPN client**, you need to know how its automated validation is structured. The **Amnezia VPN client testing suite** is maintained in the `amnezia-vpn/amnezia-client` repository under the `dev` branch, where CMake and Qt Test handle compilation and execution. Familiarity with the layout and build process lets you run existing cases locally and add new ones with minimal overhead.

## Location and Architecture of the Amnezia VPN Client Testing Suite

The automated tests are rooted in the top-level **`tests/`** directory. As implemented in `amnezia-vpn/amnezia-client`, the root **[`CMakeLists.txt`](https://github.com/amnezia-vpn/amnezia-client/blob/main/CMakeLists.txt)** defines the `ENABLE_TESTS` option around lines 120–140, includes the `tests/` subdirectory, and wires the target into CTest. Every `*.cpp` file placed under `tests/` becomes part of the **`amnezia-client-tests`** binary, which the Qt Test framework executes.

## Building and Running the Tests Locally

To compile and run the **Amnezia VPN client testing suite** on your own machine, configure the project with tests enabled, build the dedicated target, and invoke CTest.

```bash

# Clone the repository (dev branch)

git clone -b dev https://github.com/amnezia-vpn/amnezia-client.git
cd amnezia-client

# Create a build directory

mkdir build && cd build

# Configure the project, enabling tests

cmake .. -DENABLE_TESTS=ON

# Build the test target

cmake --build . --target amnezia-client-tests

# Run all tests (CMake adds a `test` target)

ctest --output-on-failure

```

Passing **`-DENABLE_TESTS=ON`** tells CMake to declare the `amnezia-client-tests` executable and register it with CTest, as defined in the root [`CMakeLists.txt`](https://github.com/amnezia-vpn/amnezia-client/blob/main/CMakeLists.txt).

## Adding a New Test Case to the Suite

New cases follow the Qt Test macro pattern. Create a `*.cpp` file under `tests/`, then update [`tests/CMakeLists.txt`](https://github.com/amnezia-vpn/amnezia-client/blob/main/tests/CMakeLists.txt) to include it in `TEST_SOURCES`.

```cpp
// File: tests/test_example.cpp
#include <QtTest/QtTest>

class ExampleTest : public QObject {
    Q_OBJECT
private slots:
    void basicOperation() {
        QCOMPARE(2 + 2, 4);
    }
};

QTEST_MAIN(ExampleTest)
#include "test_example.moc"

```

After adding the file, append it to the test sources in [`tests/CMakeLists.txt`](https://github.com/amnezia-vpn/amnezia-client/blob/main/tests/CMakeLists.txt):

```cmake
set(TEST_SOURCES
    test_example.cpp
    # … other test files …

)

add_executable(amnezia-client-tests ${TEST_SOURCES})
target_link_libraries(amnezia-client-tests PRIVATE Qt5::Test amnezia-client-lib)
add_test(NAME amnezia-client-tests COMMAND amnezia-client-tests)

```

The next `cmake --build . --target amnezia-client-tests` and `ctest` invocation will compile and execute the new case automatically.

## Key Files and Infrastructure Helpers

Several source files define, compile, and execute the **Amnezia VPN client testing suite**:

- **`tests/`** — The root of the testing suite. It contains all test source files (`*.cpp`) and the local CMake configuration.
- **[`tests/CMakeLists.txt`](https://github.com/amnezia-vpn/amnezia-client/blob/main/tests/CMakeLists.txt)** — Declares the `amnezia-client-tests` executable, enumerates `TEST_SOURCES`, links against `Qt5::Test` and `amnezia-client-lib`, and registers the test with CTest.
- **[`CMakeLists.txt`](https://github.com/amnezia-vpn/amnezia-client/blob/main/CMakeLists.txt)** (lines 120–140) — Adds the `ENABLE_TESTS` option, includes the `tests/` directory, and creates the `test` target used by CI.
- **[`.github/workflows/ci.yml`](https://github.com/amnezia-vpn/amnezia-client/blob/main/.github/workflows/ci.yml)** — The GitHub Actions workflow that configures the build with tests enabled and runs `ctest` on every push and pull request.
- **[`client/platforms/windows/windowsutils.h`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/platforms/windows/windowsutils.h)** (line 19) — Provides the **`forceCrash()`** helper used by some integration tests to validate crash-handling behavior.

## Summary

- The **Amnezia VPN client testing suite** is housed in the top-level **`tests/`** directory of the `amnezia-vpn/amnezia-client` repository on the `dev` branch.
- **CMake** drives the build via the `ENABLE_TESTS` flag in the root [`CMakeLists.txt`](https://github.com/amnezia-vpn/amnezia-client/blob/main/CMakeLists.txt), while **Qt Test** supplies the underlying framework.
- Running `cmake --build . --target amnezia-client-tests` followed by `ctest` executes all cases locally.
- New tests are added by creating a Qt Test `.cpp` file and appending it to [`tests/CMakeLists.txt`](https://github.com/amnezia-vpn/amnezia-client/blob/main/tests/CMakeLists.txt).
- Continuous integration automatically runs the suite through [`.github/workflows/ci.yml`](https://github.com/amnezia-vpn/amnezia-client/blob/main/.github/workflows/ci.yml).

## Frequently Asked Questions

### Where is the Amnezia VPN client testing suite located?

The suite is located in the top-level **`tests/`** directory on the `dev` branch. This folder holds all test source files and the subdirectory’s [`CMakeLists.txt`](https://github.com/amnezia-vpn/amnezia-client/blob/main/CMakeLists.txt).

### What framework and build system does the testing suite use?

The suite uses the **Qt Test** framework and is orchestrated by **CMake**. The root [`CMakeLists.txt`](https://github.com/amnezia-vpn/amnezia-client/blob/main/CMakeLists.txt) enables testing through the `ENABLE_TESTS` option, and [`tests/CMakeLists.txt`](https://github.com/amnezia-vpn/amnezia-client/blob/main/tests/CMakeLists.txt) links each case to `Qt5::Test` and the `amnezia-client-lib` library.

### How do I compile and execute the tests on my machine?

Configure the build with `cmake .. -DENABLE_TESTS=ON`, then build the `amnezia-client-tests` target and run `ctest --output-on-failure`. These steps produce the test executable and execute every registered case.

### How are tests triggered in continuous integration?

The GitHub Actions workflow defined in **[`.github/workflows/ci.yml`](https://github.com/amnezia-vpn/amnezia-client/blob/main/.github/workflows/ci.yml)** configures the project with `-DENABLE_TESTS=ON` and invokes `ctest` on every pull request and push, ensuring the **Amnezia VPN client testing suite** is validated before any code reaches the `dev` branch.