chore(docs): add detailed code comments to help guide new users

examples/e2e/.eslintrc.yml

@@ -14,4 +14,5 @@ rules:
 env:
   es6: true
   node: true
+  mocha: true
 extends: 'eslint:recommended'

examples/e2e/consumer.js

@@ -3,15 +3,26 @@ const request = require('superagent-bluebird-promise');
 const server = express();
 const API_HOST = process.env.API_HOST || 'http://localhost:8081';
 
+// Fetch animals who are currently 'available' from the
+// Animal Service
 const availableAnimals = () => {
   return request
     .get(`${API_HOST}/animals/available`)
     .then(res => res.body,
       () => []);
 };
 
+// Find animals by their ID from the Animal Service
+const getAnimalById = (id) => {
+  return request
+    .get(`${API_HOST}/animals/${id}`)
+    .then(res => res.body,
+      () => null);
+};
+
 // Suggestions function:
-// Given availability and sex etc. find available suitors.
+// Given availability and sex etc. find available suitors,
+// and give them a 'score'
 const suggestion = mate => {
   const predicates = [
     ((candidate, animal) => candidate.id !== animal.id),
@@ -41,14 +52,7 @@ const suggestion = mate => {
   });
 };
 
-const getAnimalById = (id) => {
-  return request
-    .get(`${API_HOST}/animals/${id}`)
-    .then(res => res.body,
-      () => null);
-};
-
-// API
+// Suggestions API
 server.get('/suggestions/:animalId', (req, res) => {
   if (!req.params.animalId) {
     res.writeHead(400);

examples/e2e/provider.js

@@ -14,8 +14,9 @@ server.use((req, res, next) => {
   next();
 });
 
-// Load data into a repository
 const animalRepository = new Repository();
+
+// Load default data into a repository
 const importData = () => {
   const data = require('./data/animalData.json');
   data.reduce((a, v) => {
@@ -25,8 +26,7 @@ const importData = () => {
   }, 0);
 };
 
-// Suggestions function:
-// Given availability and sex, find available suitors...
+// List all animals with 'available' eligibility
 const availableAnimals = () => {
   return animalRepository.fetchAll().filter(a => {
     return a.eligibility.available;
@@ -38,7 +38,7 @@ server.get('/animals', (req, res) => {
   res.json(animalRepository.fetchAll());
 });
 
-// Get all animals
+// Get all available animals
 server.get('/animals/available', (req, res) => {
   res.json(availableAnimals());
 });

examples/e2e/test/consumer.spec.js

@@ -9,10 +9,6 @@ const LOG_LEVEL = process.env.LOG_LEVEL || 'WARN';
 
 chai.use(chaiAsPromised);
 
-// Configure and import consumer API
-process.env.API_HOST = `http://localhost:${MOCK_SERVER_PORT}`;
-const { suggestion, getAnimalById } = require('../consumer');
-
 describe('Pact', () => {
   let provider;
 
@@ -27,8 +23,6 @@ describe('Pact', () => {
     log: path.resolve(process.cwd(), 'logs', 'mockserver-integration.log'),
     dir: path.resolve(process.cwd(), 'pacts'),
     spec: 2
-    // consumer: "MatchingService",
-    // provider: "AnimalProfileService"
   });
   mockservice.logLevel(LOG_LEVEL);
 
@@ -57,14 +51,22 @@ describe('Pact', () => {
 
   const MIN_ANIMALS = 2;
 
-  // Define animal list payload, with flexible matchers
+  // Define animal payload, with flexible matchers
+  // 
+  // This makes the test much more resilient to changes in actual data.
+  // Here we specify the 'shape' of the object that we care about.
+  // It is also import here to not put in expectations for parts of the 
+  // API we don't care about
   const animalBodyExpectation = {
     'id': like(1),
     'first_name': like('Billy'),
     'last_name': like('Goat'),
     'animal': like('goat'),
     'age': like(21),
-    'gender': term({ matcher: 'F|M', generate: 'M' }),
+    'gender': term({
+      matcher: 'F|M',
+      generate: 'M'
+    }),
     'location': {
       'description': like('Melbourne Zoo'),
       'country': like('Australia'),
@@ -76,15 +78,26 @@ describe('Pact', () => {
     },
     'interests': eachLike('walks in the garden/meadow')
   };
-  const animalListExpectation = eachLike(animalBodyExpectation, { min: MIN_ANIMALS });
 
-  // Start mock server before unit tests
+  // Define animal list payload, reusing existing object matcher
+  const animalListExpectation = eachLike(animalBodyExpectation, {
+    min: MIN_ANIMALS
+  });
+
+  // Setup a Mock Server before unit tests run.
+  // This server acts as a Test Double for the real Provider API.
+  // We call addInteraction() to configure the Mock Service to act like the Provider
+  // It also sets up expectations for what requests are to come, and will fail
+  // if the calls are not seen.
   before(done => {
     mockServer.start()
       .then(() => {
-        provider = pact({ consumer: 'Matching Service', provider: 'Animal Profile Service', port: MOCK_SERVER_PORT });
+        provider = pact({
+          consumer: 'Matching Service',
+          provider: 'Animal Profile Service',
+          port: MOCK_SERVER_PORT
+        });
 
-        // Add interactions
         return provider.addInteraction({
           state: 'Has some animals',
           uponReceiving: 'a request for all animals',
@@ -94,7 +107,9 @@ describe('Pact', () => {
           },
           willRespondWith: {
             status: 200,
-            headers: { 'Content-Type': 'application/json; charset=utf-8' },
+            headers: {
+              'Content-Type': 'application/json; charset=utf-8'
+            },
             body: animalListExpectation
           }
         });
@@ -122,7 +137,9 @@ describe('Pact', () => {
           },
           willRespondWith: {
             status: 200,
-            headers: { 'Content-Type': 'application/json; charset=utf-8' },
+            headers: {
+              'Content-Type': 'application/json; charset=utf-8'
+            },
             body: animalBodyExpectation
           }
         });
@@ -134,7 +151,19 @@ describe('Pact', () => {
       });
   });
 
-  // Verify service client works as expected
+  // Configure and import consumer API
+  // Note that we update the API endpoint to point at the Mock Service
+  process.env.API_HOST = `http://localhost:${MOCK_SERVER_PORT}`;
+  const {
+    suggestion,
+    getAnimalById
+  } = require('../consumer');
+
+  // Verify service client works as expected.
+  //
+  // Note that we don't call the consumer API endpoints directly, but 
+  // use unit-style tests that test the collaborating function behaviour - 
+  // we want to test the function that is calling the external service.
   describe('when a call to list all animals from the Animal Service is made', () => {
     describe('and there are animals in the database', () => {
       it('returns a list of animals', done => {
@@ -151,7 +180,6 @@ describe('Pact', () => {
         const suggestedMates = getAnimalById(1);
 
         expect(suggestedMates).to.eventually.have.deep.property('id', 1).notify(done);
-        // expect(suggestedMates).to.eventually.have.property('suggestions').with.lengthOf(MIN_ANIMALS).notify(done);
       });
     });
     describe('and there no animals in the database', () => {

examples/e2e/test/publish.js

@@ -1,7 +1,7 @@
 const pact = require('@pact-foundation/pact-node');
 const path = require('path');
 const opts = {
-  pactUrls: [path.resolve(__dirname, '../pacts/matching_service-animal_profile_service.json')], // Array of local Pact files or directories containing them. Required.
+  pactUrls: [path.resolve(__dirname, '../pacts/matching_service-animal_profile_service.json')],
   pactBroker: 'https://test.pact.dius.com.au',
   pactBrokerUsername: 'dXfltyFMgNOFZAxr8io9wJ37iUpY42M',
   pactBrokerPassword: 'O5AIZWxelWbLvqMd8PkAVycBJh2Psyg1',