OBMM Test Framework

OBMM Test Framework is a distributed test framework for OBMM (Ownership Based Memory Management). It is intended to make multi-host OBMM test execution easier, more reproducible, and less dependent on ad hoc per-test orchestration.

This project is licensed under Mulan PSL v2. See LICENSE.

What It Provides

• obmm-test-orchestrator: coordinates test execution across one or more hosts
• obmm-test-conductor: runs on each host, forks local actor processes, and reports results
• libobmm_test.a: framework library that test binaries link against

Quick Start

Prerequisites:

• Linux
• GCC 9+
• CMake 3.10+
• POSIX-compatible runtime environment

Build the repository:

scripts/build.sh

This is the default repository-local verification step for ordinary test and documentation changes. The main artifacts are staged under build/output/.

For framework changes, run the repository-local smoke check when the local machine can create loopback sockets:

scripts/local_smoke.sh

This smoke helper starts two local conductors and one local orchestrator on the same machine and runs a small portable test set. It is primarily intended for framework-maintainer validation rather than as the default check for ordinary test-writer changes.

Build And Runtime Notes

Some tests depend on optional runtime libraries such as libobmm or mami4ubmem.

• direct-link mode builds against the real headers and libraries
• compatibility mode builds against framework-owned compatibility declarations and resolves the real library at runtime

Compatibility mode is the default path for ordinary development on machines that do not have the full runtime stack installed.

For detailed build flags, runtime environment variables, configuration format, and execution flow, see:

• doc/test-writers/usage.md
• doc/test-writers/runtime-dependencies.md

Execution Model

• one orchestrator coordinates the test run
• one conductor runs on each host
• each test case declares its actors and channels
• conductors fork the actors assigned to their host

This is the high-level process model. Detailed protocol and implementation design notes live under doc/framework-maintainers/.

Documentation

Start here depending on what you are doing:

• doc/style-guide.md: shared source formatting and file-structure conventions
• doc/test-writers/usage.md: build, configure, and run distributed tests
• doc/test-writers/api.md: public API used inside test code
• doc/test-writers/runtime-dependencies.md: optional runtime wrappers and compatibility behavior
• doc/test-writers/guidelines.md: test-writing conventions
• doc/README.md: documentation index

Maintainer-facing design notes live under doc/framework-maintainers/.

The repository also includes optional reusable test-writing guidance under .agents/skills/obmm-test-writer/SKILL.md. It is intended as repository-local workflow guidance for test-writer tasks, not as a required part of the runtime or build system.

Repository Layout

• include/framework/: public framework API for test writers
• include/compat/: compatibility headers for optional runtime dependencies
• include/utils/: reusable public helper APIs
• src/framework/: core framework library
• src/conductor/: conductor implementation
• src/orchestrator/: orchestrator implementation
• src/loaders/: optional runtime loading support
• tests/runtime_smoke/: portable smoke tests
• tests/framework_tests/: maintainer-facing framework regression tests
• tests/obmm/: OBMM-specific tests

Agent Notes

Repository-specific agent guidance lives in AGENTS.md. Developers may keep untracked local agent instructions in AGENTS.local.md.