@eggjs/supertest 8.2.0 → 8.3.0-beta.3

package/README.md

@@ -1,8 +1,6 @@
 # @eggjs/supertest
 
 [![NPM version][npm-image]][npm-url]
-[![code coverage][coverage-badge]][coverage]
-[![Node.js CI](https://github.com/eggjs/supertest/actions/workflows/nodejs.yml/badge.svg)](https://github.com/eggjs/supertest/actions/workflows/nodejs.yml)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://makeapullrequest.com)
 [![MIT License][license-badge]][license]
 [![npm download][download-image]][download-url]
@@ -10,14 +8,12 @@
 
 [npm-image]: https://img.shields.io/npm/v/@eggjs/supertest.svg?style=flat-square
 [npm-url]: https://npmjs.org/package/@eggjs/supertest
-[coverage-badge]: https://img.shields.io/codecov/c/github/eggjs/supertest.svg
-[coverage]: https://codecov.io/gh/eggjs/supertest
 [license-badge]: https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square
 [license]: https://github.com/eggjs/supertest/blob/master/LICENSE
 [download-image]: https://img.shields.io/npm/dm/@eggjs/supertest.svg?style=flat-square
 [download-url]: https://npmjs.org/package/@eggjs/supertest
 
-> HTTP assertions made easy via [superagent](http://github.com/ladjs/superagent).  Maintained for [Forward Email](https://github.com/forwardemail) and [Lad](https://github.com/ladjs).
+> HTTP assertions made easy via [superagent](http://github.com/ladjs/superagent). Maintained for [Forward Email](https://github.com/forwardemail) and [Lad](https://github.com/ladjs).
 > Forked for TypeScript friendly
 
 Document see [SuperTest](https://ladjs.github.io/superagent/)
@@ -35,7 +31,7 @@ Install SuperTest as an npm module and save it to your package.json file as a de
 npm install @eggjs/supertest --save-dev
 ```
 
-  Once installed it can now be referenced by simply calling ```require('supertest');```
+Once installed it can now be referenced by simply calling `require('supertest');`
 
 ## Example
 
@@ -52,7 +48,7 @@ const express = require('express');
 
 const app = express();
 
-app.get('/user', function(req, res) {
+app.get('/user', function (req, res) {
   res.status(200).json({ name: 'john' });
 });
 
@@ -61,7 +57,7 @@ request(app)
   .expect('Content-Type', /json/)
   .expect('Content-Length', '15')
   .expect(200)
-  .end(function(err, res) {
+  .end(function (err, res) {
     if (err) throw err;
   });
 ```
@@ -74,7 +70,7 @@ const express = require('express');
 
 const app = express();
 
-app.get('/user', function(req, res) {
+app.get('/user', function (req, res) {
   res.status(200).json({ name: 'john' });
 });
 
@@ -83,16 +79,17 @@ request(app, { http2: true })
   .expect('Content-Type', /json/)
   .expect('Content-Length', '15')
   .expect(200)
-  .end(function(err, res) {
+  .end(function (err, res) {
     if (err) throw err;
   });
 
-request.agent(app, { http2: true })
+request
+  .agent(app, { http2: true })
   .get('/user')
   .expect('Content-Type', /json/)
   .expect('Content-Length', '15')
   .expect(200)
-  .end(function(err, res) {
+  .end(function (err, res) {
     if (err) throw err;
   });
 ```
@@ -100,8 +97,8 @@ request.agent(app, { http2: true })
 Here's an example with mocha, note how you can pass `done` straight to any of the `.expect()` calls:
 
 ```js
-describe('GET /user', function() {
-  it('responds with json', function(done) {
+describe('GET /user', function () {
+  it('responds with json', function (done) {
     request(app)
       .get('/user')
       .set('Accept', 'application/json')
@@ -114,8 +111,8 @@ describe('GET /user', function() {
 You can use `auth` method to pass HTTP username and password in the same way as in the [superagent](http://ladjs.github.io/superagent/#authentication):
 
 ```js
-describe('GET /user', function() {
-  it('responds with json', function(done) {
+describe('GET /user', function () {
+  it('responds with json', function (done) {
     request(app)
       .get('/user')
       .auth('username', 'password')
@@ -135,15 +132,15 @@ not throw - they will return the assertion as an error to the `.end()` callback.
 order to fail the test case, you will need to rethrow or pass `err` to `done()`, as follows:
 
 ```js
-describe('POST /users', function() {
-  it('responds with json', function(done) {
+describe('POST /users', function () {
+  it('responds with json', function (done) {
     request(app)
       .post('/users')
-      .send({name: 'john'})
+      .send({ name: 'john' })
       .set('Accept', 'application/json')
       .expect('Content-Type', /json/)
       .expect(200)
-      .end(function(err, res) {
+      .end(function (err, res) {
         if (err) return done(err);
         return done();
       });
@@ -154,16 +151,16 @@ describe('POST /users', function() {
 You can also use promises:
 
 ```js
-describe('GET /users', function() {
-  it('responds with json', function() {
+describe('GET /users', function () {
+  it('responds with json', function () {
     return request(app)
       .get('/users')
       .set('Accept', 'application/json')
       .expect('Content-Type', /json/)
       .expect(200)
       .then(response => {
-         expect(response.body.email).toEqual('foo@bar.com');
-      })
+        expect(response.body.email).toEqual('foo@bar.com');
+      });
   });
 });
 ```
@@ -171,12 +168,12 @@ describe('GET /users', function() {
 Or async/await syntax:
 
 ```js
-describe('GET /users', function() {
-  it('responds with json', async function() {
+describe('GET /users', function () {
+  it('responds with json', async function () {
     const response = await request(app)
       .get('/users')
-      .set('Accept', 'application/json')
-    expect(response.headers["Content-Type"]).toMatch(/json/);
+      .set('Accept', 'application/json');
+    expect(response.headers['Content-Type']).toMatch(/json/);
     expect(response.status).toEqual(200);
     expect(response.body.email).toEqual('foo@bar.com');
   });
@@ -187,20 +184,24 @@ Expectations are run in the order of definition. This characteristic can be used
 to modify the response body or headers before executing an assertion.
 
 ```js
-describe('POST /user', function() {
-  it('user.name should be an case-insensitive match for "john"', function(done) {
+describe('POST /user', function () {
+  it('user.name should be an case-insensitive match for "john"', function (done) {
     request(app)
       .post('/user')
       .send('name=john') // x-www-form-urlencoded upload
       .set('Accept', 'application/json')
-      .expect(function(res) {
+      .expect(function (res) {
         res.body.id = 'some fixed id';
         res.body.name = res.body.name.toLowerCase();
       })
-      .expect(200, {
-        id: 'some fixed id',
-        name: 'john'
-      }, done);
+      .expect(
+        200,
+        {
+          id: 'some fixed id',
+          name: 'john',
+        },
+        done
+      );
   });
 });
 ```
@@ -223,11 +224,11 @@ initialization app or url, a new `Test` is created per `request.VERB()` call.
 ```js
 t = request('http://localhost:5555');
 
-t.get('/').expect(200, function(err){
+t.get('/').expect(200, function (err) {
   console.log(err);
 });
 
-t.get('/').expect('heya', function(err){
+t.get('/').expect('heya', function (err) {
   console.log(err);
 });
 ```
@@ -240,32 +241,28 @@ const should = require('should');
 const express = require('express');
 const cookieParser = require('cookie-parser');
 
-describe('request.agent(app)', function() {
+describe('request.agent(app)', function () {
   const app = express();
   app.use(cookieParser());
 
-  app.get('/', function(req, res) {
+  app.get('/', function (req, res) {
     res.cookie('cookie', 'hey');
     res.send();
   });
 
-  app.get('/return', function(req, res) {
+  app.get('/return', function (req, res) {
     if (req.cookies.cookie) res.send(req.cookies.cookie);
-    else res.send(':(')
+    else res.send(':(');
   });
 
   const testAgent = agent(app);
 
-  it('should save cookies', function(done) {
-    testAgent
-    .get('/')
-    .expect('set-cookie', 'cookie=hey; Path=/', done);
+  it('should save cookies', function (done) {
+    testAgent.get('/').expect('set-cookie', 'cookie=hey; Path=/', done);
   });
 
-  it('should send cookies', function(done) {
-    testAgent
-    .get('/return')
-    .expect('hey', done);
+  it('should send cookies', function (done) {
+    testAgent.get('/return').expect('hey', done);
   });
 });
 ```
@@ -317,14 +314,11 @@ Assert header `field` `value` with a string or regular expression.
 Pass a custom assertion function. It'll be given the response object to check. If the check fails, throw an error.
 
 ```js
-request(app)
-  .get('/')
-  .expect(hasPreviousAndNextKeys)
-  .end(done);
+request(app).get('/').expect(hasPreviousAndNextKeys).end(done);
 
 function hasPreviousAndNextKeys(res) {
-  if (!('next' in res.body)) throw new Error("missing next key");
-  if (!('prev' in res.body)) throw new Error("missing prev key");
+  if (!('next' in res.body)) throw new Error('missing next key');
+  if (!('prev' in res.body)) throw new Error('missing prev key');
 }
 ```
 
@@ -342,6 +336,6 @@ Inspired by [api-easy](https://github.com/flatiron/api-easy) minus vows coupling
 
 ## Contributors
 
-[![Contributors](https://contrib.rocks/image?repo=eggjs/supertest)](https://github.com/eggjs/supertest/graphs/contributors)
+[![Contributors](https://contrib.rocks/image?repo=eggjs/egg)](https://github.com/eggjs/egg/graphs/contributors)
 
 Made with [contributors-img](https://contrib.rocks).

package/dist/agent.d.ts

@@ -0,0 +1,33 @@
+import { AgentOptions as AgentOptions$1, App } from "./types.js";
+import { Test } from "./test.js";
+import { agent } from "superagent";
+import { Server } from "node:net";
+
+//#region src/agent.d.ts
+
+/**
+ * Initialize a new `TestAgent`.
+ *
+ * @param {Function|Server} app
+ * @param {Object} options
+ */
+declare class TestAgent extends agent {
+  #private;
+  app: Server | string;
+  _host: string;
+  constructor(appOrListener: App, options?: AgentOptions$1);
+  host(host: string): this;
+  protected _testRequest(method: string, url: string): Test;
+  delete(url: string): Test;
+  del(url: string): Test;
+  get(url: string): Test;
+  head(url: string): Test;
+  put(url: string): Test;
+  post(url: string): Test;
+  patch(url: string): Test;
+  options(url: string): Test;
+  trace(url: string): Test;
+}
+declare const proxyAgent: typeof TestAgent;
+//#endregion
+export { TestAgent, proxyAgent };

package/dist/agent.js

@@ -0,0 +1,74 @@
+import { Test } from "./test.js";
+import http from "node:http";
+import http2 from "node:http2";
+import { agent } from "superagent";
+
+//#region src/agent.ts
+/**
+* Initialize a new `TestAgent`.
+*
+* @param {Function|Server} app
+* @param {Object} options
+*/
+var TestAgent = class extends agent {
+	app;
+	_host;
+	#http2 = false;
+	constructor(appOrListener, options = {}) {
+		super(options);
+		if (typeof appOrListener === "function") if (options.http2) {
+			this.#http2 = true;
+			this.app = http2.createServer(appOrListener);
+		} else this.app = http.createServer(appOrListener);
+		else this.app = appOrListener;
+	}
+	host(host) {
+		this._host = host;
+		return this;
+	}
+	_testRequest(method, url) {
+		const req = new Test(this.app, method.toUpperCase(), url);
+		if (this.#http2) req.http2();
+		if (this._host) req.set("host", this._host);
+		const that = this;
+		req.on("response", that._saveCookies.bind(this));
+		req.on("redirect", that._saveCookies.bind(this));
+		req.on("redirect", that._attachCookies.bind(this, req));
+		that._setDefaults(req);
+		that._attachCookies(req);
+		return req;
+	}
+	delete(url) {
+		return this._testRequest("delete", url);
+	}
+	del(url) {
+		return this._testRequest("delete", url);
+	}
+	get(url) {
+		return this._testRequest("get", url);
+	}
+	head(url) {
+		return this._testRequest("head", url);
+	}
+	put(url) {
+		return this._testRequest("put", url);
+	}
+	post(url) {
+		return this._testRequest("post", url);
+	}
+	patch(url) {
+		return this._testRequest("patch", url);
+	}
+	options(url) {
+		return this._testRequest("options", url);
+	}
+	trace(url) {
+		return this._testRequest("trace", url);
+	}
+};
+const proxyAgent = new Proxy(TestAgent, { apply(target, _, argumentsList) {
+	return new target(argumentsList[0], argumentsList[1]);
+} });
+
+//#endregion
+export { TestAgent, proxyAgent };

package/dist/error/AssertError.d.ts

@@ -0,0 +1,8 @@
+//#region src/error/AssertError.d.ts
+declare class AssertError extends Error {
+  expected: any;
+  actual: any;
+  constructor(message: string, expected: any, actual: any, options?: ErrorOptions);
+}
+//#endregion
+export { AssertError };

package/dist/error/AssertError.js

@@ -0,0 +1,15 @@
+//#region src/error/AssertError.ts
+var AssertError = class extends Error {
+	expected;
+	actual;
+	constructor(message, expected, actual, options) {
+		super(message, options);
+		this.name = this.constructor.name;
+		this.expected = expected;
+		this.actual = actual;
+		Error.captureStackTrace(this, this.constructor);
+	}
+};
+
+//#endregion
+export { AssertError };

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import { AgentOptions, App } from "./types.js";
+import { AssertFunction, CallbackFunction, ExpectHeader, ResponseError, Test, TestApplication } from "./test.js";
+import { Request, RequestOptions } from "./request.js";
+import { TestAgent, proxyAgent } from "./agent.js";
+
+//#region src/index.d.ts
+
+/**
+ * Test against the given `app`,
+ * returning a new `Test`.
+ */
+declare function request(app: App, options?: RequestOptions): Request;
+declare const _default: ((app: App, options?: RequestOptions) => Request) & {
+  agent: (app: App, options?: AgentOptions) => TestAgent;
+};
+//#endregion
+export { AssertFunction, CallbackFunction, ExpectHeader, Request, type RequestOptions, ResponseError, Test, TestAgent, TestApplication, proxyAgent as agent, _default as default, request };

package/dist/index.js

@@ -0,0 +1,24 @@
+import { Test } from "./test.js";
+import { Request } from "./request.js";
+import { TestAgent, proxyAgent } from "./agent.js";
+
+//#region src/index.ts
+/**
+* Test against the given `app`,
+* returning a new `Test`.
+*/
+function request(app, options = {}) {
+	return new Request(app, options);
+}
+var src_default = new Proxy(request, {
+	apply(target, _, argumentsList) {
+		return target(argumentsList[0], argumentsList[1]);
+	},
+	get(target, property, receiver) {
+		if (property === "agent") return proxyAgent;
+		return Reflect.get(target, property, receiver);
+	}
+});
+
+//#endregion
+export { Request, Test, TestAgent, proxyAgent as agent, src_default as default, request };

package/dist/request.d.ts

@@ -0,0 +1,25 @@
+import { App } from "./types.js";
+import { Test } from "./test.js";
+import { Server } from "node:net";
+
+//#region src/request.d.ts
+interface RequestOptions {
+  http2?: boolean;
+}
+declare class Request {
+  #private;
+  app: string | Server;
+  constructor(appOrListener: App, options?: RequestOptions);
+  protected _testRequest(method: string, url: string): Test;
+  delete(url: string): Test;
+  del(url: string): Test;
+  get(url: string): Test;
+  head(url: string): Test;
+  put(url: string): Test;
+  post(url: string): Test;
+  patch(url: string): Test;
+  options(url: string): Test;
+  trace(url: string): Test;
+}
+//#endregion
+export { Request, RequestOptions };

package/dist/request.js

@@ -0,0 +1,51 @@
+import { Test } from "./test.js";
+import http from "node:http";
+import http2 from "node:http2";
+
+//#region src/request.ts
+var Request = class {
+	app;
+	#http2 = false;
+	constructor(appOrListener, options = {}) {
+		if (typeof appOrListener === "function") if (options.http2) {
+			this.#http2 = true;
+			this.app = http2.createServer(appOrListener);
+		} else this.app = http.createServer(appOrListener);
+		else this.app = appOrListener;
+	}
+	_testRequest(method, url) {
+		const req = new Test(this.app, method.toUpperCase(), url);
+		if (this.#http2) req.http2();
+		return req;
+	}
+	delete(url) {
+		return this._testRequest("delete", url);
+	}
+	del(url) {
+		return this._testRequest("delete", url);
+	}
+	get(url) {
+		return this._testRequest("get", url);
+	}
+	head(url) {
+		return this._testRequest("head", url);
+	}
+	put(url) {
+		return this._testRequest("put", url);
+	}
+	post(url) {
+		return this._testRequest("post", url);
+	}
+	patch(url) {
+		return this._testRequest("patch", url);
+	}
+	options(url) {
+		return this._testRequest("options", url);
+	}
+	trace(url) {
+		return this._testRequest("trace", url);
+	}
+};
+
+//#endregion
+export { Request };

package/dist/test.d.ts

@@ -0,0 +1,100 @@
+import { AssertError } from "./error/AssertError.js";
+import { Request, Response } from "superagent";
+import { Server } from "node:net";
+
+//#region src/test.d.ts
+type TestApplication = Server | string;
+type AssertFunction = (res: Response) => AssertError | void;
+type CallbackFunction = (err: AssertError | Error | null, res: Response) => void;
+type ResponseError = Error & {
+  syscall?: string;
+  code?: string;
+  status?: number;
+};
+interface ExpectHeader {
+  name: string;
+  value: string | number | RegExp;
+}
+declare class Test extends Request {
+  app: TestApplication;
+  _server: Server;
+  _asserts: AssertFunction[];
+  /**
+   * Initialize a new `Test` with the given `app`,
+   * request `method` and `path`.
+   */
+  constructor(app: TestApplication, method: string, path: string);
+  /**
+   * Returns a URL, extracted from a server.
+   *
+   * @return {String} URL address
+   * @private
+   */
+  protected serverAddress(app: Server, path: string): string;
+  /**
+   * Expectations:
+   *
+   * ```js
+   *   .expect(200)
+   *   .expect(200, fn)
+   *   .expect(200, body)
+   *   .expect('Some body')
+   *   .expect('Some body', fn)
+   *   .expect(['json array body', { key: 'val' }])
+   *   .expect('Content-Type', 'application/json')
+   *   .expect('Content-Type', 'application/json', fn)
+   *   .expect(fn)
+   *   .expect([200, 404])
+   * ```
+   *
+   * @return {Test} The current Test instance for chaining.
+   */
+  expect(a: number | string | RegExp | object | AssertFunction, b?: string | number | RegExp | CallbackFunction, c?: CallbackFunction): Test;
+  /**
+   * UnExpectations:
+   *
+   *   .unexpectHeader('Content-Type')
+   *   .unexpectHeader('Content-Type', fn)
+   */
+  unexpectHeader(name: string, fn?: CallbackFunction): this;
+  /**
+   * Expectations:
+   *
+   *   .expectHeader('Content-Type')
+   *   .expectHeader('Content-Type', fn)
+   */
+  expectHeader(name: string, fn?: CallbackFunction): this;
+  _unexpectHeader(name: string, res: Response): AssertError | undefined;
+  _expectHeader(name: string, res: Response): AssertError | undefined;
+  /**
+   * Defer invoking superagent's `.end()` until
+   * the server is listening.
+   */
+  end(fn: CallbackFunction): this;
+  /**
+   * Perform assertions and invoke `fn(err, res)`.
+   */
+  assert(resError: ResponseError | null, res: Response, fn: CallbackFunction): void;
+  /**
+   * Perform assertions on a response body and return an Error upon failure.
+   */
+  _assertBody(body: RegExp | string | number | object | null | undefined, res: Response): AssertError | undefined;
+  /**
+   * Perform assertions on a response header and return an Error upon failure.
+   */
+  _assertHeader(header: ExpectHeader, res: Response): AssertError | undefined;
+  /**
+   * Perform assertions on the response status and return an Error upon failure.
+   */
+  _assertStatus(status: number, res: Response): AssertError | undefined;
+  /**
+   * Perform assertions on the response status and return an Error upon failure.
+   */
+  _assertStatusArray(statusArray: number[], res: Response): AssertError | undefined;
+  /**
+   * Performs an assertion by calling a function and return an Error upon failure.
+   */
+  _assertFunction(fn: AssertFunction, res: Response): Error | undefined;
+}
+//#endregion
+export { AssertFunction, CallbackFunction, ExpectHeader, ResponseError, Test, TestApplication };