Every GovStack building block will have an API, defined in an OpenAPI Specification (usually swagger.yaml) defined in their /api/ directory.
Every GovStack building block will have several test suites (e.g., the API test suite /test/api-suite/) defined in their /test/ directory.
Every GovStack building block will have several candidate applications with deployment & configuration scripts defined in their /examples directory.
Whenever a commit or pull request is made to a building block repository, all of the test suites inside /test/ will be run against all of the candidate applications inside /examples .
More specifically, compliance is checked by starting and configuring each example application by executing a /examples/yourApp/test_entrypoint.sh --config api-suite script provided by a contributor and then running all test suites against that running application.
Read on to learn more about how to add a new example application for compliance testing, as well as some tips and guidance for how to configure a test_entrypoint.sh file, an adaptor, and underlying deployment and configuration services that will enable yourApp to pass GovStack tests.
(1) Add your candidate to the repo
Clone the repo for the specification you’re checking: git clone firstname.lastname@example.org:GovStackWorkingGroup/bb-workflow.git
Add a folder for your candidate in the /examples directory.
Provide a way for the test runner to launch and configure your application via the execution of a test_entrypoint.sh file. (This will launch your candidate via docker-compose, provide an adaptor—maybe via Caddy, maybe via some other application—and configure it to pass a particular suite of tests.)
(2) Test your compliance locally, develop your adaptor
cd into your candidate’s directory and start your application with ./test_entrypoint.sh
cd into the /test/api-suite directory and install the testing dependencies:
Run the tests
yarn run test
See which are passing and which are failing. Design and develop an adaptor that will enable your candidate application to achieve compliance with more of the tests detailed in this particular suite.
Add link to adaptor design and development guidance
(3) Open a pull request against the official GovStack spec repo
Once you’re happy with your candidate application’s level of compliance, open a PR against the official GovStack spec.
When you open your PR, you’ll see that the test suite now runs against your candidate and reports back your compliance results on CircleCi.
Here we can see that a workflow candidate “Camunda” has been properly configured and is currently passing 0 out of 5 workflow api specification tests.
Request a review on your PR from one of the repository admins.
Going forward, you and other contributors to the specification will be able to see how proposed changes to the API and its associated tests will impact compliance with all “checked in” candidates for a building block.