testing: add new guidelines + cov info

ref hyprwm/Hyprland#12383

Author: vaxerski

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.

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.