From 45198d8d34454cb0374b99784884baeb11b09eb4 Mon Sep 17 00:00:00 2001 From: Matthew Smith Date: Wed, 22 Mar 2023 16:31:09 +0000 Subject: [PATCH] chore: add instructions for implementing the Gherkin tests for a new language generator (#184) --- README.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/README.md b/README.md index 4efc70a..bd4cd9d 100644 --- a/README.md +++ b/README.md @@ -268,6 +268,35 @@ A primary goal of OpenAPI Forge is to provide robust and extensively tested clie In order to test your generator you'll need to choose a suitable test runner (e.g. [Cucumber](https://www.npmjs.com/package/@cucumber/cucumber) for JavaScript). The standard pattern for each test is that it generates a client API using a schema snippet, then validates the generated output. +### Walkthrough for implementing the BDD tests for a new generator + +Test implementations must: + +1. Start with the `test:generators` script in the `package.json` and do these steps in JS: + 1. Move the BDD tests to where they can be read by the rest of the test code. + 1. Pass over control to the target language's implementation of the Gherkin tests. +1. In the target language, implement the step definitions for each of the `.feature` files. Each test must: + 1. Run the openapi-forge command with the schema snippet in each test to produce the generated code. + 1. Prepare the generated code for dynamic use (language dependent). For example: + 1. JS uses dynamic require statements. + 1. Java needs to compile the classes, add them to the classpath, and access them with Reflection. + 1. Implement the rest of the step definitions for the scenario. +1. Output the results in the format expected by the main forge project `generator-tests` command. + +Recommendations for easier development: + +1. Start by looking at just one test in one feature file. The main complexity is getting the generation working. Each subsequent test will be easier to write. +1. To begin with, clean the generated schemas and code manually. Being able to see the generated code for each test will help with debugging. +1. Write the generator first, or in parallel. It would be a hard task to write the Gherkin implementations without a nearly-done generator. +1. Use what the existing generators have done as a guide (noting that the JS and TS ones are easier, and so may not be representative). + +Existing generators: + +1. The JS implementations are easier because we don't need to switch between languages or compile any code: https://github.com/ScottLogic/openapi-forge-javascript/ and + https://github.com/ScottLogic/openapi-forge-typescript both at `features/support/`. +1. C#: https://github.com/ScottLogic/openapi-forge-csharp at `tests/FeaturesTests/`. +1. Java - coming soon! + ## Formatting Ideally the generated output should be 'neatly' formatted in an idiomatic way for the target language. There are a couple of ways to achieve this: