feat(example): working serverless example with pact. #166

Author: mefellows

examples/messages/package.json

@@ -15,7 +15,6 @@
   "license": "MIT",
   "devDependencies": {
     "@types/mocha": "^2.2.41",
-    "axios": "^0.14.0",
     "chai": "^3.5.0",
     "mocha": "^3.5.3",
     "nyc": "^11.6.0"

examples/serverless/.gitignore

@@ -1 +1,2 @@
 .serverless
+pacts

examples/serverless/README.md

@@ -1,28 +1,93 @@
 # Serverless example
 
+![serverless-logo](https://user-images.githubusercontent.com/53900/38163394-57ec9176-353f-11e8-80d1-b9f6d5f1773f.png)
+
 Fictional application running using the [Serverless](https://github.com/serverless/serverless) framework.
 
+The very basic architecture is as follows:
+
+`[Event Provider]` -> `[SNS]` <- `[Event Consumer]`
+
+## Overview
+<!-- TOC -->
+
+- [Overview](#overview)
+- [Test Services with Pact](#test-services-with-pact)
+- [Deployment](#deployment)
+  - [Pact Broker integration](#pact-broker-integration)
+  - [Running deployment](#running-deployment)
+- [Running](#running)
+- [Further reading](#further-reading)
+
+<!-- /TOC -->
+
 **Message Producer**
 
-Small utility that takes a request and publishes a message to an SQS queue.
+Small utility that when invoked, publishes an "event" message to an SQS queue.
 
 **Message Consumer**
 
-Lambda function that reads from SQS and processes the data.
+Lambda function that reads from SQS and processes the data - by incrementing a simple counter.
+
+## Test Services with Pact
+
+To run both the consumer and provider pact tests:
+
+```
+npm t
+```
+
+Or individually:
+
+```
+npm run test:consumer
+npm run test:provider
+```
+
+## Deployment
 
+### Pact Broker integration
 
-## Deploy service
+Using the test broker at https://test.pact.dius.com.au (user/pass: `dXfltyFMgNOFZAxr8io9wJ37iUpY42M` / `O5AIZWxelWbLvqMd8PkAVycBJh2Psyg1`), we integrate the `can-i-deploy` facility, that ensure it is safe to deploy the consumer or provider before a change.
 
-Ensure you have valid AWS credentials in your environment, and then run;
+Whenever we verify a contract with Pact, the results are shared with the broker, which is able to determine compatibility between components.
+
+You can see the current state of verification by running one of:
+
+```
+npm run can-i-deploy:consumer
+npm run can-i-deploy:provider
+```
+
+### Running deployment
+
+Ensure you have valid AWS credentials in your environment and have installed serverless framework (`npm i -g serverless`), and then run;
 
 ```sh
-export AWS_ACCOUNT_ID=1234xxxx5678 # Required by function at runtime
-serverless deploy -v
+npm run deploy
+```
+
+This will first check with `can-i-deploy`. If you want to skip this process, you can simply run:
+
+```
+serverless deploy -f provider
+serverless deploy -f consumer
 ```
 
-## How we set this up
+## Running
+
+**Invoking the provider**
+
+```sh
+serverless invoke -f provider -l
+```
 
+**Watching the consumer**
 ```sh
-npm install -g serverless
-serverless create --template aws-nodejs --path sqs-publisher
+serverless logs -f consumer -t
 ```
+
+## Further reading
+
+For further reading and introduction into the topic of asynchronous services contract testing, see this [article](https://dius.com.au/2017/09/22/contract-testing-serverless-and-asynchronous-applications/)
+and our other [example](https://github.com/pact-foundation/pact-js/tree/master/examples/messages) for a more detailed overview of these concepts.

examples/serverless/consumer/consumer.spec.js

@@ -0,0 +1,29 @@
+/* tslint:disable:no-unused-expression object-literal-sort-keys max-classes-per-file no-empty */
+const consumeEvent = require("./index").consumeEvent;
+const { like, term } = require("../../../dist/dsl/matchers");
+const { MessageConsumer, Message, synchronousBodyHandler } = require("../../../dist/pact");
+const path = require("path");
+
+describe("Serverless consumer tests", () => {
+  const messagePact = new MessageConsumer({
+    consumer: "SNSPactEventConsumer",
+    dir: path.resolve(process.cwd(), "pacts"),
+    provider: "SNSPactEventProvider",
+  });
+
+  describe("receive a pact event", () => {
+    it("should accept a valid event", () => {
+      return messagePact
+        .expectsToReceive("a request to save an event")
+        .withContent({
+          id: like(1),
+          event: like("something important"),
+          type: term({ generate: "save", matcher: "^(save|update|cancel)$" }),
+        })
+        .withMetadata({
+          "content-type": "application/json",
+        })
+        .verify(synchronousBodyHandler(consumeEvent));
+    });
+  });
+});

examples/serverless/consumer/index.js

@@ -4,24 +4,38 @@ const AWS = require('aws-sdk');
 
 // Consumer handler, responsible for extracting message from SNS
 // and dealing with lambda-related things.
-module.exports.handler = (event, context, callback) => {
+const handler = (event, context, callback) => {
   console.log("Received event from SNS");
 
   event.Records.forEach(e => {
     console.log("Event:", JSON.parse(e.Sns.Message));
-    consumeEvent(e)
+    consumeEvent(JSON.parse(e.Sns.Message))
   });
 
   callback(null, {
     event
   });
 };
 
+let eventCount = 0;
+
 // Actual consumer code, has no Lambda/AWS/Protocol specific stuff
 // This is the thing we test in the Consumer Pact tests
 const consumeEvent = (event) => {
-
-  // save in dynamo or something...
   console.log('consuming event', event)
 
+  if (!event || !event.id) {
+    throw new Error("Invalid event, missing fields")
+  }
+
+  // You'd normally do something useful, like process it
+  // and save it in Dynamo
+  console.log('Event count:', ++eventCount);
+
+  return eventCount;
 }
+
+module.exports = {
+  handler,
+  consumeEvent
+};

examples/serverless/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "serverless-pact-example",
+  "version": "1.0.0",
+  "description": "Example testing a serverless app with Pact",
+  "main": "index.js",
+  "scripts": {
+    "clean": "if [ -d 'pacts' ]; then rm -rf pacts; fi",
+    "test": "npm run test:consumer && npm run test:publish && npm run test:provider",
+    "test:consumer": "mocha consumer/*.spec.js",
+    "test:provider": "mocha -t 10000 provider/*.spec.js",
+    "test:publish": "node publish.js",
+    "can-i-deploy": "npm run can-i-deploy:consumer && npm run can-i-deploy:provider",
+    "can-i-deploy:consumer": "$(find ../../ -name pact-broker | grep -e 'bin/pact-broker$' | head -n 1) can-i-deploy --pacticipant SNSPactEventConsumer --latest --broker-base-url https://test.pact.dius.com.au --broker-username dXfltyFMgNOFZAxr8io9wJ37iUpY42M --broker-password O5AIZWxelWbLvqMd8PkAVycBJh2Psyg1",
+    "can-i-deploy:provider": "$(find ../../ -name pact-broker | grep -e 'bin/pact-broker$' | head -n 1) can-i-deploy --pacticipant SNSPactEventProvider --latest --broker-base-url https://test.pact.dius.com.au --broker-username dXfltyFMgNOFZAxr8io9wJ37iUpY42M --broker-password O5AIZWxelWbLvqMd8PkAVycBJh2Psyg1",
+    "deploy": "npm run deploy:consumer && npm run deploy:provider",
+    "deploy:consumer": "npm run can-i-deploy && serverless deploy -f consumer",
+    "deploy:provider": "npm run can-i-deploy && serverless deploy -f provider"
+  },
+  "devDependencies": {
+    "chai": "^3.5.0",
+    "mocha": "^3.5.3"
+  },
+  "keywords": [
+    "pact",
+    "serverless",
+    "lambda",
+    "contract-testing"
+  ],
+  "author": "Matt Fellows <matt.fellows@onegeek.com.au>",
+  "license": "MIT",
+  "dependencies": {
+    "aws-sdk": "^2.218.1"
+  }
+}

examples/serverless/publisher/.gitignore renamed to examples/serverless/provider/.gitignore

@@ -7,13 +7,13 @@ const TOPIC_ARN = process.env.TOPIC_ARN;
 // Handler is the Lambda and SNS specific code
 // The message generation logic is separated from the handler itself
 // in the
-module.exports.handler = (event, context, callback) => {
-  const message = createEvent(event);
+const handler = (event, context, callback) => {
+  const message = createEvent();
 
   const sns = new AWS.SNS();
 
   const params = {
-    Message: message.body,
+    Message: JSON.stringify(message),
     TopicArn: TOPIC_ARN
   };
 
@@ -22,7 +22,6 @@ module.exports.handler = (event, context, callback) => {
       callback(error);
     }
 
-    console.log("Message successfully published to queue")
     callback(null, {
       message: 'Message successfully published to SNS topic "pact-events"',
       event
@@ -34,12 +33,16 @@ module.exports.handler = (event, context, callback) => {
 
 // Separate your producer code, from the lambda handler.
 // No Lambda/AWS/Protocol specific stuff in here..
-const createEvent = (event) => {
+const createEvent = (obj) => {
+  // Change 'type' to something else to test a pact failure
   return {
-    statusCode: 200,
-    body: JSON.stringify({
-      message: 'Go Serverless v1.0! Your function executed successfully!',
-      input: event,
-    }),
+    id: parseInt(Math.random() * 100),
+    event: "an update to something useful",
+    type: "update"
   };
 };
+
+module.exports = {
+  handler,
+  createEvent,
+}

examples/serverless/publisher/index.js renamed to examples/serverless/provider/index.js

@@ -0,0 +1,35 @@
+
+/* tslint:disable:no-unused-expression object-literal-sort-keys max-classes-per-file no-empty */
+const { like, term } = require("../../../dist/dsl/matchers");
+const { MessageProvider, Message } = require("../../../dist/pact");
+const path = require("path");
+const { createEvent } = require("./index");
+
+describe("Message provider tests", () => {
+  const p = new MessageProvider({
+    handlers: {
+      "a request to save an event": () => createEvent(),
+    },
+    logLevel: "WARN",
+    provider: "SNSPactEventProvider",
+    providerVersion: "1.0.0",
+
+    // For local validation
+    // pactUrls: [path.resolve(process.cwd(), "pacts", "snspacteventconsumer-snspacteventprovider.json")],
+
+    // Uncomment to use the broker
+    pactBrokerUrl: "https://test.pact.dius.com.au/",
+    pactBrokerUsername: "dXfltyFMgNOFZAxr8io9wJ37iUpY42M",
+    pactBrokerPassword: "O5AIZWxelWbLvqMd8PkAVycBJh2Psyg1",
+    publishVerificationResult: true,
+
+    // Tag the contract
+    tags: ["latest"],
+  });
+
+  describe("send an event", () => {
+    it("should send a valid event", () => {
+      return p.verify();
+    });
+  });
+});

examples/serverless/provider/message-provider.spec.js

@@ -0,0 +1,23 @@
+const pact = require('@pact-foundation/pact-node')
+const path = require('path')
+const opts = {
+  pactFilesOrDirs: [path.resolve(__dirname, 'pacts/')],
+  pactBroker: 'https://test.pact.dius.com.au',
+  pactBrokerUsername: 'dXfltyFMgNOFZAxr8io9wJ37iUpY42M',
+  pactBrokerPassword: 'O5AIZWxelWbLvqMd8PkAVycBJh2Psyg1',
+  tags: ['latest'],
+  consumerVersion: '1.0.1'
+}
+
+pact.publishPacts(opts)
+  .then(() => {
+    console.log('Pact contract publishing complete!')
+    console.log('')
+    console.log('Head over to https://test.pact.dius.com.au/ and login with')
+    console.log('=> Username: dXfltyFMgNOFZAxr8io9wJ37iUpY42M')
+    console.log('=> Password: O5AIZWxelWbLvqMd8PkAVycBJh2Psyg1')
+    console.log('to see your published contracts.')
+  })
+  .catch(e => {
+    console.log('Pact contract publishing failed: ', e)
+  })