generate-xunit-tests

name	generate-xunit-tests
description	Generates unit tests using the Polyspace XUnit framework (PSTUnit). Use when the user asks to "generate unit tests", "write tests", "PSTUnit", "Polyspace XUnit", or wants to create C/C++ unit tests.
license	MathWorks BSD-3-Clause
metadata	{"version":"1.0"}

How to Generate Polyspace XUnit Tests

Step-by-step guide to write and build unit tests using the Polyspace XUnit framework (PSTUnit).

1. Create a test plan

Before writing tests, analyze the function under test to create a test plan covering:

• Main functionalities: Nominal execution paths with valid inputs.
• Error cases: Invalid inputs, boundary violations, and error handling paths.
• Edge cases: Boundary values, empty inputs, maximum/minimum values, null pointers.

User approval required: Present the test plan to the user and wait for their approval before proceeding to the next step. Refine the plan if the user requests changes.

2. Get the XUnit API documentation

Read reference/xunit_api_c.md (for C projects) or reference/xunit_api_cpp.md (for C++ projects) in this folder to get the PSTUnit API reference.

3. Author the test code

• Include the pstunit header (pstunit.h) in your test file.
• Add a main() function that returns PST_MAIN(argc, argv).
• In C, register each test in main() with PST_ADD_TEST before calling PST_MAIN. In C++, tests are auto-registered so no PST_ADD_TEST is needed.
• Use the XUnit API macros and functions to define test cases and test suites.
• Include the headers of the functions under test.
• Create one test case per scenario from the test plan.

Commenting conventions:

• Start the test file with a comment block describing its purpose: what module/function is tested and what the file covers.
• Before each test case, add a brief comment stating the goal of that test point.
• Inside each test case, add short comments describing the setup/initialization, the action being performed, and what is being verified.

4. Build the test

To build, compile the pstest.c source file (or pstunit.c for Polyspace versions older than R2026b) alongside your test file, adding the pstunit include directory. Use the same compiler and flags as the project under test to ensure compatibility. If the build fails, analyze and fix the errors, then rebuild. Iterate until the build succeeds.

Build command example (C):

gcc <test_file> <polyspace_root>/polyspace/pstest/pstunit/src/pstest.c \
    -I<polyspace_root>/polyspace/pstest/pstunit/include -o test_executable

Build command example (C++):

g++ <test_file> <polyspace_root>/polyspace/pstest/pstunit/src/pstest.c \
    -I<polyspace_root>/polyspace/pstest/pstunit/include -o test_executable

How to find <polyspace_root>

<polyspace_root> is the Polyspace installation root — the directory that contains the polyspace/ folder.

1. Check the $POLYSPACE_ROOT environment variable: echo $POLYSPACE_ROOT
2. If not set, derive it from a Polyspace binary in PATH: POLYSPACE_ROOT=$(cd "$(dirname "$(which polyspace-as-you-code)")/../.." && pwd)
3. If neither works, ask the user for the Polyspace installation path.

Do NOT use find / or broad filesystem searches — they will hang on network or snapshot filesystems.

5. Run the test

User approval required: Before running the test executable, you MUST ask for the user's explicit permission. These tests are generated by an LLM and may contain unintended side effects. The user must review and approve execution.

Once approved, run the executable. If tests fail at runtime, fix the code and repeat from step 4.

---

Copyright 2026 The MathWorks, Inc.

---