Skip to content

Latest commit

 

History

History
85 lines (62 loc) · 3.75 KB

CONTRIBUTING.md

File metadata and controls

85 lines (62 loc) · 3.75 KB

Project structure

Structure in flux currently, please see #1195: Proposal to modularize the guardrail repo

  • root: Contains tests and nothing else
    • codegen: Codegen core. Defines algebras and default interpreters.
    • sample: Contains integration tests for generated code. May be generated via example in the sbt console.

Coding guidelines

Writing integration Tests

It is difficult to tell if the code generated by the tool is functional and type sound by structure alone. As unit tests are not enough, integration tests actually run guardrail as a CLI tool to generate complete clients and servers, ensuring everything works as expected.

The projects defined at modules/sample-* contain:

  • target/generated: Sources generated by runScalaExample or runJavaExample
  • src/main: Support definitions for generated code
  • src/test: Manually written integration tests against the generated code. These tests are run by the runtimeScalaSuite, runtimeJavaSuite, or the integration testSuite command.

By running guardrail, then attempting to compile the generated code, then running integration tests against the generated code, we can ensure quality.

Adding a new swagger spec

Adding new specifications is accomplished by:

  • creating a file in modules/sample/src/main/resources
  • adding an entry in exampleCases defined in build.sbt. The available flags are largely undocumented, so reading the parser is necessary.
val exampleCases: List[ExampleCase] = List(
  ExampleCase(sampleResource("additional-properties.yaml"), "additionalProperties"),
  ExampleCase(sampleResource("petstore.json"), "examples").args("--import", "support.PositiveLong"),
  ExampleCase(sampleResource("polymorphism-nested.yaml"), "polymorphismNested").frameworks(Set("akka-http", "endpoints", "http4s"))
)
  • First argument has to point to the newly added specification file. sampleResource looks up the specification in modules/sample/src/main/resources
  • Second argument defines what package to put the specification into (For regression tests, issues.issue1234)
  • .args(...) is variadic, and concatenates the specified args directly to the end of your command
  • .frameworks(...) is the set of frameworks that this file should be run against

Adding tests

Define your tests in ./modules/sample-*/src/test/scala make sure to use imports corresponding the previously defined packageName

Running the tests

Use the runtimeSuite command inside of an SBT session to run code generation and execute the tests

Useful commands inside sbt console

  • testSuite: Compile, test codegen, run sample codegen, compile sample, run tests inside sample
  • runtimeSuite: Run guardrail, then run all tests against the generated code
  • cli: Useful for scripting: sbt 'cli --client ...'
  • format: Runs scalafmt against codebase
  • checkFormatting: Verifies formatting, run as part of CI against PRs
  • mdoc: Generate the doc microsite locally

Resources