jest-matcher-http 1.0.1

package/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

package/.eslintrc.js

@@ -0,0 +1,84 @@
+'use strict';
+
+module.exports = {
+  env: {
+    node: true,
+    'jest/globals': true,
+  },
+  extends: [
+    'airbnb-base',
+    'plugin:jsdoc/recommended',
+    'plugin:jest/recommended',
+    'plugin:jest/style',
+  ],
+  plugins: ['jest'],
+  overrides: [],
+  parserOptions: {
+    ecmaVersion: 2020,
+    sourceType: 'script', // https://github.com/eslint/eslint/issues/5301#issuecomment-184720161
+  },
+  rules: {
+    strict: ['error', 'global'], // Needed: https://github.com/airbnb/javascript/issues/722
+    'jsdoc/check-types': 'error',
+    'jsdoc/check-property-names': 'error',
+    'jsdoc/check-param-names': 'error',
+    'jsdoc/check-tag-names': 'error',
+    'jsdoc/check-alignment': 'error',
+    'jsdoc/check-indentation': 'error',
+    'jsdoc/empty-tags': 'error',
+    'jsdoc/newline-after-description': 'error',
+    'jsdoc/require-description-complete-sentence': [
+      'error',
+      { abbreviations: ['etc', 'e.g.', 'i.e.'] },
+    ],
+    'jsdoc/require-description': 'error',
+    'jsdoc/require-hyphen-before-param-description': 'error',
+    'jsdoc/require-jsdoc': 'error',
+    'jsdoc/require-param-description': 'error',
+    'jsdoc/require-param-name': 'error',
+    'jsdoc/require-param-type': 'error',
+    'jsdoc/require-param': 'error',
+    'jsdoc/require-property': 'error',
+    'jsdoc/require-property-description': 'error',
+    'jsdoc/require-property-name': 'error',
+    'jsdoc/require-property-type': 'error',
+    'jsdoc/require-returns-check': 'error',
+    'jsdoc/require-returns-description': 'error',
+    'jsdoc/require-returns-type': 'error',
+    'jsdoc/require-returns': 'error',
+    'jsdoc/valid-types': 'error',
+    'jest/consistent-test-it': 'error',
+    'jest/expect-expect': 'error',
+    'jest/prefer-lowercase-title': 'error',
+    'jest/no-alias-methods': 'error',
+    'jest/no-commented-out-tests': 'error',
+    'jest/no-conditional-expect': 'error',
+    'jest/no-disabled-tests': 'error',
+    'jest/no-duplicate-hooks': 'error',
+    'jest/no-export': 'error',
+    'jest/no-focused-tests': 'error',
+    'jest/no-identical-title': 'error',
+    'jest/no-if': 'error',
+    'jest/no-jasmine-globals': 'error',
+    'jest/no-mocks-import': 'error',
+    'jest/no-restricted-matchers': 'error',
+    'jest/no-standalone-expect': 'error',
+    'jest/no-test-return-statement': 'error',
+    'jest/prefer-called-with': 'error',
+    'jest/prefer-hooks-on-top': 'error',
+    'jest/prefer-spy-on': 'error',
+    'jest/prefer-strict-equal': 'error',
+    'jest/prefer-to-be': 'error',
+    'jest/prefer-to-contain': 'error',
+    'jest/prefer-to-have-length': 'error',
+    'jest/prefer-todo': 'error',
+    'jest/require-top-level-describe': 'error',
+    'jest/require-to-throw-message': 'error',
+    'jest/valid-describe-callback': 'error',
+    'jest/valid-expect-in-promise': 'error',
+    'jest/valid-expect': 'error',
+    'jest/valid-title': 'error',
+    quotes: [2, 'single', { avoidEscape: true }],
+    'comma-dangle': [2, 'always-multiline'],
+  },
+};

package/.git-hooks/pre-commit

@@ -0,0 +1,4 @@
+#!/bin/sh
+
+.git-hooks/pre-commit-eslint
+.git-hooks/pre-commit-test-unit

package/.git-hooks/pre-commit-eslint

@@ -0,0 +1,36 @@
+#!/bin/sh
+
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep ".jsx\{0,1\}$")
+
+if [[ "$STAGED_FILES" = "" ]]; then
+  exit 0
+fi
+
+PASS=true
+
+echo "\nValidating Javascript:\n"
+
+ESLINT="$(git rev-parse --show-toplevel)/node_modules/.bin/eslint"
+
+for FILE in $STAGED_FILES
+do
+  "$ESLINT" "$FILE"
+
+  if [[ "$?" == 0 ]]; then
+    echo "\t\033[32mESLint Passed: $FILE\033[0m"
+  else
+    echo "\t\033[41mESLint Failed: $FILE\033[0m"
+    PASS=false
+  fi
+done
+
+echo "\nJavascript validation completed!\n"
+
+if ! $PASS; then
+  echo "\033[41mESLINT FAILED:\033[0m Your commit contains files that should pass ESLint but do not. Please fix the ESLint errors and try again.\n"
+  exit 1
+else
+  echo "\033[42mESLINT SUCCEEDED\033[0m\n"
+fi
+
+exit $?

package/.git-hooks/pre-commit-test-unit

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+npm test

package/.github/updates.yml

@@ -0,0 +1,15 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      commit-message:
+        prefix: "fix"
+
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "daily"
+      commit-message:
+        prefix: "fix"

package/.github/workflows/test_and_publish.yml

@@ -0,0 +1,72 @@
+# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs
+
+name: Test & Publish
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [14.x, 16.x, 18.x]
+    steps:
+    - uses: actions/checkout@v3
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v3
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+    - run: npm ci
+    - run: npm test
+  
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+    strategy:
+      fail-fast: false
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v3
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v2
+      with:
+        languages: javascript
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v3
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+    - run: npm ci
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v2
+      with:
+        category: "/language:javascript"
+
+  publish:
+    name: Publish to NPM
+    if: ${{ github.ref == 'refs/heads/main' }}
+    runs-on: ubuntu-latest
+    needs: [test, analyze]
+    steps: 
+    - uses: actions/checkout@v3
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v3
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+    - run: npm ci
+    - run: npm run semantic-release
+      env:
+        NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/README.md

@@ -0,0 +1,119 @@
+<h1 align="center" style="border-bottom: none;">jest-matcher-http</h1>
+<h3 align="center">Extension for <a href="https://facebook.github.io/jest">Jest</a> providing http-related matchers.</h3>
+<p align="center">
+  <a href="https://www.npmjs.com/package/jest-matcher-http">
+    <img alt="npm latest version" src="https://img.shields.io/npm/v/jest-matcher-http/latest.svg">
+  </a>
+  <a href="https://github.com/rimesime/jest-matcher-http/actions?query=workflow%3ATest+branch%3Amain">
+    <img alt="Build states" src="https://github.com/semantic-release/semantic-release/workflows/Test/badge.svg">
+  </a>
+  <a href="#badge">
+    <img alt="semantic-release: angular" src="https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release">
+  </a>
+</p>
+
+
+Jest [matchers](https://jestjs.io/docs/using-matchers) (`toReturnHttpStatus`, `toReturnHttpHeader`) to [expect](https://jestjs.io/docs/expect) http responses.
+
+Logs received body and headers if response is not as expected.
+
+
+# Installation & Configuration
+
+With npm:
+
+```shell
+$ npm install --save-dev jest-matcher-http
+```
+
+Either, or:
+* Via configuration - Add this package to your `jest.config.js`:
+    ```
+    setupFilesAfterEnv: ['jest-matcher-http'],
+    ```
+
+* Or, if you need fine-grained control, load specific matchers in your test file:
+    ```javascript
+    const { toReturnHttpCode } = require('jest-matcher-http');
+
+    expect.extend({ toReturnHttpCode });
+    ```
+
+# Usage
+
+```javascript
+expect(response).toReturnHttpStatus(307);
+expect(response).toReturnHttpHeader('Location', '/v1/new-path');
+```
+
+## Log Output Example
+```bash
+expected http status code 500 to equal 307
+
+    server responded with body:
+    {
+      "requestId": "<uuid>",
+      "message": "Some helpful information."
+    }
+
+    server responded with headers:
+    {
+      "content-type": "application/json",
+      ...
+    }
+```
+
+## Extended Example
+```javascript
+const supertest = require('supertest');
+const request = supertest('www.the-host.com');
+
+describe('Example', () => {
+    it('should accept empty object', async () => {
+      const response = await request
+        .post('/v1/objects')
+        .send({});
+
+      expect(response).toReturnHttpCode(200);
+    })
+
+    it('should redirect', async () => {
+      const response = await request
+        .get('/v1/old-path');
+
+      expect(response).toReturnHttpStatus(307);
+      expect(response).toReturnHttpHeader('Location', '/v1/new-path');
+    })
+});
+```
+
+# Contributing
+
+1. Clone the repository:
+    ```shell
+    $ git clone git@github.com:rimesime/jest-matcher-http.git
+    ```
+
+1. This repository uses conventional commits that are validated using `git-conventional-commits`. To validate this automatically, git-hooks need to be enabled manually after cloning this repository:
+    ```shell
+    $ git config core.hooksPath .git-hooks
+    ```
+
+1. Install dependencies:
+    ```shell
+    $ npm ci
+    ```
+
+1. Test:
+    ```shell
+    $ npm test
+    ```
+
+1. Commit (using commitizen for semantic releases):
+    ```shell
+    $ npm run commit
+    ```
+
+# License
+
+This is free software, distributed under the [ISC license](https://opensource.org/licenses/ISC).

package/jest.unit.config.js

@@ -0,0 +1,213 @@
+'use strict';
+
+/*
+ * For a detailed explanation regarding each configuration property, visit:
+ * https://jestjs.io/docs/configuration
+ */
+
+module.exports = {
+  // All imported modules in your tests should be mocked automatically
+  // automock: false,
+
+  // Stop running tests after `n` failures
+  // bail: 0,
+
+  // The directory where Jest should store its cached dependency information
+  // cacheDirectory: "/private/var/folders/d_/f95lcbvs6bsfqsf8pvd4zngm0000gn/T/jest_dx",
+
+  // Automatically clear mock calls, instances, contexts and results before every test
+  clearMocks: true,
+
+  // Indicates whether the coverage information should be collected while executing the test
+  collectCoverage: true,
+
+  // An array of glob patterns indicating a set of files for which coverage information
+  // should be collected
+  collectCoverageFrom: ['<rootDir>/src/**/*.js'],
+
+  // The directory where Jest should output its coverage files
+  coverageDirectory: 'build/coverage/unit',
+
+  // An array of regexp pattern strings used to skip coverage collection
+  coveragePathIgnorePatterns: ['node_modules'],
+
+  // Indicates which provider should be used to instrument code for coverage
+  coverageProvider: 'v8',
+
+  // A list of reporter names that Jest uses when writing coverage reports
+  // coverageReporters: [
+  //   "json",
+  //   "text",
+  //   "lcov",
+  //   "clover"
+  // ],
+
+  // An object that configures minimum threshold enforcement for coverage results
+  coverageThreshold: {
+    global: {
+      branches: 100,
+      functions: 100,
+      lines: 100,
+      statements: 100,
+    },
+  },
+
+  // A path to a custom dependency extractor
+  // dependencyExtractor: undefined,
+
+  // Make calling deprecated APIs throw helpful error messages
+  // errorOnDeprecated: false,
+
+  // The default configuration for fake timers
+  // fakeTimers: {
+  //   "enableGlobally": false
+  // },
+
+  // Force coverage collection from ignored files using an array of glob patterns
+  // forceCoverageMatch: [],
+
+  // A path to a module which exports an async function that is triggered once before
+  // all test suites
+  // globalSetup: undefined,
+
+  // A path to a module which exports an async function that is triggered once after all test suites
+  // globalTeardown: undefined,
+
+  // A set of global variables that need to be available in all test environments
+  // globals: {},
+
+  // The maximum amount of workers used to run your tests. Can be specified as % or a number.
+  // E.g.maxWorkers: 10% will use 10% of your CPU amount + 1 as the maximum worker
+  // number.maxWorkers: 2 will use a maximum of 2 workers.
+  // maxWorkers: "50%",
+
+  // An array of directory names to be searched recursively up from the requiring module's location
+  // moduleDirectories: [
+  //   "node_modules"
+  // ],
+
+  // An array of file extensions your modules use
+  // moduleFileExtensions: [
+  //   "js",
+  //   "mjs",
+  //   "cjs",
+  //   "jsx",
+  //   "ts",
+  //   "tsx",
+  //   "json",
+  //   "node"
+  // ],
+
+  // A map from regular expressions to module names or to arrays of module names that allow to
+  // stub out resources with a single module
+  // moduleNameMapper: {},
+
+  // An array of regexp pattern strings, matched against all module paths before
+  // considered 'visible' to the module loader
+  // modulePathIgnorePatterns: [],
+
+  // Activates notifications for test results
+  // notify: false,
+
+  // An enum that specifies notification mode. Requires { notify: true }
+  // notifyMode: "failure-change",
+
+  // A preset that is used as a base for Jest's configuration
+  // preset: undefined,
+
+  // Run tests from one or more projects
+  // projects: undefined,
+
+  // Use this configuration option to add custom reporters to Jest
+  // reporters: undefined,
+
+  // Automatically reset mock state before every test
+  // resetMocks: false,
+
+  // Reset the module registry before running each individual test
+  // resetModules: false,
+
+  // A path to a custom resolver
+  // resolver: undefined,
+
+  // Automatically restore mock state and implementation before every test
+  // restoreMocks: false,
+
+  // The root directory that Jest should scan for tests and modules within
+  // rootDir: undefined,
+
+  // A list of paths to directories that Jest should use to search for files in
+  roots: ['<rootDir>/src'],
+
+  // Allows you to use a custom runner instead of Jest's default test runner
+  // runner: "jest-runner",
+
+  // The paths to modules that run some code to configure or set up the testing
+  // environment before each test
+  // setupFiles: [],
+
+  // A list of paths to modules that run some code to configure or set up the
+  // testing framework before each test
+  setupFilesAfterEnv: ['./src/index.js'],
+
+  // The number of seconds after which a test is considered as slow and reported
+  // as such in the results.
+  // slowTestThreshold: 5,
+
+  // A list of paths to snapshot serializer modules Jest should use for snapshot testing
+  // snapshotSerializers: [],
+
+  // The test environment that will be used for testing
+  // testEnvironment: "jest-environment-node",
+
+  // Options that will be passed to the testEnvironment
+  // testEnvironmentOptions: {},
+
+  // Adds a location field to test results
+  // testLocationInResults: false,
+
+  // The glob patterns Jest uses to detect test files
+  // testMatch: [
+  //   "**/__tests__/**/*.[jt]s?(x)",
+  //   "**/?(*.)+(spec|test).[tj]s?(x)"
+  // ],
+
+  // An array of regexp pattern strings that are matched against all test paths,
+  // matched tests are skipped
+  // testPathIgnorePatterns: [
+  //   "/node_modules/"
+  // ],
+
+  // The regexp pattern or array of patterns that Jest uses to detect test files
+  // testRegex: [],
+
+  // This option allows the use of a custom results processor
+  // testResultsProcessor: undefined,
+
+  // This option allows use of a custom test runner
+  // testRunner: "jest-circus/runner",
+
+  // A map from regular expressions to paths to transformers
+  // transform: undefined,
+
+  // An array of regexp pattern strings that are matched against all source file paths,
+  // matched files will skip transformation
+  // transformIgnorePatterns: [
+  //   "/node_modules/",
+  //   "\\.pnp\\.[^\\/]+$"
+  // ],
+
+  // An array of regexp pattern strings that are matched against all modules before
+  // the module loader will automatically return a mock for them
+  // unmockedModulePathPatterns: undefined,
+
+  // Indicates whether each individual test should be reported during the run
+  // verbose: undefined,
+
+  // An array of regexp patterns that are matched against all source file paths
+  // before re-running tests in watch mode
+  // watchPathIgnorePatterns: [],
+
+  // Whether to use watchman for file crawling
+  // watchman: true,
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "jest-matcher-http",
+  "version": "1.0.1",
+  "description": "Additional Jest matchers for HTTP responses.",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "jest --coverage --config jest.unit.config.js",
+    "acp": "git add . && npm run commit && git push",
+    "commit": "git-cz",
+    "semantic-release": "semantic-release --branches main"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rimesime/jest-matcher-http.git"
+  },
+  "author": "Simon Schmitt (mail@simonschmitt.com)",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/rimesime/jest-matcher-http/issues"
+  },
+  "homepage": "https://github.com/rimesime/jest-matcher-http#readme",
+  "release": {
+    "branches": [
+      "main"
+    ],
+    "repositoryUrl": "git+ssh://git@github.com/rimesime/jest-matcher-http.git",
+    "plugins": [
+      "@semantic-release/commit-analyzer",
+      "@semantic-release/release-notes-generator",
+      "@semantic-release/npm",
+      "@semantic-release/github"
+    ]
+  },
+  "devDependencies": {
+    "commitizen": "^4.2.5",
+    "cz-conventional-changelog": "^3.3.0",
+    "eslint": "^8.28.0",
+    "eslint-config-airbnb-base": "^15.0.0",
+    "eslint-plugin-import": "^2.26.0",
+    "eslint-plugin-jest": "^27.1.6",
+    "eslint-plugin-jsdoc": "^39.6.4",
+    "jest": "^29.3.1",
+    "semantic-release": "^19.0.5"
+  },
+  "dependencies": {
+    "@jest/globals": "^29.3.1"
+  },
+  "config": {
+    "commitizen": {
+      "path": "./node_modules/cz-conventional-changelog"
+    }
+  }
+}

package/src/index.js

@@ -0,0 +1,8 @@
+'use strict';
+
+const { expect } = require('@jest/globals');
+const matchers = require('./matchers');
+
+expect.extend(matchers);
+
+module.exports = matchers;

package/src/index.unit.test.js

@@ -0,0 +1,15 @@
+'use strict';
+
+const matchers = require('./index');
+
+describe('index', () => {
+  it('should add matchers', () => {
+    expect(expect.toReturnHttpCode).toBeDefined();
+    expect(expect.toReturnHttpHeader).toBeDefined();
+  });
+
+  it('should export matchers', () => {
+    expect(matchers.toReturnHttpCode).toBeDefined();
+    expect(matchers.toReturnHttpHeader).toBeDefined();
+  });
+});

package/src/matchers.js

@@ -0,0 +1,60 @@
+'use strict';
+
+/**
+ * Expect a http request to return given http status code.
+ * Log response body and headers otherwise.
+ *
+ * @param {{status: number, body: any, headers: any}} response - The response of the request.
+ * @param {number} expectedHttpStatusCode - The expected http status code.
+ * @returns {{message: Function, pass: boolean}} The expect result according to jest.
+ * @see {@link https://jestjs.io/docs/expect#expectextendmatchers}
+ */
+function toReturnHttpCode(response, expectedHttpStatusCode) {
+  const { status, body, headers } = response;
+
+  const pass = status === expectedHttpStatusCode;
+
+  if (pass) {
+    return { pass };
+  }
+
+  return {
+    pass,
+    message: () => `expected http status code ${status} to equal ${expectedHttpStatusCode}\n\n`
+      + `server responded with body:\n${JSON.stringify(body, null, 2)}\n\n`
+      + `server responded with headers:\n${JSON.stringify(headers, null, 2)}`,
+  };
+}
+
+/**
+ * Expect a http request to return the given http header.
+ * Log response body and headers otherwise.
+ *
+ * @param {{body: any, headers: any}} response - The response of the request.
+ * @param {string} headerField - The expected http header field.
+ * @param {string} headerValue - The expected http header value.
+ * @returns {{message: Function, pass: boolean}} The expect result according to jest.
+ * @see {@link https://jestjs.io/docs/expect#expectextendmatchers}
+ */
+function toReturnHttpHeader(response, headerField, headerValue) {
+  const { body, headers } = response;
+  const headerFieldLowerCase = headerField.toLowerCase();
+
+  const pass = headers[headerFieldLowerCase] === headerValue;
+
+  if (pass) {
+    return { pass };
+  }
+
+  return {
+    pass,
+    message: () => `expected http header "${headerFieldLowerCase}" with value "${headerValue}"\n\n`
+      + `server responded with body:\n${JSON.stringify(body, null, 2)}\n\n`
+      + `server responded with headers:\n${JSON.stringify(headers, null, 2)}`,
+  };
+}
+
+module.exports = {
+  toReturnHttpCode,
+  toReturnHttpHeader,
+};

package/src/matchers.unit.test.js

@@ -0,0 +1,79 @@
+'use strict';
+
+describe('matchers', () => {
+  describe('toReturnHttpCode', () => {
+    it('should succeed if http code is as expected', async () => {
+      const response = {
+        status: 200,
+        body: {},
+        headers: {},
+      };
+
+      expect(response).toReturnHttpCode(response.status);
+    });
+
+    it('should fail if http code is not as expected', async () => {
+      const response = {
+        status: 200,
+        body: {},
+        headers: {},
+      };
+
+      let caughtError;
+      try {
+        expect(response).toReturnHttpCode(1);
+      } catch (error) {
+        caughtError = error;
+      }
+
+      expect(caughtError.message).toBe(
+        'expected http status code 200 to equal 1\n'
+          + '\n'
+          + 'server responded with body:\n'
+          + '{}\n'
+          + '\n'
+          + 'server responded with headers:\n'
+          + '{}',
+      );
+    });
+  });
+
+  describe('toReturnHttpHeader', () => {
+    it('should succeed if http header is as expected', async () => {
+      const response = {
+        status: 200,
+        body: {},
+        headers: {
+          'request-id': 'some-uuid',
+        },
+      };
+
+      expect(response).toReturnHttpHeader('request-id', 'some-uuid');
+    });
+
+    it('should fail if http header is not as expected', async () => {
+      const response = {
+        status: 200,
+        body: {},
+        headers: {},
+      };
+
+      let caughtError;
+      try {
+        expect(response).toReturnHttpHeader('request-id', 'some-uuid');
+      } catch (error) {
+        caughtError = error;
+      }
+
+      expect(caughtError.message).toBe(
+        'expected http header "request-id" with value "some-uuid"\n'
+          + '\n'
+          + 'server responded with body:\n'
+          + '{}\n'
+          + '\n'
+          + 'server responded with headers:\n'
+          + '{}',
+      );
+    });
+  });
+});