@tryghost/express-test 0.3.0 → 0.5.0

package/lib/expect-request.js

@@ -1,10 +1,29 @@
 const assert = require('assert');
 const {Request, RequestOptions} = require('./request');
 const {snapshotManager} = require('@tryghost/jest-snapshot');
+const {makeMessageFromMatchMessage} = require('./utils');
+
+/**
+ * @typedef {object} ExpressTestAssertion
+ * @prop {function} fn - Wrapped assertion with response context
+ * @prop {string} [message] - The message to display if the assertion fails
+ * @prop {string} [method] - The method to call on the assertion object
+ * @prop {'header' | 'status'} [type] - The type of assertion
+ * @prop {import('assert').AssertionError} [error] - The error to throw if the assertion fails
+ * @prop {any} [expected]
+ * @prop {any} [expectedValue]
+ * @prop {string} [expectedField]
+ * @prop {object} [properties]
+ */
 
 class ExpectRequest extends Request {
     constructor(...args) {
         super(...args);
+
+        /**
+         * @property {ExpressTestAssertion[]} assertions
+         */
+        this.assertions = [];
     }
 
     expect(callback) {
@@ -35,7 +54,8 @@ class ExpectRequest extends Request {
     expectStatus(expected) {
         const assertion = {
             fn: this._assertStatus,
-            expected
+            expected,
+            type: 'status'
         };
 
         this._addAssertion(assertion);
@@ -47,7 +67,8 @@ class ExpectRequest extends Request {
         const assertion = {
             fn: this._assertHeader,
             expectedField: expectedField.toLowerCase(),
-            expectedValue
+            expectedValue,
+            type: 'header'
         };
 
         this._addAssertion(assertion);
@@ -55,7 +76,7 @@ class ExpectRequest extends Request {
         return this;
     }
 
-    matchBodySnapshot(properties) {
+    matchBodySnapshot(properties = {}) {
         let assertion = {
             fn: this._assertSnapshot,
             properties: properties,
@@ -67,11 +88,12 @@ class ExpectRequest extends Request {
         return this;
     }
 
-    matchHeaderSnapshot(properties) {
+    matchHeaderSnapshot(properties = {}) {
         let assertion = {
             fn: this._assertSnapshot,
             properties: properties,
-            field: 'headers'
+            field: 'headers',
+            type: 'header'
         };
 
         this._addAssertion(assertion);
@@ -86,7 +108,7 @@ class ExpectRequest extends Request {
             }
 
             try {
-                if (this.assertions) {
+                if (this.assertions && this.assertions.length) {
                     this._assertAll(response);
                 }
                 return callback(null, response);
@@ -96,13 +118,51 @@ class ExpectRequest extends Request {
         });
     }
 
+    /**
+     * @description Runs through the assertions queue and executes them
+     * in following order:
+     * 1. Assertions with no type, e.g: body snapshot match, generic assertions
+     * 2. Assertions of "header" type
+     * 3. Assertions of "status" type
+     *
+     * The order is here to assert the most informative assertions first and the
+     * least informative ones last. For example status code assertions, usually
+     * are setup first but give the least amount of information needed to
+     * investigate the reason of failure. Same problem with header assertions.
+     * By changing the default order of assertions it's expected to improve
+     * the developer experience creating/debugging tests.
+     *
+     * @param {Object} response - HTTP response object
+     */
     _assertAll(response) {
+        const statusCodeAssertions = [];
+        const headerAssertions = [];
+
         for (const assertion of this.assertions) {
+            if (!['status', 'header'].includes(assertion.type)) {
+                assertion.fn(response, assertion);
+            } else if (assertion.type === 'status') {
+                statusCodeAssertions.push(assertion);
+            } else if (assertion.type === 'header') {
+                headerAssertions.push(assertion);
+            }
+        }
+
+        for (const assertion of headerAssertions) {
+            assertion.fn(response, assertion);
+        }
+
+        for (const assertion of statusCodeAssertions) {
             assertion.fn(response, assertion);
         }
     }
 
+    /**
+     * Adds assertion to the queue of assertions to be performed
+     * @param {ExpressTestAssertion} assertion
+     */
     _addAssertion(assertion) {
+        // We create the error here so that we get a useful stack trace
         let error = new assert.AssertionError({
             message: 'Unexpected assertion error',
             expected: assertion.expected,
@@ -112,7 +172,6 @@ class ExpectRequest extends Request {
         error.contextString = this.reqOptions.toString();
         assertion.error = error;
 
-        this.assertions = this.assertions || [];
         this.assertions.push(assertion);
     }
 
@@ -120,6 +179,11 @@ class ExpectRequest extends Request {
         const {error} = assertion;
 
         error.message = `Expected statusCode ${assertion.expected}, got statusCode ${response.statusCode} ${error.contextString}`;
+
+        if (response.body && response.body.errors && response.body.errors[0].message) {
+            error.message += `\n${response.body.errors[0].message}`;
+        }
+
         error.actual = response.statusCode;
 
         assert.equal(response.statusCode, assertion.expected, error);
@@ -152,13 +216,32 @@ class ExpectRequest extends Request {
     _assertSnapshot(result, assertion) {
         const {properties, field, error} = assertion;
 
-        const match = snapshotManager.match(result[field], properties);
+        if (!result[field]) {
+            error.message = `Unable to match snapshot on undefined field ${field} ${error.contextString}`;
+            error.expected = field;
+            error.actual = 'undefined';
+            assert.notEqual(result[field], undefined, error);
+        }
+
+        const hint = `[${field}]`;
+        const match = snapshotManager.match(result[field], properties, hint);
+
+        Object.keys(properties).forEach((prop) => {
+            const errorMessage = `"response.${field}" is missing the expected property "${prop}"`;
+            error.message = makeMessageFromMatchMessage(match.message(), errorMessage);
+            error.expected = prop;
+            error.actual = 'undefined';
+            error.showDiff = false; // Disable mocha's diff output as it's already present in match.message()
+
+            assert.notEqual(result[field][prop], undefined, error);
+        });
 
         if (match.pass !== true) {
-            const snapshotName = match.message().match(/Snapshot name: `(.*)`/)[1];
+            const errorMessage = `"response.${field}" does not match snapshot.`;
+            error.message = makeMessageFromMatchMessage(match.message(), errorMessage);
             error.expected = match.expected;
             error.actual = match.actual;
-            error.message = `Expected ${field} to match in Snapshot: "${snapshotName}" ${error.contextString}`;
+            error.showDiff = false; // Disable mocha's diff output as it's already present in match.message()
         }
 
         assert.equal(match.pass, true, error);

package/lib/request.js

@@ -67,7 +67,7 @@ class Request {
         const {req, res} = reqresnext(Object.assign({}, reqOptions, {app}), {app});
 
         // This is needed to make error handling work
-        // @TODO: submit this upstream in reqresnext
+        // @TODO: remove once https://github.com/antongolub/reqresnext/issues/31 is solved
         req.socket.destroy = () => { };
         return {req, res};
     }

package/lib/utils.js

@@ -3,3 +3,9 @@ module.exports.isJSON = function isJSON(mime) {
     // but not /json-seq
     return /[/+]json($|[^-\w])/i.test(mime);
 };
+
+module.exports.makeMessageFromMatchMessage = function makeMessageFromMatchMessage(message, errorMessage) {
+    const messageLines = message.split('\n');
+    messageLines.splice(0, 1, errorMessage);
+    return messageLines.join('\n');
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryghost/express-test",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "repository": "https://github.com/TryGhost/framework/tree/main/packages/express-test",
   "author": "Ghost Foundation",
   "license": "MIT",
@@ -20,15 +20,15 @@
   },
   "devDependencies": {
     "c8": "7.11.0",
-    "express": "^4.17.2",
-    "express-session": "^1.17.2",
+    "express": "4.17.2",
+    "express-session": "1.17.2",
     "mocha": "9.2.0",
     "sinon": "13.0.1"
   },
   "dependencies": {
-    "@tryghost/jest-snapshot": "^0.2.0",
+    "@tryghost/jest-snapshot": "^0.3.2",
     "cookiejar": "^2.1.3",
-    "reqresnext": "^1.6.6"
+    "reqresnext": "^1.7.0"
   },
-  "gitHead": "1750e2bdc5b8f659a4439490c79a8c262a74e66f"
+  "gitHead": "e954893434fda3f8c8de1970aaaa6f6a8b297f5d"
 }