@@ -70,3 +70,82 @@ The following adapter matcher objects are available:
7070* ` uur::CUDA `
7171* ` uur::HIP `
7272* ` uur::NativeCPU `
73+
74+ ## Writing a new CTS test
75+
76+ If you're writing a new CTS test you'll need to make use of the existing test
77+ fixtures and instantiation macros to access the adapters available for testing.
78+ The definitions for these can all be found in
79+ [ fixtures.h] ( https://github.com/oneapi-src/unified-runtime/blob/main/test/conformance/testing/include/uur/fixtures.h ) .
80+
81+ There are five "base" fixtures in that header that each correspond to an
82+ instantiation macro - specific macros are needed due to how gtest handles
83+ parameterization and printing. All of these make use of gtest's [ value
84+ parameterization] ( http://google.github.io/googletest/advanced.html#how-to-write-value-parameterized-tests )
85+ to instantiate the tests for all the available backends. Two of the five base
86+ fixtures have a wrapper to allow for tests defining their own parameterization.
87+
88+ The base fixtures and their macros are detailed below. Tests inheriting from
89+ fixtures other than the base ones (` urContextTest ` , etc.) must be instantiated
90+ with the macro that corresponds to whatever base class is ultimately being
91+ inherited from. In the case of ` urContextTest ` we can see that it inherits
92+ directly from ` urDeviceTest ` , so we should use the ` urDeviceTest ` macro. For
93+ other fixtures you'll need to follow the inheritance back a few steps to figure
94+ it out.
95+
96+ ### ` urAdapterTest `
97+
98+ This fixture is intended for tests that will be run once for each adapter
99+ available. The only data member it provides is a ` ur_adapter_handle_t ` .
100+
101+ Instantiated with the ` UUR_INSTANTIATE_ADAPTER_TEST_SUITE ` macro.
102+
103+ ### ` urPlatformTest `
104+
105+ This fixture is intended for tests that will be run once for each platform
106+ available (note the potentially one-to-many relationship between adapters and
107+ platforms). The only data member it provides is a ` ur_platform_handle_t ` .
108+
109+ Instantiated with the ` UUR_INSTANTIATE_PLATFORM_TEST_SUITE ` macro.
110+
111+ ### ` urDeviceTest `
112+
113+ This fixture is intended for tests that will be run once for each device
114+ available. It provides a ` ur_adapter_handle_t ` , ` ur_platform_handle_t ` and a
115+ ` ur_device_handle_t ` (the former two corresponding to the latter).
116+
117+ Instantiated with the ` UUR_INSTANTIATE_DEVICE_TEST_SUITE ` macro.
118+
119+ ### ` urPlatformTestWithParam `
120+
121+ This fixture functions the same as ` urPlatformTest ` except it allows value
122+ parameterization via a template parameter. Note the parameter you specify is
123+ accessed with ` getParam() ` rather than gtest's ` GetParam() ` . A platform handle
124+ is provided the same way it is in the non-parameterized variant.
125+
126+ Instantiated with the ` UUR_PLATFORM_TEST_SUITE_WITH_PARAM ` macro, which, in
127+ addition to the fixture, takes a ` ::testing::Values ` list of parameter values
128+ and a printer (more detail about that below).
129+
130+ ### ` urDeviceTestWithParam `
131+
132+ As with the parameterized platform fixture this functions identically to
133+ ` urDeviceTest ` with the addition of the template parameter for
134+ parameterization.
135+
136+ Instantiated with the ` UUR_DEVICE_TEST_SUITE_WITH_PARAM ` macro.
137+
138+ ### Parameter printers
139+
140+ When instantiating tests based on the parameterized fixtures you need to
141+ provide a printer function along with the value list. This determines how the
142+ parameter values are incorporated into the test name. If your parameter type
143+ has a ` << ` operator defined for it, you can simply use the
144+ ` platformTestWithParamPrinter ` /` deviceTestWithParamPrinter ` helper functions for
145+ this.
146+
147+ If you find yourself needing to write a custom printer function, bear in mind
148+ that due to the parameterization wrapper it'll need to deal with a tuple
149+ containing the platform/device information and your parameter. You should
150+ reference the implementations of ` platformTestWithParamPrinter ` and
151+ ` deviceTestWithParamPrinter ` to see how this is handled.
0 commit comments