feat: add test template files

Author: mefellows

src/pact.test.template

@@ -0,0 +1,66 @@
+import { SpecificationVersion, PactV4, MatchersV3 } from "@pact-foundation/pact";
+import { ThingAPI } from './thing'
+
+// Extract matchers here to improve readability when used in the test
+const { like } = MatchersV3;
+
+// Create a 3 level test hierarchy
+//
+// 1. Top level describe block containing the name of the API being tested
+// 2. Describe block for the specific API endpoint
+// 3. Test block for the specific test case
+// 4. Execute the test case
+// 5. Call the API under test
+// 6. Assert the response
+// 8. Use Pact matchers to constrain and test the Provider response
+// 7. Use Jest matchers to assert the API client behaviour
+
+// Top level - name of the API
+describe("Thing API", () => {
+  // Use the PactV4 class, and serialise the Pact as V4 Pact Specification
+  const pact = new PactV4({
+    consumer: "ThingConsumer",
+    provider: "ThingProvider",
+    spec: SpecificationVersion.SPECIFICATION_VERSION_V4,
+  });
+
+  // Level 2 - Describe block for the specific API endpoint
+  describe("GET /thing/:id", () => {
+
+    // Level 3 - Test block for the specific test case
+    test("given a valid thing, returns 200", async () => {
+      await pact
+        .addInteraction()
+        .given("a thing with id 1 exists")
+        .uponReceiving("a request for a valid thing")
+        // Avoid matchers on the request unless necessary
+        .withRequest("GET", "/thing/1", (builder) => {
+          builder.headers({ Accept: "application/json" });
+        })
+        .willRespondWith(200, (builder) => {
+          // Use loose matchers where possible, to avoid unnecessary constraints on the provider
+          builder.jsonBody(
+            like({
+              id: 1,
+              name: "Thing 1",
+              price: 100,
+            })
+          );
+        })
+        .executeTest(async (mockserver) => {
+          // Instantiate the ThingAPI client
+          const ThingAPI = new ThingAPI(mockserver.url);
+
+          // Call the API under test
+          const Thing = await ThingAPI.getThingById(1);
+
+          // Use Jest matchers to assert the response
+          expect(Thing).toEqual({
+            id: 1,
+            name: "Some 1",
+            price: 100,
+          });
+        });
+    });
+  });
+});

src/test.instructions.txt

@@ -0,0 +1,8 @@
+* Use the Jest testing framework
+* Use the native Jest expect (https://jestjs.io/docs/expect) matchers such as `toEqual` and `toBeTruthy`
+* Prefer the use of the async/await pattern when using Promises
+* Use the PactV4 interface
+* Use a 3 level hierarchy for tests
+  1. Level 1 should be the API under test as a `describe` block e.g. "Product API"
+  2. Level 2 should be the endpoint as a `describe` block e.g. "GET /products/:id", "POST /products"
+  3. Level 3 should be the scenario as a `test` block e.g. "Given a valid user, returns a 200", "Given an invalid user, returns a 400"