Skip to content

Commit

Permalink
fix: update docs and types to expose request (#341)
Browse files Browse the repository at this point in the history
Updates the types to export a `request` object, and also updates the
readme to prefer `request.*` rather than `chai.request.*`.
  • Loading branch information
43081j authored Sep 24, 2024
1 parent 1e1abbe commit ffb54a4
Show file tree
Hide file tree
Showing 2 changed files with 53 additions and 19 deletions.
62 changes: 46 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,11 @@ chai.use(chaiHttp);
// if you need to access `request`
import {default as chaiHttp, request} from "chai-http";
chai.use(chaiHttp);

request.get(...).send(...);

// or setting up an app
request.execute(app);
```

To use Chai HTTP on a web page, please use the latest v4 version for now.
Expand All @@ -54,7 +58,9 @@ port to listen on for a given test.
__Note:__ This feature is only supported on Node.js, not in web browsers.

```js
chai.request.execute(app)
import {request} from 'chai-http';

request.execute(app)
.get('/')
```

Expand All @@ -65,7 +71,9 @@ keep the server open, perhaps if you're making multiple requests, you must call
`.keepOpen()` after `.request()`, and manually close the server down:

```js
const requester = chai.request.Request(app).keepOpen()
import {request} from 'chai-http';

const requester = request.Request(app).keepOpen()

Promise.all([
requester.get('/a'),
Expand All @@ -81,7 +89,9 @@ Promise.all([
You may also use a base url as the foundation of your request.

```js
chai.request.execute('http://localhost:8080')
import {request} from 'chai-http';

request.execute('http://localhost:8080')
.get('/')
```

Expand All @@ -102,25 +112,31 @@ Examples:

`.set()`
```js
import {request} from 'chai-http';

// Set a request header
chai.request.execute(app)
request.execute(app)
.put('/user/me')
.set('Content-Type', 'application/json')
.send({ password: '123', confirmPassword: '123' })
```

`.send()`
```js
import {request} from 'chai-http';

// Send some JSON
chai.request.execute(app)
request.execute(app)
.put('/user/me')
.send({ password: '123', confirmPassword: '123' })
```

`.type()`
```js
import {request} from 'chai-http';

// Send some Form Data
chai.request.execute(app)
request.execute(app)
.post('/user/me')
.type('form')
.send({
Expand All @@ -132,30 +148,36 @@ chai.request.execute(app)

`.attach()`
```js
import {request} from 'chai-http';

// Attach a file
chai.request.execute(app)
request.execute(app)
.post('/user/avatar')
.attach('imageField', fs.readFileSync('avatar.png'), 'avatar.png')
```

`.auth()`
```js
import {request} from 'chai-http';

// Authenticate with Basic authentication
chai.request.execute(app)
request.execute(app)
.get('/protected')
.auth('user', 'pass')

// Authenticate with Bearer Token
chai.request.execute(app)
request.execute(app)
.get('/protected')
.auth(accessToken, { type: 'bearer' })

```

`.query()`
```js
import {request} from 'chai-http';

// Chain some GET query parameters
chai.request.execute(app)
request.execute(app)
.get('/search')
.query({name: 'foo', limit: 10}) // /search?name=foo&limit=10
```
Expand All @@ -171,7 +193,9 @@ const { expect } = chai;
To make the request and assert on its response, the `end` method can be used:

```js
chai.request.execute(app)
import {request} from 'chai-http';

request.execute(app)
.put('/user/me')
.send({ password: '123', confirmPassword: '123' })
.end((err, res) => {
Expand All @@ -193,8 +217,10 @@ accomplished using the
callback has completed, and the assertions can be verified:

```js
import {request} from 'chai-http';

it('fails, as expected', function(done) { // <= Pass in done callback
chai.request.execute('http://localhost:8080')
request.execute('http://localhost:8080')
.get('/')
.end((err, res) => {
expect(res).to.have.status(123);
Expand All @@ -203,7 +229,7 @@ it('fails, as expected', function(done) { // <= Pass in done callback
});

it('succeeds silently!', () => { // <= No done callback
chai.request.execute('http://localhost:8080')
request.execute('http://localhost:8080')
.get('/')
.end((err, res) => {
expect(res).to.have.status(123); // <= Test completes before this runs
Expand All @@ -221,7 +247,9 @@ If `Promise` is available, `request()` becomes a Promise capable library -
and chaining of `then`s becomes possible:

```js
chai.request.execute(app)
import {request} from 'chai-http';

request.execute(app)
.put('/user/me')
.send({ password: '123', confirmPassword: '123' })
.then((res) => {
Expand All @@ -238,8 +266,10 @@ Sometimes you need to keep cookies from one request, and send them with the
next (for example, when you want to login with the first request, then access an authenticated-only resource later). For this, `.request.agent()` is available:

```js
import {request} from 'chai-http';

// Log in
const agent = chai.request.agent(app)
const agent = request.agent(app)
agent
.post('/session')
.send({ username: 'me', password: '123' })
Expand All @@ -254,7 +284,7 @@ agent
});
```

Note: The server started by `chai.request.agent(app)` will not automatically close following the test(s). You should call `agent.close()` after your tests to ensure your program exits.
Note: The server started by `request.agent(app)` will not automatically close following the test(s). You should call `agent.close()` after your tests to ensure your program exits.

## Assertions

Expand Down
10 changes: 7 additions & 3 deletions types/index.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
// Austin Cawley-Edwards <https://github.com/austince>
// TypeScript Version: 3.0
/// <reference types="chai" />
import * as request from 'superagent';
import * as superAgentRequest from 'superagent';

// Merge namespace with global chai
declare global {
Expand Down Expand Up @@ -48,8 +48,8 @@ declare global {
}

namespace ChaiHttp {
interface Response extends request.Response {}
interface Agent extends request.SuperAgentStatic {
interface Response extends superAgentRequest.Response {}
interface Agent extends superAgentRequest.SuperAgentStatic {
keepOpen(): Agent;
close(callback?: (err: any) => void): Agent;
}
Expand All @@ -59,3 +59,7 @@ declare global {
declare function chaiHttp(chai: any, utils: any): void;

export default chaiHttp;

declare const request: Chai.ChaiHttpRequest;

export {request};

0 comments on commit ffb54a4

Please sign in to comment.