@tryghost/express-test 0.4.2 → 0.6.1

package/README.md

@@ -40,6 +40,16 @@ return await agent
 This is an initial version for review. More docs coming if it works :)
 
 
+### Assertion execution order
+The order of *chained* assertion execution is NOT the order they were declared in. The framework follows the priority order of the assertion types:
+1. `expect`
+2. `expectHeader`
+3. `expectStatus`
+
+Meaning, any `expect` declarations would be asserted first following by `expectHeader` and `expectStatus` declarations.
+
+The custom order is here to prioritize assertions with the most context first. The feature was added based on frustrations with frameworks like [superagent](https://github.com/visionmedia/superagent), which didn't provide enough information when the status code assertions failed.
+
 ## Develop
 
 This is a mono repository, managed with [lerna](https://lernajs.io/).

package/index.js

@@ -1 +1,9 @@
 module.exports = require('./lib/agent');
+
+// NOTE: exposing jest-snapshot as a part of express-test to avoid
+//       version missmatching on the client side
+module.exports.snapshot = {
+    mochaHooks: require('@tryghost/jest-snapshot').mochaHooks,
+    any: require('@tryghost/jest-snapshot').any,
+    stringMatching: require('@tryghost/jest-snapshot').stringMatching
+};

package/lib/agent.js

@@ -3,6 +3,14 @@ const ExpectRequest = require('./expect-request');
 const {RequestOptions} = require('./request');
 
 class Agent {
+    /**
+     *
+     * @param {Object} app instance of Express app
+     * @param {Object} [defaults]
+     * @param {string} [defaults.baseUrl]
+     * @param {Object} [defaults.headers]
+     * @param {Object} [defaults.queryParams] - custom query params to append to each request
+     */
     constructor(app, defaults = {}) {
         this.app = app;
         this.defaults = defaults;
@@ -15,6 +23,20 @@ class Agent {
             url = `/${this.defaults.baseUrl}/${url}`.replace(/(^|[^:])\/\/+/g, '$1/');
         }
 
+        if (this.defaults.queryParams) {
+            const searchParams = new URLSearchParams();
+
+            for (const key in this.defaults.queryParams) {
+                searchParams.append(key, this.defaults.queryParams[key]);
+            }
+
+            if (url.includes('?')) {
+                url = `${url}&${searchParams.toString()}`;
+            } else {
+                url = `${url}?${searchParams.toString()}`;
+            }
+        }
+
         return url;
     }
 

package/lib/expect-request.js

@@ -3,9 +3,27 @@ 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 {'body' | 'header' | 'status'} type - The type of assertion, with following priority: body > header > status
+ * @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) {
@@ -25,7 +43,8 @@ class ExpectRequest extends Request {
         };
 
         const assertion = {
-            fn: wrapperFn
+            fn: wrapperFn,
+            type: 'body'
         };
 
         this._addAssertion(assertion);
@@ -36,7 +55,8 @@ class ExpectRequest extends Request {
     expectStatus(expected) {
         const assertion = {
             fn: this._assertStatus,
-            expected
+            expected,
+            type: 'status'
         };
 
         this._addAssertion(assertion);
@@ -48,7 +68,8 @@ class ExpectRequest extends Request {
         const assertion = {
             fn: this._assertHeader,
             expectedField: expectedField.toLowerCase(),
-            expectedValue
+            expectedValue,
+            type: 'header'
         };
 
         this._addAssertion(assertion);
@@ -60,7 +81,8 @@ class ExpectRequest extends Request {
         let assertion = {
             fn: this._assertSnapshot,
             properties: properties,
-            field: 'body'
+            field: 'body',
+            type: 'body'
         };
 
         this._addAssertion(assertion);
@@ -72,7 +94,8 @@ class ExpectRequest extends Request {
         let assertion = {
             fn: this._assertSnapshot,
             properties: properties,
-            field: 'headers'
+            field: 'headers',
+            type: 'header'
         };
 
         this._addAssertion(assertion);
@@ -87,7 +110,7 @@ class ExpectRequest extends Request {
             }
 
             try {
-                if (this.assertions) {
+                if (this.assertions && this.assertions.length) {
                     this._assertAll(response);
                 }
                 return callback(null, response);
@@ -97,12 +120,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 (assertion.type === 'body') {
+                assertion.fn(response, assertion);
+            } else if (assertion.type === 'status') {
+                statusCodeAssertions.push(assertion);
+            } else if (assertion.type === 'header') {
+                headerAssertions.push(assertion);
+            } else {
+                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({
@@ -114,7 +176,6 @@ class ExpectRequest extends Request {
         error.contextString = this.reqOptions.toString();
         assertion.error = error;
 
-        this.assertions = this.assertions || [];
         this.assertions.push(assertion);
     }
 

package/lib/request.js

@@ -1,14 +1,13 @@
 const {default: reqresnext} = require('reqresnext');
 const {CookieAccessInfo} = require('cookiejar');
 const {parse} = require('url');
-const {isJSON, convertKeysToLowerCase} = require('./utils');
+const {isJSON} = require('./utils');
 
 class RequestOptions {
     constructor({method, url, headers, body} = {}) {
         this.method = method || 'GET';
         this.url = url || '/';
-        // TODO: remove convertKeysToLowerCase utility once https://github.com/antongolub/reqresnext/issues/33 is fixed
-        this.headers = convertKeysToLowerCase(headers) || {};
+        this.headers = headers || {};
         this.body = body;
     }
 
@@ -30,8 +29,7 @@ class Request {
     }
 
     header(name, value) {
-        // TODO: remove toLowerCase once https://github.com/antongolub/reqresnext/issues/33 is fixed
-        this.reqOptions.headers[name.toLowerCase()] = value;
+        this.reqOptions.headers[name] = value;
         return this;
     }
 

package/lib/utils.js

@@ -9,13 +9,3 @@ module.exports.makeMessageFromMatchMessage = function makeMessageFromMatchMessag
     messageLines.splice(0, 1, errorMessage);
     return messageLines.join('\n');
 };
-
-module.exports.convertKeysToLowerCase = function (map) {
-    const newMap = {};
-
-    for (const key in map) {
-        newMap[key.toLowerCase()] = map[key];
-    }
-
-    return newMap;
-};

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@tryghost/express-test",
-  "version": "0.4.2",
+  "version": "0.6.1",
   "repository": "https://github.com/TryGhost/framework/tree/main/packages/express-test",
   "author": "Ghost Foundation",
   "license": "MIT",
   "main": "index.js",
   "scripts": {
     "dev": "echo \"Implement me!\"",
-    "test": "NODE_ENV=testing c8 mocha --require ./test/utils/overrides.js './test/**/*.test.js'",
+    "test": "NODE_ENV=testing c8 --all --reporter text --reporter cobertura mocha --require ./test/utils/overrides.js './test/**/*.test.js'",
     "lint": "eslint . --ext .js --cache",
     "posttest": "yarn lint"
   },
@@ -20,15 +20,15 @@
   },
   "devDependencies": {
     "c8": "7.11.0",
-    "express": "^4.17.2",
-    "express-session": "^1.17.2",
-    "mocha": "9.2.0",
+    "express": "4.17.3",
+    "express-session": "1.17.2",
+    "mocha": "9.2.1",
     "sinon": "13.0.1"
   },
   "dependencies": {
-    "@tryghost/jest-snapshot": "^0.3.1",
+    "@tryghost/jest-snapshot": "^0.3.4",
     "cookiejar": "^2.1.3",
-    "reqresnext": "^1.6.6"
+    "reqresnext": "^1.7.0"
   },
-  "gitHead": "fdec1082aa5efa81196205cbcd8a31c61b50c8fa"
+  "gitHead": "3768b2b29fe5c2ae4e535264246bc78933eba372"
 }