@tryghost/express-test 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2013-2022 Ghost Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# Express Test
+
+Rapid express testing without HTTP
+
+## Install
+
+`npm install @tryghost/express-test --save`
+
+or
+
+`yarn add @tryghost/express-test`
+
+
+## Usage
+
+```
+const TestAgent = require('@tryghost/express-test');
+const agent = new TestAgent(app, {defaults});
+```
+
+For the most up-to-date and clear usage info, there's a live working example of this library in action inside `tests/example-app.test.js`.
+
+An instantiated agent can make HTTP-like calls, with a supertest-like chained API to set headers & body and to check status, headers and anything else.
+
+
+```
+const agent = new TestAgent(app)
+
+return await agent
+    .post('/check/')
+    .header('x-check', true) // set a header
+    .body({foo: 'bar'}) // Set the body of the POST
+    .expectStatus(200) // Assert that the response status is 200
+    .expectHeader('x-checked', 'false') // Assert a header is set on the response
+    .expect(({body}) => {
+        // Make any further assertions
+        assert.deepEqual(body, {foo: 'bar'});
+    });
+```
+This is an initial version for review. More docs coming if it works :)
+
+
+## Develop
+
+This is a mono repository, managed with [lerna](https://lernajs.io/).
+
+Follow the instructions for the top-level repo.
+1. `git clone` this repo & `cd` into it as usual
+2. Run `yarn` to install top-level dependencies.
+
+
+## Run
+
+- `yarn dev`
+
+
+## Test
+
+- `yarn lint` run just eslint
+- `yarn test` run lint and tests
+
+
+
+
+# Copyright & License
+
+Copyright (c) 2013-2022 Ghost Foundation - Released under the [MIT license](LICENSE).

package/index.js

@@ -0,0 +1 @@
+module.exports = require('./lib/agent');

package/lib/agent.js

@@ -0,0 +1,49 @@
+const {CookieJar} = require('cookiejar');
+const ExpectRequest = require('./expect-request');
+const {RequestOptions} = require('./request');
+
+class Agent {
+    constructor(app, defaults = {}) {
+        this.app = app;
+        this.defaults = defaults;
+
+        this.jar = new CookieJar();
+    }
+
+    _makeUrl(url) {
+        if (this.defaults.baseUrl) {
+            url = `/${this.defaults.baseUrl}/${url}`.replace(/(^|[^:])\/\/+/g, '$1/');
+        }
+
+        return url;
+    }
+
+    _mergeOptions(method, url, options = {}) {
+        // It doesn't make sense to call this method without these properties
+        if (!method) {
+            throw new Error('_mergeOptions cannot be called without a method'); /* eslint-disable-line no-restricted-syntax */
+        }
+
+        if (!url) {
+            throw new Error('_mergeOptions cannot be called without a url'); /* eslint-disable-line no-restricted-syntax */
+        }
+
+        return new RequestOptions({
+            method,
+            url: this._makeUrl(url),
+            headers: Object.assign({}, this.defaults.headers, options.headers),
+            body: Object.assign({}, this.defaults.body, options.body)
+        });
+    }
+}
+
+['get', 'post', 'put', 'del'].forEach((method) => {
+    Agent.prototype[method] = function (url, options) {
+        if (!url) {
+            throw new Error('Cannot make a request without supplying a url'); /* eslint-disable-line no-restricted-syntax */
+        }
+        return new ExpectRequest(this.app, this.jar, this._mergeOptions(method.toUpperCase(), url, options));
+    };
+});
+
+module.exports = Agent;

package/lib/expect-request.js

@@ -0,0 +1,115 @@
+const assert = require('assert');
+const {Request, RequestOptions} = require('./request');
+
+class ExpectRequest extends Request {
+    constructor(...args) {
+        super(...args);
+    }
+
+    expect(callback) {
+        const wrapperFn = (response, assertion) => {
+            try {
+                callback(response);
+            } catch (error) {
+                error.stack = assertion.error.stack.replace(assertion.error.message, error.message);
+                throw error;
+            }
+        };
+
+        const assertion = {
+            fn: wrapperFn
+        };
+
+        this._addAssertion(assertion);
+
+        return this;
+    }
+
+    expectStatus(expected) {
+        const assertion = {
+            fn: this._assertStatus,
+            expected
+        };
+
+        this._addAssertion(assertion);
+
+        return this;
+    }
+
+    expectHeader(expectedField, expectedValue) {
+        const assertion = {
+            fn: this._assertHeader,
+            expectedField: expectedField.toLowerCase(),
+            expectedValue
+        };
+
+        this._addAssertion(assertion);
+
+        return this;
+    }
+    finalize(callback) {
+        super.finalize((error, response) => {
+            if (error) {
+                return callback(error);
+            }
+
+            try {
+                if (this.assertions) {
+                    this._assertAll(response);
+                }
+                return callback(null, response);
+            } catch (_error) {
+                return callback(_error);
+            }
+        });
+    }
+
+    _assertAll(response) {
+        for (const assertion of this.assertions) {
+            assertion.fn(response, assertion);
+        }
+    }
+
+    _addAssertion(assertion) {
+        let error = new assert.AssertionError({
+            message: 'Unexpected assertion error',
+            expected: assertion.expected,
+            stackStartFn: this._addAssertion
+        });
+
+        error.contextString = this.reqOptions.toString();
+        assertion.error = error;
+
+        this.assertions = this.assertions || [];
+        this.assertions.push(assertion);
+    }
+
+    _assertStatus(response, assertion) {
+        const {error} = assertion;
+
+        error.message = `Expected statusCode ${assertion.expected}, got statusCode ${response.statusCode} ${error.contextString}`;
+        error.actual = response.statusCode;
+
+        assert.equal(response.statusCode, assertion.expected, error);
+    }
+
+    _assertHeader(response, assertion) {
+        const {expectedField, expectedValue, error} = assertion;
+        const actual = response.headers[expectedField];
+        const expectedHeaderString = `${expectedField}: ${expectedValue}`;
+        const actualHeaderString = `${expectedField}: ${actual}`;
+
+        error.expected = expectedHeaderString;
+        error.actual = actualHeaderString;
+
+        error.message = `Expected header "${expectedHeaderString}" to exist but got ${JSON.stringify(response.headers)} ${error.contextString}`;
+        assert.notStrictEqual(actual, undefined, error);
+
+        error.message = `Expected header "${expectedHeaderString}", got ${actualHeaderString} ${error.contextString}`;
+        assert.equal(expectedHeaderString, actualHeaderString, error);
+    }
+}
+
+module.exports = ExpectRequest;
+module.exports.ExpectRequest = ExpectRequest;
+module.exports.RequestOptions = RequestOptions;

package/lib/request.js

@@ -0,0 +1,132 @@
+const {default: reqresnext} = require('reqresnext');
+const {CookieAccessInfo} = require('cookiejar');
+const {parse} = require('url');
+const {isJSON} = require('./utils');
+
+class RequestOptions {
+    constructor({method, url, headers, body} = {}) {
+        this.method = method || 'GET';
+        this.url = url || '/';
+        this.headers = headers || {};
+        this.body = body;
+    }
+
+    toString() {
+        return `${this.method} request on ${this.url}`;
+    }
+}
+
+class Request {
+    constructor(app, cookieJar, reqOptions) {
+        this.app = app;
+        this.reqOptions = reqOptions instanceof RequestOptions ? reqOptions : new RequestOptions(reqOptions);
+        this.cookieJar = cookieJar;
+    }
+
+    body(body) {
+        this.reqOptions.body = body;
+        return this;
+    }
+
+    header(name, value) {
+        this.reqOptions.headers[name] = value;
+        return this;
+    }
+
+    then(resolve, reject) {
+        this.finalize((error, response) => {
+            if (error) {
+                return reject(error);
+            }
+
+            return resolve(response);
+        });
+    }
+
+    /*
+     * This method exists to make it easy to extend this class with ExpectRequest
+     * We use callbacks so we don't need to introduce async/await here which may make things
+     * Difficult and/or confusing with the thennable
+     */
+    finalize(callback) {
+        this._doRequest((error, response) => {
+            if (error) {
+                return callback(error);
+            }
+            return callback(null, response);
+        });
+    }
+
+    _getReqRes() {
+        const {app, reqOptions} = this;
+
+        const {req, res} = reqresnext(Object.assign({}, reqOptions, {app}), {app});
+
+        // This is needed to make error handling work
+        // @TODO: submit this upstream in reqresnext
+        req.socket.destroy = () => { };
+        return {req, res};
+    }
+
+    _buildResponse(res) {
+        const statusCode = res.statusCode;
+        const headers = Object.assign({}, res.getHeaders());
+        const text = res.body ? res.body.toString('utf8') : undefined;
+        let body = {};
+
+        if (isJSON(res.getHeader('Content-Type'))) {
+            body = text && JSON.parse(text);
+        }
+
+        return {statusCode, headers, text, body, response: res};
+    }
+
+    _doRequest(callback) {
+        try {
+            const {req, res} = this._getReqRes();
+
+            this._restoreCookies(req);
+
+            res.on('finish', () => {
+                const response = this._buildResponse(res);
+
+                this._saveCookies(res);
+
+                callback(null, response);
+            });
+
+            this.app(req, res);
+        } catch (error) {
+            callback(error);
+        }
+    }
+
+    _getCookies(req) {
+        const url = parse(req.url);
+
+        const access = new CookieAccessInfo(
+            url.hostname,
+            url.pathname,
+            url.protocol === 'https:'
+        );
+
+        return this.cookieJar.getCookies(access).toValueString();
+    }
+
+    _restoreCookies(req) {
+        req.headers.cookie = this._getCookies(req);
+        return req;
+    }
+
+    _saveCookies(res) {
+        const cookies = res.getHeader('set-cookie');
+
+        if (cookies) {
+            this.cookieJar.setCookies(cookies);
+        }
+    }
+}
+
+module.exports = Request;
+module.exports.Request = Request;
+module.exports.RequestOptions = RequestOptions;

package/lib/utils.js

@@ -0,0 +1,5 @@
+module.exports.isJSON = function isJSON(mime) {
+    // should match /json or +json
+    // but not /json-seq
+    return /[/+]json($|[^-\w])/i.test(mime);
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@tryghost/express-test",
+  "version": "0.1.0",
+  "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 './test/**/*.test.js'",
+    "lint": "eslint . --ext .js --cache",
+    "posttest": "yarn lint"
+  },
+  "files": [
+    "index.js",
+    "lib"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "c8": "7.11.0",
+    "express": "^4.17.2",
+    "express-session": "^1.17.2",
+    "mocha": "9.2.0",
+    "sinon": "13.0.0"
+  },
+  "dependencies": {
+    "cookiejar": "^2.1.3",
+    "reqresnext": "^1.6.6"
+  },
+  "gitHead": "45777c4b5a010293f529f88aea19a81a896ba266"
+}