contributing: Add a testing guide

[wenzeslaus]

The most complete statement of GRASS testing conventions lived in AGENTS.md, written for AI agents, and a contributor following the documented path never saw it. style_guide.md had no testing section, testsuite/README.md gave pytest a single sentence, and the Testing section in development_intro.md linked only the gunittest manual.

This adds testing.md covering the choice between pytest and gunittest, test placement and naming, session fixtures, grass.tools, test data, running the tests, and tests which cannot run in parallel. AGENTS.md now points at the guide and keeps only its agent-specific notes, so the two cannot drift too much.

This change was drafted with the help of Claude Code (Fable 5).

Details (AI-generated)

What the guide covers

Choosing between pytest and gunittest; where test files go and how they are named; setting up a session fixture; running tools with grass.tools; generating test data; running the tests; and needs_solo_run, which is load-bearing because CI's default pass runs --numprocesses=auto -m 'not needs_solo_run' and was documented nowhere.

The conventions come from test code in the tree rather than from prose. Where the tree and AGENTS.md disagreed, the tree won.

The gunittest command was wrong

grass -c <project>/<mapset> --exec ./test_x.py fails with Permission denied. The test files are not executable (311 of 317 are mode 644, and only 13 have a shebang), and lib/init/grass.py only recovers from ENOENT, not EACCES. Separately, the -c form aborts on a second run because the mapset already exists, which is exactly the case of re-running a test after a fix.

Both testing.md and AGENTS.md now use --tmp-mapset with an explicit python interpreter, and note that some tests load data files by relative path and so must be run from their own directory.

Reachability and the build

Linked from CONTRIBUTING.md, doc/development/README.md, testsuite/README.md, a new short Testing section in style_guide.md, and man/mkdocs/docs/development_intro.md. Registered in doc/development/Makefile and doc/development/CMakeLists.txt, the same two places style_guide.md is registered; without both, the page builds nowhere and the link from development_intro.md 404s.

Like the other development guides, the page is reached through development_intro.md rather than through the mkdocs nav. That is existing behaviour, not something this PR changes.

style_guide.md

Gains a short Testing section stating the expectation and pointing at the guide. It asks that a bug fix touching untested code also add a test for that code's basic functionality, so it is visible that the fix did not break behaviour which was already correct.

Verification

• The fixture and test in the guide were extracted from the finished page and run against a local build. They pass. The asserted values match the existing r_slope_aspect_test.py, which also passes.
• The corrected gunittest command was extracted verbatim from AGENTS.md and executed: exit 0, and again on a second consecutive run. A separate run reported Ran 16 tests and OK.
• The old -c form was executed and reproduced both failures.
• A local mkdocs build confirms testing.html is generated and that the link from development_intro.html resolves. This built against an existing dist tree with the new page added, not from a full build of this branch.
• pre-commit passes. gersemi could not run in this environment because its cache directory was not writable, so the one-line CMakeLists.txt change is unverified by that hook.

Left for separate changes

testsuite/README.md lines 25-26 contain literal backslashes in the export commands, so copying them sets literal strings instead of running the command substitutions. python/grass/grassdb/tests/grass_grassdb_create_xy.py matches no collection pattern in pyproject.toml and is therefore never run, despite containing a test function.

[wenzeslaus]

This branch is in the main repo, not my fork. I made a new clone and forgot to check/finish my setup. Since it is already created, I'll leave it as is and delete it when this PR is closed.

[Pranav-error]

Very glad to see this — I hit two of these conventions the hard way in the last few weeks and had to reconstruct them from other tests.

One case the guide does not cover, and it bit me on #7835: a test that calls into C through ctypes should make those calls in a subprocess.

My regression test there called Vect_cat_list_to_array() through ctypes in the pytest process. The bug under test was a null dereference, so on Windows the call died — and because a segfault ends the process, pytest went with it. The Windows suite stopped at 8% with Process completed with exit code 1 and no traceback at all, since pytest's captured output dies with it. @echoix restarted the run twice before I worked out that it was mine and not flakiness.

Running the ctypes calls in a subprocess (subprocess.run([sys.executable, "-c", SCRIPT], env=env, ...) with the env from the standard session fixture, asserting on the return code) turns the same crash into return code -11 in one ordinary test failure, and the rest of the suite survives. That is better even when the test passes, because a suite-killer becomes something you can diagnose.

Worth a short subsection if you agree — the failure mode gives you nothing to go on, so it is hard to work out from first principles. Happy to draft the wording.

[wenzeslaus]

@Pranav-error The C function tests are missing and you are right that it is a important gap to close. I would like to do it later in a separate PR which may include changes to existing tests. You can remind I promised that if I don't follow up on it in the future.

[wenzeslaus]

@Pranav-error I created an issue for you comment about C (and did not assign myself yet): #7862