@@ -152,6 +152,40 @@ Now create the simulator program file `my-simulation.go`.
152152 // write your test code here
153153 }
154154
155+ ### Generating Test Case Documentation
156+
157+ The [ package hivesim] provides automatic test case generation that can be used to compile all the
158+ test cases that a given simulator runs into a markdown file.
159+
160+ The documentation can be generated by executing the simulator binary with the environment variable
161+ ` HIVE_DOCS_MODE ` set to "true".
162+
163+ The document generator recurses into every test suite and test function that the simulator defines
164+ and collects their names and descriptions, as defined in the ` hivesim.Suite ` , ` hivesim.TestSpec `
165+ or ` hivesim.ClientTestSpec ` objects.
166+
167+ If the test object contains no description, it will not be listed in the documentation generated.
168+
169+ A ` TESTS.md ` file that serves as an index document will be generated, inside of it a listing of
170+ all the test suites will be included, along with the links to all test suite markdown files.
171+
172+ For every test suite a ` TESTS-<Suite Name>.md ` file will be generated, containing the listing of
173+ all test cases included in the suite.
174+
175+ The ` Location ` field of the ` hivesim.Suite ` can be used to specify a subdirectory where the
176+ markdown file for this given suite will be placed.
177+
178+ The ` Category ` field of ` hivesim.TestSpec ` or ` hivesim.ClientTestSpec ` can be used to generate
179+ test categories in which the test cases will be grouped for readability purposes.
180+
181+ The following environment variables can be used to configure document generation:
182+ - ` HIVE_DOCS_MODE ` : Enable test case documentation generation (set to "true").
183+ - ` HIVE_SIMULATOR_NAME ` : Name of the simulator for which the documentation is being generated.
184+ If unset, the path of the simulator executable will be used to parse the simulator's name.
185+ - ` HIVE_DOCS_OUTPUT_DIR ` : Output root directory for all generated markdown files.
186+ If unset, the current working directory will be used.
187+
188+
155189### Creating the Dockerfile
156190
157191The simulator needs to have a Dockerfile in order to run.
0 commit comments