readme

Author: hauner

README.adoc

@@ -0,0 +1,118 @@
+:badge-license: https://img.shields.io/badge/License-Apache%202.0-blue.svg?labelColor=313A42
+:badge-ci: https://github.com/hauner/openapi-processor-test/workflows/ci/badge.svg
+:oaps-ci: https://github.com/hauner/openapi-processor-test/actions?query=workflow%3Aci
+:oaps-license: https://github.com/hauner/openapi-processor-test/blob/master/LICENSE
+:oap-docs: https://hauner.github.com/openapi-processor/spring/current/index.html
+:opa-core: https://github.com/hauner/openapi-processor-test
+:opa-spring: https://github.com/hauner/openapi-processor-spring
+
+// badges
+//link:{oaps-ci}[image:{badge-ci}[]]
+link:{oaps-license}[image:{badge-license}[]]
+
+
+== openapi-processor-test
+
+this contains re-usable code and data for testing openapi-processors.
+
+=== test code/data
+
+A test case does an end-to-end test of an openapi-processor.
+
+`resources/tests` contains the input files of a number of tests. The name of the folder is the name
+of the test case.
+
+A test case contains an `openapi.yaml` and  a `mapping.yaml` file in the `inputs` folder. An
+`inputs.yaml` sibling file of the `inputs` folder list the files in the folder.
+
+To provide the expected output of the test case a consumer of oap-test creates a
+`resources/tests/<integration test name>` folder in its *own* resources. Inside it a `generated` folder
+and a `generated.yaml` with the list of expected files in the corresponding folder.
+
+A test case can contain both inputs and outputs. So it is easy to create additional tests without
+touching oap-test.
+
+To run the test cases a consumer creates an `@RunWith(Parameterized)` junit test which extends
+`com.github.hauner.openapi.test.ProcessorTestBase`. The `@Parameterized` method provides the list of
+test cases to run.
+
+==== example
+
+the inputs:
+
+ resources/tests/my-test
+ +--- inputs.yaml
+ \--- inputs
+      +--- mapping.yaml
+      \--- openapi.yaml
+
+the expected files:
+
+ resources/tests/my-test
+ +--- generated.yaml
+ \--- generated
+      +--- api
+      |    \--- EndpointApi.java
+      \--- model
+           \--- Foo.java
+
+the `inputs.yaml` and `generated.yaml` use the same simple format:
+
+ items:
+    - inputs/openapi.yaml
+    - inputs/mapping.yaml
+
+or
+
+ items:
+    - generated/api/EndpointApi.java
+    - generated/model/Foo.java
+
+
+Extending `com.github.hauner.openapi.test.ProcessorTestBase` looks like this (using groovy):
+
+[source,groovy]
+----
+import com.github.hauner.openapi.test.ProcessorTestBase
+import com.github.hauner.openapi.test.TestSet
+
+@RunWith(Parameterized)
+class ProcessorEndToEndTest extends ProcessorTestBase {
+
+    static def ALL = [
+        'test-case',   // this is the folder name in resources/tests
+        // ... more tests
+    ]
+
+
+    @Parameterized.Parameters(name = "{0}")
+    static Collection<TestSet> sources () {
+        def swagger = ALL.collect {
+           new TestSet (name: it, processor: new Processor(), parser: ParserType.SWAGGER.name ())
+        }
+
+        def openapi4j = ALL.collect {
+           new TestSet (name: it, processor: new Processor(), parser: ParserType.OPENAPI4J.name ())
+        }
+
+        swagger + openapi4j
+    }
+
+    ProcessorEndToEndTest (TestSet testSet) {
+        super (testSet)
+    }
+
+    @Test
+    void "native - processor creates expected files for api set "() {
+        runOnNativeFileSystem ()
+    }
+
+}
+----
+
+See link:{oap-core}[openapi-processor-core] and link:{oap-spring}[openapi-processor-spring] for
+working examples.
+
+== openapi-processor Documentation
+
+See link:{oap-docs}[here].