DO NOT REVIEW - Smoke testing

.eslintignore

@@ -4,4 +4,5 @@ node_modules
 .eslintignore
 .prettierrc.js
 .prettierignore
-.vscode
+.vscode
+test

.gitattributes

@@ -0,0 +1,2 @@
+# Needed for Prettier
+* text eol=lf

.github/workflows/smoke.yml

@@ -0,0 +1,39 @@
+name: Smoke Tests
+
+on:
+  push:
+    branches:
+      - "**"
+  pull_request:
+    branches:
+      - "**"
+
+jobs:
+  smoke-tests:
+    name: Smoke Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out Git repository
+        uses: actions/checkout@v3
+
+      - name: Use Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 16.x
+          cache: 'npm'
+
+      - name: Install Node.js dependencies
+        run: |
+          npm install
+
+      - id: smoke_test
+        name: Smoke Test generator-options, test-generators and forge commands
+        run: |
+          npm run test:smoke
+
+      - id: show_full_log
+        name: Show Full Log
+        if: success() || failure()
+        run: |
+          cat log.txt

.github/workflows/test-forge.yml

@@ -0,0 +1,32 @@
+name: Test Forge
+
+on:
+  push:
+    branches:
+      - "**"
+  pull_request:
+    branches:
+      - "**"
+
+jobs:
+  test-forge:
+    name: Test Forge
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out Git repository
+        uses: actions/checkout@v3
+
+      - name: Use Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 16.x
+          cache: 'npm'
+
+      - name: Install Node.js dependencies
+        run: |
+          npm install
+
+      - name: Test Forge
+        run: |
+          npm test

CICD/compareTestResults.js

@@ -1,6 +1,6 @@
 const fs = require("fs");
 
-const log = require("../src/log.js");
+const log = require("../src/common/log");
 
 log.setLogLevel(log.logLevels.verbose);
 

CICD/updateWebpage.js

@@ -1,6 +1,6 @@
 const fs = require("fs");
 
-const log = require("../src/log.js");
+const log = require("../src/common/log");
 
 // This regex extracts the generator table from README.md.
 const tableRegex =

CONTRIBUTING.md

@@ -67,26 +67,71 @@ Options:
   -h, --help                         display help for command
 ```
 
-If the testing doesn't work you may be using the wrong script-shell configuration in npm. To keep scripts working in both Unix and Windows machines the shell expected in the project is git-bash. To change your shell type you can run the command below, changing the file location if you have your git-bash executable is in a different location:
+### OpenAPI Forge Package
+
+Install openapi-forge as a global package (this is required for running the tests even if you have it git-cloned locally):
 
 ```
-npm config set script-shell "C:\\Program Files\\Git\\bin\\bash.exe"
+$ npm install openapi-forge --global
 ```
 
+### Dependencies on the Forge Project
+
+The generators hardcode the relative path to the generate.js in order to run test-generators. Currently these must be changed manually if the path of generate.js is changed. See this issue: #158.
+
+### GitHub Workflows
+
+The Gherkin tests are run as part of Continuous Integration using `.github/workflows/test.yml`. It runs the tests on every generator, checking for the presence of a generated test results file. It does not check for passing/failing tests. See this issue: #157.
+
 <br>
 
 # Example directory structure for testing to work using default locations
 
-You can have the locations of the forge and generators in custom locations with custom names but you will need to input the relative file paths into the testing commands of the forge nad generators.
+You can have the locations of the forge and generators in custom locations with custom names but you will need to input the relative file paths into the testing commands of the forge and generators.
 Below is the file structure needed to use the testing commands with the default locations:
 
 ```
-|-openapi-forge
+openapi-forge
+|
 |-openapi-forge-typescript
 |-openapi-forge-csharp
 |-openapi-forge-...
 ```
 
+For example, run:
+
+```
+$ openapi-forge test-generators --format json --generators openapi-forge-csharp
+```
+
+You should see an output that looks like this:
+
+```
+{
+  logLevel: '1',
+  format: 'json',
+  generators: [ 'openapi-forge-csharp' ]
+}
+<path>\openapi-forge-csharp
+Starting tests for generator openapi-forge-csharp
+[
+  { testRunStarted: { timestamp: [Object] } },
+  { testCaseStarted: {} },
+  { testCaseFinished: {} },
+  // ....
+  { testRunFinished: { timestamp: [Object] } }
+]
+{
+  "openapi-forge-csharp": {
+    "scenarios": 44,
+    "failed": 0,
+    "passed": 44,
+    "time": 47
+  }
+}
+
+```
+
 <br>
 
 ## Points to remember when contributing

README.md

@@ -61,6 +61,26 @@ Options:
   -h, --help              Display help for command
 ```
 
+Individual generators may have their own options. Try it out:
+
+```
+% openapi-forge generator-options https://github.com/ScottLogic/openapi-forge-javascript.git
+Usage: openapi-forge generator-options <generator>
+
+This generator has a number of additional options which can be supplied when executing the 'forge' command.
+
+Options:
+  --generator.moduleFormat <value>  The module format to use for the generated
+                                    code. (choices: "commonjs", "esmodule",
+                                    default: "commonjs")
+```
+
+and then
+
+```
+% openapi-forge forge https://petstore3.swagger.io/api/v3/openapi.json https://github.com/ScottLogic/openapi-forge-javascript.git --generator.moduleFormat "esmodule"
+```
+
 ## Client generation
 
 In order to generate a client you need a suitable API specification, this can be supplied as a URL or a local file and can be in JSON or YML format. For this tutorial, we’ll use the Swagger Petstore API:
@@ -134,8 +154,8 @@ And that’s it, you’ve successfully generated and used your first client libr
 OpenAPI Forge currently has the following language generators:
 
 - TypeScript - https://github.com/ScottLogic/openapi-forge-typescript
-- C# - https://github.com/murcikan-scottlogic/openapi-forge-csharp
-- JavaScript - https://github.com/murcikan-scottlogic/openapi-forge-javascript
+- C# - https://github.com/ScottLogic/openapi-forge-csharp
+- JavaScript - https://github.com/Scottlogic/openapi-forge-javascript
 
 # Generator development
 
@@ -248,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:

features/response.feature

@@ -229,6 +229,32 @@ Feature: API responses, including model object deserialization
     Then the response should have a property dateOne with value 2013-07-21T00:00:00.000Z
     And the response should have a property dateTwo with value 2012-07-21T00:00:00.000Z
 
+  Scenario: the API returns headers
+    Given an API with the following specification
+    """
+    {
+      "openapi":"3.0.2",
+      "info" : {"title": "test", "version": "0.0.0"},
+      "paths": {
+        "/test/get": {
+          "get": {
+            "operationId": "getResponse",
+            "responses": {
+              "200": {
+                "description": "successful operation"
+              }
+            }
+          }
+        }
+      }
+    }
+    """
+    When calling the method getResponse and the server responds with headers
+    """
+    {"foo": "bar"}
+    """
+    Then the response should have a header foo with value bar
+
   Scenario: a response that lacks content
     Given an API with the following specification
     """

features/tags.feature

@@ -29,7 +29,7 @@ Feature: Grouping of paths by tags
     Then the api file with tag "" exists
     And the method "getResponse" should be present in the api file with tag ""
 
-    Scenario: Path with a tag = "" is present in a tagless API file
+  Scenario: Path with a tag = "" is present in a tagless API file
     Given an API with the following specification
     """
     {
@@ -58,7 +58,7 @@ Feature: Grouping of paths by tags
     Then the api file with tag "" exists
     And the method "getResponse" should be present in the api file with tag ""
 
-    Scenario: Path with no tag array is present in a tagless API file
+  Scenario: Path with no tag array is present in a tagless API file
     Given an API with the following specification
     """
     {
@@ -86,7 +86,7 @@ Feature: Grouping of paths by tags
     Then the api file with tag "" exists
     And the method "getResponse" should be present in the api file with tag ""
 
-    Scenario: Path with no tag is not present in a tagged API file
+  Scenario: Path with no tag is not present in a tagged API file
     Given an API with the following specification
     """
     {
@@ -170,7 +170,7 @@ Feature: Grouping of paths by tags
     And the method "doNotGetResponse3" should be present in the api file with tag ""
     And the method "doNotGetResponse3" should not be present in the api file with tag "tag"
 
-    Scenario: Path with multiple tags is present in first tag's API file
+  Scenario: Path with multiple tags is present in first tag's API file
     Given an API with the following specification
     """
     {
@@ -201,7 +201,7 @@ Feature: Grouping of paths by tags
     And the api file with tag "" does not exist
     Then the method "getResponse" should be present in the api file with tag "tag"
 
-    Scenario: Path with multiple tags is not present in second tag's API file
+  Scenario: Path with multiple tags is not present in second tag's API file
     Given an API with the following specification
     """
     {