test(rccl): consolidate host-only microtest framework into test/host by pvallem · Pull Request #9817 · ROCm/rocm-systems

pvallem · 2026-08-07T03:02:21Z

Summary

Consolidate the host-only microtest framework from projects/rccl/test/microtest/ into
projects/rccl/test/host/, co-locating it with the rccl-HostUnitTests suite added in #9320.
Both are no-GPU, hipcc --offload-host-only suites that link neither librccl.so nor the HIP
runtime.

This framework is an example / pattern for writing fast host-only microtests: the test TU
#includes the production .cc under test directly (via a *_CC_PATH macro) and satisfies every
external HIP / nccl* symbol from fakes/, so static helpers and individual failure branches
become reachable with no GPU and no library link. p2p-test.cc (exercising
ipcRegisterBuffer) is the worked example; MICROTEST_README.md documents how to add more.

The framework was originally authored by Matt Hughes (matt.hughes@amd.com) on
origin/users/mahughes/unit-test-ideas, and he is credited as co-author. This PR relocates it onto
develop and merges the two CMakeLists.txt into one.

What moved (`test/microtest/` → `test/host/`)

p2p-test.cc, fakes/{hip,nccl,p2p}_fakes.{cc,h}
standalone/micro_link_stubs.cc → test/host/micro_link_stubs.cc (the standalone/ subdir is
folded in, not kept separate — same host-only build model)
README.md → test/host/MICROTEST_README.md (with standalone/README.md folded in)
Shared helpers stay in test/common/ and are only referenced, not moved
(main_altrsmi.cpp, ProcessIsolatedTestRunner.cpp).

Merged build model

test/host/CMakeLists.txt is dual-mode:

In-RCCL-build (./install.sh -t, via add_subdirectory(host) under BUILD_TESTS): builds
rccl-UnitTestsMicro and registers it with CTest through RCCL's shared category mechanism
(apply_test_category_labels + new test/test_categories_micro.yaml), the same path used by
rccl-UnitTests / rccl-UnitTestsFixtures.
Standalone (cmake -B build -DRCCL_BUILD_DIR=<hipified snapshot>): builds
rccl-HostUnitTests + rccl-UnitTestsMicro from a hipified snapshot; run the binaries directly.

HIP's compile requirements are applied without linking the HIP runtime via
$<TARGET_PROPERTY:hip::*,INTERFACE_INCLUDE_DIRECTORIES/COMPILE_OPTIONS/COMPILE_DEFINITIONS>
(valid at the declared CMake minimum, 3.16), so any un-shimmed HIP call surfaces as a link error.

Header guards

fakes headers converted from #pragma once to explicit #ifndef guards (house style):
RCCL_TEST_HOST_HIP_FAKES_H_, RCCL_TEST_HOST_NCCL_FAKES_H_, RCCL_TEST_HOST_P2P_FAKES_H_.

Coverage

rccl-UnitTestsMicro builds instrumented (llvm source-based coverage). There is no bespoke
wrapper script; MICROTEST_README.md documents rendering a report with ROCm llvm-cov scoped to
the compiled unit (p2p_tmp.cc), including the OCI (generate profraw) → host (render) flow.
The host-only unit-test CI workflow is added separately in #9742.

Coordination with other PRs

test(rccl): host-only unit tests for src/init.cc (AICOMRCCL-1685) #9783 (stacked init microtests on unit-test-ideas) will rebase onto these test/host
paths; keeping the fakes/ subdir pre-empts the test/host/init_stubs.cpp (feature(rccl): AICOMRCCL-1669 rccl-HostUnitTests — CPU-only test binary #9320) vs
fakes/init_stubs.cc (test(rccl): host-only unit tests for src/init.cc (AICOMRCCL-1685) #9783) name collision by path.
ci(rccl): add host-only unit test workflow #9742 (host-only unit-test CI) builds test/host standalone on every PR touching
projects/rccl/**; once it lands, that workflow also compiles rccl-UnitTestsMicro.

Test Result

Standalone (WSL, ROCm 7.2.4, clang-22): rccl-HostUnitTests 275/275 and
rccl-UnitTestsMicro 30/30 pass; ldd shows no rccl / HIP / HSA.
In-RCCL-build (OCI, ROCm 7.0.2, gfx942): ./install.sh --debug -t builds clean; ctest -N
lists the rccl-UnitTestsMicro_* category suites and ctest -R Micro passes; direct run 30/30,
ldd clean.

JIRA ID: AICOMRCCL-1661

therock-pr-bot · 2026-08-07T03:02:57Z

✅ All Policy Checks Passed

Check	Status	Details
📝 PR Description	✅ Pass	—
⛔ Forbidden Files	✅ Pass	—
🧪 Unit Test	✅ Pass	—
🚫 Draft PR	🔜 To Be Enabled	—
🚩 Feature Flag	🔜 To Be Enabled	—
📊 Code Coverage	🔜 To Be Enabled	—

🎉 All policy checks passed!

📖 Need help? See the Policy FAQ for details on every check and how to fix failures.

🙋 Wish to Override Policy?

Move the host-only microtest framework from test/microtest into test/host, where the merged rccl-HostUnitTests suite (PR #9320) already lives. Both are no-GPU, hipcc --offload-host-only suites, so they now share one home and one build entry point. The microtest framework being relocated (p2p-test.cc, fakes/, the in-build and standalone CMake, README, coverage.sh) was originally authored by Matt Hughes on users/mahughes/unit-test-ideas. This commit relocates that work into test/host and merges the two build models. - test/host/CMakeLists.txt is now dual-mode: under BUILD_TESTS (./install.sh -t, via add_subdirectory(host)) it builds only the in-RCCL-build rccl-UnitTestsMicro target and returns; invoked standalone (cmake -B build) it builds rccl-HostUnitTests + rccl-UnitTestsMicro from a hipified snapshot. The microtest/standalone build is folded in (no separate standalone/ dir). - test/CMakeLists.txt gains MICRO_TEST_LINK_LIBS (COMPILE_ONLY hip, no HIP runtime at link) and add_subdirectory(host). - Coverage: in-build -Xarch_device flags use the "SHELL:" prefix so CMake does not de-dup the repeated -Xarch_device and drop host __llvm_covmap. - fakes headers converted from #pragma once to RCCL_TEST_HOST_*_H_ guards (house style); keeping the fakes/ subdir also pre-empts the future init_stubs.cpp vs fakes/init_stubs.cc name collision from #9783. JIRA ID: AICOMRCCL-1661 Co-Authored-By: Matt Hughes <matt.hughes@amd.com>

… coverage.sh Follow-up to the microtest consolidation, addressing review feedback: - Register rccl-UnitTestsMicro with CTest via RCCL's shared category mechanism (apply_test_category_labels + new test/test_categories_micro.yaml), matching how rccl-UnitTests/Fixtures register — the in-build target was installed but never add_test()-registered, so ctest never ran it. Standalone build keeps the #9320 direct-invocation model (documented), no bare add_test. - Replace $<COMPILE_ONLY:hip::host/device> (needs CMake 3.27) with $<TARGET_PROPERTY:hip::*,INTERFACE_INCLUDE_DIRECTORIES/COMPILE_OPTIONS/ COMPILE_DEFINITIONS>, valid at the declared minimum (3.16); still no HIP runtime on the link line. - coverage.sh: parse --html/FUNC before invoking the binary and forward only post-`--` args to gtest (previously --html leaked into the test command); fix the source scope from the non-existent p2p.cc to the compiled unit p2p_tmp.cc (llvm-cov was silently falling back to whole-binary totals); correct the coverage-option docs (MICRO_COVERAGE / in-build unconditional, drop the nonexistent ENABLE_MICROTEST_COVERAGE). - MICROTEST_README.md: replace the "Adding a new test" placeholder with a real section; drop trailing whitespace. JIRA ID: AICOMRCCL-1661

…ctly The coverage.sh convenience wrapper is not used by the build, CI, or CTest and only worked where llvm-cov is present (not on OCI). Remove it and document the equivalent ROCm llvm-cov / llvm-profdata invocations in MICROTEST_README.md, including the OCI (generate profraw) -> host (render) flow and the correct p2p_tmp.cc scoping. Update the p2p-test.cc comment that referenced it. JIRA ID: AICOMRCCL-1661

The microtest framework is an example/pattern for writing host-only tests; avoid citing specific coverage percentages. JIRA ID: AICOMRCCL-1661

- Correct the run example filter to the real test name P2pMicrotest.IpcRegisterBuffer_NullRegRecordIsNoOp (the old IpcRegisterBuffer.NullRegRecordIsNoOp matched zero tests). - Scope the cuMem*/hipMem* dependency advice to the two test models: runtime-linked RCCL targets get hip::host via RCCL_COMMON_LINK_LIBS, whereas rccl-UnitTestsMicro deliberately excludes the HIP runtime and needs a fake/seam instead. Add a warning about link deps not carrying over when moving a test into this hermetic target. JIRA ID: AICOMRCCL-1661

mch

I think it would be good to delete a lot of slop comments otherwise we'll get buried in them over time. One area of duplication related to signature drift detection that should be addressed.

prasanna-amd

Looks good to me.

… trim comments Addresses mch's review on the microtest fakes: - Extract the signature-drift watchdog (FnSigOf/HookMatchesProd templates + ASSERT_HOOK_MATCHES_PROD macro) into fakes/signature-drift.h; nccl_fakes.cc and p2p_fakes.cc now include it and keep only their per-file assertions (removes the duplicated templates/macro). - Fold micro_link_stubs.cc into hip_fakes.cc (Section 2) and drop the separate file; neither host binary links the HIP runtime, so the stubs live in one place. Standalone target no longer lists micro_link_stubs.cc. - Trim verbose comments across hip_fakes.{cc,h}, nccl_fakes.{cc,h}, p2p_fakes.{cc,h} and the README. Binaries intentionally kept separate for now (combining rccl-UnitTestsMicro into rccl-HostUnitTests is a larger change to evaluate separately). Verified: standalone test/host build on WSL (ROCm 7.2.4) — rccl-HostUnitTests 275/275, rccl-UnitTestsMicro 30/30, ldd clean (links without micro_link_stubs.cc). JIRA ID: AICOMRCCL-1661

Co-authored-by: Matt Hughes <matt.hughes@amd.com>

pvallem requested a review from a team as a code owner August 7, 2026 03:02

github-actions Bot added the project: rccl label Aug 7, 2026

pvallem requested review from mch and prasanna-amd August 7, 2026 03:05

systems-assistant Bot added the organization: ROCm label Aug 7, 2026

pvallem force-pushed the users/pvallem/consolidate-host-tests branch from d127254 to f89d541 Compare August 7, 2026 03:09

Prasannakumar Murugesan added 4 commits August 7, 2026 04:39

docs(rccl): drop invented coverage-delta example from microtest README

932ec2a

The microtest framework is an example/pattern for writing host-only tests; avoid citing specific coverage percentages. JIRA ID: AICOMRCCL-1661

mch requested changes Aug 7, 2026

View reviewed changes

prasanna-amd approved these changes Aug 7, 2026

View reviewed changes

pvallem requested a review from a team August 7, 2026 21:00

mch approved these changes Aug 7, 2026

View reviewed changes

Comment thread projects/rccl/test/host/fakes/hip_fakes.cc Outdated

pvallem and others added 3 commits August 7, 2026 15:12

Update projects/rccl/test/host/fakes/hip_fakes.h

95478cb

Co-authored-by: Matt Hughes <matt.hughes@amd.com>

Update projects/rccl/test/host/fakes/hip_fakes.cc

b1d255b

Co-authored-by: Matt Hughes <matt.hughes@amd.com>

Update projects/rccl/test/host/fakes/p2p_fakes.h

63204da

Co-authored-by: Matt Hughes <matt.hughes@amd.com>

This was referenced Aug 7, 2026

ci(rccl): add pre-commit formatting check for projects/rccl #9888

Open

ci(rccl): run perf regression gate on-demand (org /perf-regression) and per-PR #9950

Open

Navigation Menu

Uh oh!

test(rccl): consolidate host-only microtest framework into test/host - #9817

test(rccl): consolidate host-only microtest framework into test/host#9817
pvallem wants to merge 9 commits into
developfrom
users/pvallem/consolidate-host-tests

pvallem commented Aug 7, 2026 •

edited

Loading

Uh oh!

therock-pr-bot Bot commented Aug 7, 2026 •

edited

Loading

Uh oh!

mch left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

prasanna-amd left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

pvallem commented Aug 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What moved (test/microtest/ → test/host/)

Merged build model

Header guards

Coverage

Coordination with other PRs

Test Result

Uh oh!

therock-pr-bot Bot commented Aug 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ All Policy Checks Passed

Uh oh!

mch left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

prasanna-amd left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

pvallem commented Aug 7, 2026 •

edited

Loading

What moved (`test/microtest/` → `test/host/`)

therock-pr-bot Bot commented Aug 7, 2026 •

edited

Loading