hyprwm/hyprland-wiki
1
0
Fork 0
mirror of https://github.com/hyprwm/hyprland-wiki.git synced 2025-12-19 19:20:02 +01:00
Code Issues Projects Releases Packages Wiki Activity

testing: add new guidelines + cov info (#1293)

Browse source 
ref https://github.com/hyprwm/Hyprland/pull/12383
This commit is contained in:
Vaxry 2025-12-05 14:16:29 +00:00 • committed by GitHub
parent 4d35b684be
commit 980a1b6902
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 73 additions and 32 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

40
content/Contributing and Debugging/PR-Guidelines.md
View file

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

65
content/Contributing and Debugging/Tests.md Normal file
View file

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