doc: add TESTING.md documenting testing strategy

[spatrang]

Summary

Adds a top-level TESTING.md that serves as the authoritative reference for how ROCgdb is validated and how engineers should write and run tests. This satisfies the org-wide requirement that every component repository document its testing strategy.

What's included

The document is organized into 10 sections and covers the areas requested by the ticket:

• Testing layers overview — the three layers: selftests (unit), the DejaGnu integration testsuite, and performance tests.
• Prerequisites & building for testing — host toolchain, DejaGnu 1.5.3+, and the ROCm/GPU requirements (ROCdbgapi, HIP compiler, --with-amd-dbgapi), with an example development build.
• Unit testing (selftests) — the maintenance selftest mechanism, --enable-unit-tests/GDB_SELF_TEST, gdbsupport/selftest.h, and how selftests are run and wrapped by gdb.gdb/unittest.exp.
• Integration / functional testing — the DejaGnu testsuite layout, make check-gdb with TESTS/RUNTESTFLAGS, output files, result codes, and the ROCm/GPU slice (gdb.rocm/, allow_hip_tests skip logic, GPU lock, the hip board, and the test_rocgdb.py CI runner).
• Performance testing — the gdb.perf/ framework, check-perf, and how baselines/regressions are handled.
• When tests run (CI) — the TheRock GitHub Actions workflows, per-PR/per-push cadence, and skip behavior.
• How to write tests — layer selection, .exp conventions, common helper procs, and what constitutes sufficient coverage.
• Debugging test failures and a quick-command reference.

Notes

• Documentation only — no code or test behavior changes.
• Content was verified against the actual repository (testsuite Makefiles, lib/rocm.exp, boards/hip.exp, .github/scripts/test_rocgdb.py, and the CI workflows).

[lancesix]

This is a good start, but I feel that this document gets into some details that are bound to get out of sync rapidly. It discusses details of some function or script parameters, but I am afraid that those scripts / functions can end-up changing and causing discontinuity here.

[lumachad]

On a first skim, I think the document is too verbose. We need to make it cover the points but be succint. We don't need to talk about dependencies required to test but rather focus on what test strategies we have and a quick summary of what they are, what they look like etc.

[spatrang]

Update: rewrote TESTING.md per review feedback

Thanks for the reviews. I've reworked the document to address the two overarching points — that it was too verbose (@lumachad) and got into specifics that would drift out of sync (@lancesix) — and pushed the update
Key changes:

• Much shorter and strategy-focused (~580 → ~180 lines): a "test strategies at a glance" table plus a brief section per strategy (selftests, DejaGnu functional incl. GPU, performance), when tests run, and how to write tests.
• Defers to upstream as the source of truth: no longer claims to be "authoritative"; links gdb/testsuite/README and the TestingGDB wiki up front, and points to README-ROCM.md / gdb/README for build/dependency details instead of duplicating them.
• Dropped churn-prone specifics (helper-proc listings, script parameter/flag tables, env-var tables); the CI runner now just points at test_rocgdb.py --help.
• Fixed the accuracy issues raised inline: GPU tests are not cleanly skipped on unsupported/mixed hardware (expect real failures), and HSA_COREDUMP_PATTERN was removed.
• Added a short, clearly illustrative .exp skeleton in "How to write tests" so the document still shows what a test looks like, pointing at the real gdb.rocm/ tests as templates.

All individual review comments have been addressed and replied to inline. Please take another look.

[czidev-amd]

Please also check all the symbols in this file, use standard ones, do not use the one from extended ascii set.
Otherwise looks good to me.

[lumachad]

You might want to keep an eye on ROCm/TheRock#6711.

[spatrang]

Update: addressed @czidev-amd's review + light alignment with the ROCm testing-doc standard

Pushed an update:

• ASCII only — replaced all extended-ASCII characters (em dashes and arrows) with plain ASCII; verified none remain.
• Test directories described by meaning rather than a bare list (core gdb.base, architecture gdb.arch, language support gdb.cp/gdb.python, machine interface gdb.mi, backend-specific such as the GPU suite gdb.rocm).
• Parallel runs — added a make -j$(nproc) check-gdb TESTS=... example.
• Testing principles — added a short section (layered validation, local-first, scale to available resources) that mirrors the emerging ROCm testing strategy in Introduce a TESTING.md or docs/development/testing.md file documenting our testing strategy TheRock#6711, which @lumachad pointed to.

On the copyright-banner question: TheRock's testing/CONTRIBUTING/README Markdown docs and ROCgdb's own README-ROCM.md don't carry a banner, so I left it out to match convention — happy to add an SPDX/AMD header if a maintainer prefers (left that thread open).

All other review threads have been addressed and resolved. PTAL.

[czidev-amd]

LGTM,

Feedback

[spatrang]

Update: addressed @palves's comment

• Removed the paragraph about invoking runtest directly; the doc now documents only the make targets (which set up site.exp / -data-directory for you).
• Kept the parallel -j$(nproc) example: as @palves noted, compilation still parallelizes even though GPU test execution is serialized by the GPU lock.

All review threads are resolved. PTAL.

[spatrang]

Update: restructured to follow the ROCm testing-doc outline

Reworked TESTING.md to follow the outline of the emerging ROCm-wide testing strategy in ROCm/TheRock#6711 (adapted, not verbatim):

• Philosophy intro + the existing "upstream is the source of truth" callout.
• Testing principles - make tests accessible during development, use layered validation, scale coverage to available resources, use static analysis for mechanical checks, add reliable tests to required CI.
• Testing changes to ROCgdb - by change type (core/target-independent, AMDGPU/ROCm-specific with the illustrative gdb.rocm/ skeleton, performance-sensitive).
• Testing ROCgdb against ROCm - build with amd-dbgapi, reproducible environments, run the same tests locally and in CI.
• Validating ROCgdb on hardware and in CI - supported GPU hardware, when tests run, reading results / triage.

All earlier review fixes are preserved (ASCII-only, defers to upstream, no build-dep duplication, no direct runtest, GPU-lock/parallel nuance, accurate GPU skip semantics). PTAL.

[lumachad]

A few comments on the current versions. I think this is mostly good. Just need to polish it a bit more and improve the signal to noise ratio.

[spatrang]

Update: addressed @lumachad's review

Pushed changes addressing all comments from the latest review:

• Nightly/on-demand cadence reworded: high-signal suites run per PR; configurations CI cannot cover per PR (e.g. GPU architectures without dedicated per-PR runner capacity) run nightly or on demand.
• Removed the build/runtime-dependency pointer and the TheRock reference from the intro; the page now stays focused on testing and validation.
• "Make tests accessible" reworded to your point: every fix or feature should come with a test that verifies the specific behavior being changed.
• Three test types framed explicitly (unit/selftests, functional, performance); noted selftests are also exercised by the functional testsuite, that functional is where most testing happens, and that perf tests are currently exercised only rarely.
• Serialization reason corrected: GPU tests serialize device access because some GPUs cannot debug multiple processes concurrently (not because hardware is limited). Added the concrete per-PR cadence (gdb.rocm minus corefile on GPU runners, gdb.dwarf2 on CPU, GPU corefile runner coming) under "When tests run".
• Dropped the direct make check-gdb ... invocation (won't work with non-standard library paths); the doc points to running via test_rocgdb.py.
• Removed the illustrative .exp skeleton; the doc now defers to gdb/testsuite/README and to copying an existing gdb.rocm/ test as a template.
• Added ROCR_VISIBLE_DEVICES as the way to restrict a run to a supported device.

[lumachad]

I'm happy with this one as a first draft. We can iterate on it going forward.