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

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 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.

# 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.

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 to include it in TEST_SOURCES.

// 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:

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 — 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 (lines 120–140) — Adds the ENABLE_TESTS option, includes the tests/ directory, and creates the test target used by CI.
• .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 (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, 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.
• Continuous integration automatically runs the suite through .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.

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 enables testing through the ENABLE_TESTS option, and 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}