From 980a1b69022a87ccf978b742cd5a3d711af50f3c Mon Sep 17 00:00:00 2001 From: Vaxry <43317083+vaxerski@users.noreply.github.com> Date: Fri, 5 Dec 2025 14:16:29 +0000 Subject: [PATCH] testing: add new guidelines + cov info (#1293) ref https://github.com/hyprwm/Hyprland/pull/12383 --- .../PR-Guidelines.md | 40 +++--------- content/Contributing and Debugging/Tests.md | 65 +++++++++++++++++++ 2 files changed, 73 insertions(+), 32 deletions(-) create mode 100644 content/Contributing and Debugging/Tests.md diff --git a/content/Contributing and Debugging/PR-Guidelines.md b/content/Contributing and Debugging/PR-Guidelines.md index da024de..f0abdf2 100644 --- a/content/Contributing and Debugging/PR-Guidelines.md +++ b/content/Contributing and Debugging/PR-Guidelines.md @@ -30,6 +30,14 @@ _only_ ignore them if it's absolutely necessary. I've tweaked it so that in 99% of cases you absolutely should fix it. +### Testing + +Please check the [Tests](../Tests) page for information about tests in Hyprland, and related +projects. + +No test regressions is a _must_, while new tests are _required_ if possible to test (e.g. +graphical stuff is not testable). + ### Other Some stuff clang-tidy / clang-format won't catch: @@ -87,35 +95,3 @@ src/ If you are in `a.hpp` and want to include `b.hpp`, you _must_ use `../b/b.hpp`, and _cannot_ use `b/b.hpp`. The latter will break plugins. One exception you might notice in the code is absolute paths from the root are allowed, e.g. `protocols/some-protocol.hpp`. - -### Test your changes -Run and test your changes to make sure they work! - -## Testing and CI - -Since [#9297](https://github.com/hyprwm/Hyprland/pull/9297), we require each MR that fixes an issue -or adds a new feature to include test(s) for the feature, if possible. - -The testing framework is incapable of testing visual changes (e.g. graphical effects), and some very -niche parts (real HID devices, etc). However, if your change is related to: binds, layouts, config options, -window management, hyprctl, dispatchers, keywords, etc. your MR _needs_ tests. - -### How to run tests locally - -In order to run tests locally, build Hyprland, then: -```sh -cd hyprtester -../build/hyprtester/hyprtester --plugin ./plugin/hyprtestplugin.so -``` - -### How to add tests - -In order to add a new test, you can either make a new test file, or add a test to an existing file. -If you are adding a new test file, remember to end on a clean state: close all windows you've opened, and go back to workspace 1. - -If you are adding to an existing test file, find a file that's appropriate for the category -of your test. - -Tests are done by having a hyprland process active, issuing hyprctl commands, and checking the result with hyprctl queries. - -Check the `hyprtester/` directory of the source repo for more. \ No newline at end of file diff --git a/content/Contributing and Debugging/Tests.md b/content/Contributing and Debugging/Tests.md new file mode 100644 index 0000000..2a8d622 --- /dev/null +++ b/content/Contributing and Debugging/Tests.md @@ -0,0 +1,65 @@ +--- +title: Tests +--- + +Hyprland and some other projects under the hypr* umbrella have _tests_ that +try to catch bugs and regressions before code is merged. + +Building in Debug will by default build tests. + +## Running tests + +### GTests + +GTests are GoogleTests that are _unit tests_. These tests simply check how +some elements behave when they can run on their own. + +In all hypr* projects, GTests are ran by ctest. Run: + +```sh +ctest -j$(nproc) -C Debug --test-dir=build +``` + +And make sure your tests pass. + +### Hyprland's hyprtester + +A lot of hyprland's code cannot be unit tested, thus we have our own Hyprtester +binary which runs hyprland and issues commands and expects results. + +To run Hyprtester, `cd` into `./hyprtester`, then run: + +```sh +../build/hyprtester/hyprtester --plugin ./plugin/hyprtestplugin.so +``` + +*This will run for a while!* At the end, it will print summary results +of how many tests passed, and how many failed. + +The goal of failed tests is to be **0**. + +## Submitting new tests + +New tests have to either be a GTest, if the thing tested is possible to be unit tested, +or a part of hyprtester. + +For both test types, you can check the test directories in the project. GTests live in `tests/`, +while hyprtester tests live in `hyprtester/`. + +### What to test + +If you're submitting a new feature, it's obviously your feature. For a fix, try to write a test +case that would fail before your fix. + +For new tests, you can inspect the coverage report. + +First, run _both_ ctest and hyprtester. Then, run (from the repo root): + +```sh +gcovr -r . build --html --html-details -o build/coverage.html --gcov-ignore-parse-errors="negative_hits.warn" && xdg-open ./build/coverage.html +``` + +this will run for a while, then open a report in your browser. You can see which files have been tested in +what amount, and click on the files to see a line-by-line breakdown. + +If there are paths untested, we'd be very happy to receive tests for them.