Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

hivesim: Add documentation generation #948

Merged
merged 4 commits into from
Dec 5, 2023
Merged

hivesim: Add documentation generation #948

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7b16bf9
hivesim: Add docs generation
marioevz Nov 21, 2023
71586ad
docs: Add documentation generator info
marioevz Nov 21, 2023
4e84c23
hivesim: docs: preserve suite/test order
marioevz Nov 27, 2023
f931b46
hivesim/docs: cleanup
marioevz Nov 28, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions docs/simulators.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,40 @@ Now create the simulator program file `my-simulation.go`.
// write your test code here
}

### Generating Test Case Documentation

The [package hivesim] provides automatic test case generation that can be used to compile all the
test cases that a given simulator runs into a markdown file.

The documentation can be generated by executing the simulator binary with the environment variable
`HIVE_DOCS_MODE` set to "true".

The document generator recurses into every test suite and test function that the simulator defines
and collects their names and descriptions, as defined in the `hivesim.Suite`, `hivesim.TestSpec`
or `hivesim.ClientTestSpec` objects.

If the test object contains no description, it will not be listed in the documentation generated.

A `TESTS.md` file that serves as an index document will be generated, inside of it a listing of
all the test suites will be included, along with the links to all test suite markdown files.

For every test suite a `TESTS-<Suite Name>.md` file will be generated, containing the listing of
all test cases included in the suite.

The `Location` field of the `hivesim.Suite` can be used to specify a subdirectory where the
markdown file for this given suite will be placed.

The `Category` field of `hivesim.TestSpec` or `hivesim.ClientTestSpec` can be used to generate
test categories in which the test cases will be grouped for readability purposes.

The following environment variables can be used to configure document generation:
- `HIVE_DOCS_MODE`: Enable test case documentation generation (set to "true").
- `HIVE_SIMULATOR_NAME`: Name of the simulator for which the documentation is being generated.
If unset, the path of the simulator executable will be used to parse the simulator's name.
- `HIVE_DOCS_OUTPUT_DIR`: Output root directory for all generated markdown files.
If unset, the current working directory will be used.


### Creating the Dockerfile

The simulator needs to have a Dockerfile in order to run.
Expand Down
1 change: 1 addition & 0 deletions go.mod
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ require (
github.com/evanw/esbuild v0.18.11
github.com/fsouza/go-dockerclient v1.9.8
github.com/gorilla/mux v1.8.0
github.com/lithammer/dedent v1.1.0
golang.org/x/exp v0.0.0-20230905200255-921286631fa9
golang.org/x/net v0.17.0
gopkg.in/inconshreveable/log15.v2 v2.0.0-20200109203555-b30bc20e4fd1
Expand Down
2 changes: 2 additions & 0 deletions go.sum
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -226,6 +226,8 @@ github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0
github.com/labstack/echo/v4 v4.5.0/go.mod h1:czIriw4a0C1dFun+ObrXp7ok03xON0N1awStJ6ArI7Y=
github.com/labstack/gommon v0.3.0/go.mod h1:MULnywXg0yavhxWKc+lOruYdAhDwPK9wf0OL7NoOu+k=
github.com/leanovate/gopter v0.2.9 h1:fQjYxZaynp97ozCzfOyOuAGOU4aU/z37zf/tOujFk7c=
github.com/lithammer/dedent v1.1.0 h1:VNzHMVCBNG1j0fh3OrsFRkVUwStdDArbgBWoPAffktY=
github.com/lithammer/dedent v1.1.0/go.mod h1:jrXYCQtgg0nJiN+StA2KgR7w6CiQNv9Fd/Z9BP0jIOc=
github.com/magiconair/properties v1.8.0/go.mod h1:PppfXfuXeibc/6YijjN8zIbojt8czPbwD3XqdrwzmxQ=
github.com/mattn/go-colorable v0.1.2/go.mod h1:U0ppj6V5qS13XJ6of8GYAs25YV2eR4EVcfRqFIhoBtE=
github.com/mattn/go-colorable v0.1.8/go.mod h1:u6P/XSegPjTcexA+o6vUJrdnUu04hMope9wVRipJSqc=
Expand Down
Loading