feat: add types to support typescript projects

README.md

@@ -37,17 +37,13 @@ With npm:
 $ npm install --save-dev jest-matcher-http
 ```
 
-Add this package to your `jest.config.js`:
+Add this setting to your `jest.config.js`:
 ```
 setupFilesAfterEnv: ['jest-matcher-http'],
 ```
 
-Alternatively, if you need fine-grained control, load specific matchers in your test file:
-```javascript
-const { toReturnHttpCode } = require('jest-matcher-http');
+There's an example typescript project here: [integration_tests/tsProject/](integration_tests/tsProject/). This is used for integration testing this lib to ensure typescript compatibility.
 
-expect.extend({ toReturnHttpCode });
-```
 
 # Usage
 

integration_tests/tsProject.int.test.js

@@ -0,0 +1,26 @@
+'use strict';
+
+const { exec } = require('child_process');
+
+describe('typescript project', () => {
+  // eslint-disable-next-line jest/no-done-callback
+  it('should successfully run jest tests of typescript project', (done) => {
+    const cmd = 'cd integration_tests/tsProject && npx jest my.successful.test.ts';
+    exec(cmd, (error) => {
+      expect(error).toBeNull();
+      done();
+    });
+  });
+
+  // eslint-disable-next-line jest/no-done-callback
+  it('should let jest tests fail if tests failing', (done) => {
+    const cmd = 'cd integration_tests/tsProject && npx jest my.failing.test.ts';
+    exec(cmd, (error) => {
+      expect(error?.code).toBe(1);
+      expect(error?.message).toStrictEqual(
+        expect.stringContaining('expected http status code 200 to equal 500'),
+      );
+      done();
+    });
+  });
+});

integration_tests/tsProject/jest.config.js

@@ -0,0 +1,10 @@
+'use strict';
+
+module.exports = {
+  preset: 'ts-jest',
+  // For real projects, use:
+  // setupFilesAfterEnv: ['jest-matcher-http'],
+  // Since this is a integration test project, living in the main
+  // package, we have to import the main package with a relative path.
+  setupFilesAfterEnv: ['../../'],
+};

integration_tests/tsProject/my.failing.test.ts

@@ -0,0 +1,24 @@
+// For real projects, use:
+// import 'jest-matcher-http';
+// Since this is a integration test project, living in the main
+// package, we have to import the main package with a relative path.
+import '../../';
+
+import axios, { AxiosInstance, AxiosResponse } from 'axios';
+
+const { runAgainstServer } = require('../localServer.int.helper');
+
+describe('matchers', () => {
+  let request: AxiosInstance;
+  let response: AxiosResponse;
+
+  test('should always fail', async () => {
+    await runAgainstServer(async (url: string) => {
+      request = axios.create({ baseURL: url });
+      response = await request.get('/get-json');
+    });
+
+    expect(response).toReturnHttpCode(500);
+    expect(response).toReturnHttpHeader('non-existing', 'Header');
+  });
+});

integration_tests/tsProject/my.successful.test.ts

@@ -0,0 +1,24 @@
+// For real projects, use:
+// import 'jest-matcher-http';
+// Since this is a integration test project, living in the main
+// package, we have to import the main package with a relative path.
+import '../../';
+
+import axios, { AxiosInstance, AxiosResponse } from 'axios';
+
+const { runAgainstServer } = require('../localServer.int.helper');
+
+describe('matchers', () => {
+  let request: AxiosInstance;
+  let response: AxiosResponse;
+
+  test('should be able to use http matchers', async () => {
+    await runAgainstServer(async (url: string) => {
+      request = axios.create({ baseURL: url });
+      response = await request.get('/get-json');
+    });
+
+    expect(response).toReturnHttpCode(200);
+    expect(response).toReturnHttpHeader('some', 'Header');
+  });
+});

jest.unit.config.js

@@ -177,9 +177,10 @@ module.exports = {
 
   // An array of regexp pattern strings that are matched against all test paths,
   // matched tests are skipped
-  // testPathIgnorePatterns: [
-  //   "/node_modules/"
-  // ],
+  testPathIgnorePatterns: [
+    '/node_modules/',
+    '.ts$',
+  ],
 
   // The regexp pattern or array of patterns that Jest uses to detect test files
   // testRegex: [],

package.json

@@ -6,6 +6,7 @@
   "engines": {
     "node": "16.x || 18.x || 20.x"
   },
+  "types": "./types/index.d.ts",
   "scripts": {
     "lint": "eslint .",
     "test": "jest --coverage --config jest.unit.config.js",
@@ -38,6 +39,7 @@
     ]
   },
   "devDependencies": {
+    "@types/jest": "^29.5.12",
     "axios": "^1.3.4",
     "eslint": "^8.36.0",
     "eslint-config-airbnb-base": "^15.0.0",
@@ -50,7 +52,9 @@
     "pre-commit": "^1.2.2",
     "semantic-release": "^23.0.7",
     "signal-promise": "^1.0.3",
-    "superagent": "^8.0.9"
+    "superagent": "^8.0.9",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.4.4"
   },
   "dependencies": {
     "@jest/globals": "^29.5.0"

src/matchers.js

@@ -1,10 +1,20 @@
 'use strict';
 
+/**
+ * @typedef {object} GenericResponse
+ * @property {{ [key: string]: any }} headers - The headers of the response.
+ * @property {object} [data] - The data of the response.
+ * @property {string} [text] - The text of the response.
+ * @property {object} [body] - The body of the response.
+ * @property {number} [status] - The status of the response.
+ * @property {number} [statusCode] - The status of the response.
+ */
+
 /**
  * Extract the result from the response.
  *
- * @param {object} response - The response of the request.
- * @returns {object} The result. Empty string if no result found.
+ * @param {GenericResponse} response - The response of the request.
+ * @returns {object | string} The result. Empty string if no result found.
  */
 function extractResult(response) {
   if (response.data) {
@@ -26,9 +36,9 @@ function extractResult(response) {
  * Expect a http request to return given http status code.
  * Log response body and headers otherwise.
  *
- * @param {object} response - The response of the request.
+ * @param {GenericResponse} 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.
+ * @returns {{ pass: boolean, message: () => string }} The expect result according to jest.
  * @see {@link https://jestjs.io/docs/expect#expectextendmatchers}
  */
 function toReturnHttpCode(response, expectedHttpStatusCode) {
@@ -51,10 +61,10 @@ function toReturnHttpCode(response, expectedHttpStatusCode) {
  * Expect a http request to return the given http header.
  * Log response body and headers otherwise.
  *
- * @param {object} response - The response of the request.
+ * @param {GenericResponse} 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.
+ * @returns {{ pass: boolean, message: () => string }} The expect result according to jest.
  * @see {@link https://jestjs.io/docs/expect#expectextendmatchers}
  */
 function toReturnHttpHeader(response, headerField, headerValue) {

types/index.d.ts

@@ -0,0 +1,10 @@
+export {};
+
+declare global {
+    namespace jest {
+        interface Matchers<R> {
+            toReturnHttpCode(status: number): R;
+            toReturnHttpHeader(headerField: string, headerValue: string): R;
+        }
+    }
+}