# supertest-session

> Cookie-based session persistence for Supertest

Latest version **5.0.1** (published 2023-08-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install supertest-session
pnpm add supertest-session
yarn add supertest-session
bun add supertest-session
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 5.0.1 |
| Published | 2023-08-01 |
| First published | 2013-11-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 13.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 88 |
| Author | RJ Zaworski |
| Maintainers | rjz, ctavan |
| Keywords | supertest, session, cookie |

## Links

- npm: https://www.npmjs.com/package/supertest-session
- Repository: https://github.com/rjz/supertest-session
- Homepage: https://github.com/rjz/supertest-session#readme
- Issues: https://github.com/rjz/supertest-session/issues
- npm.io page: https://npm.io/package/supertest-session

## Dependencies (3)

- [methods](https://npm.io/package/methods.md) ^1.1.2
- [cookiejar](https://npm.io/package/cookiejar.md) ^2.1.2
- [object-assign](https://npm.io/package/object-assign.md) ^4.0.1

## Alternatives

- [@pothos/plugin-authz](https://npm.io/package/@pothos/plugin-authz.md) — 12.4K weekly downloads
- [@bounded-sh/client](https://npm.io/package/@bounded-sh/client.md) — 3.2K weekly downloads
- [@luigi-project/plugin-auth-oauth2](https://npm.io/package/@luigi-project/plugin-auth-oauth2.md) — 2.3K weekly downloads
- [@nocobase/plugin-verification](https://npm.io/package/@nocobase/plugin-verification.md) — 2.0K weekly downloads
- [escher-request](https://npm.io/package/escher-request.md) — 545 weekly downloads

## Recent versions

- 5.0.1 (latest) — 2023-08-01
- 5.0.0 — 2023-08-01
- 4.1.0 — 2020-09-06
- 4.0.0 — 2019-03-28
- 3.3.0 — 2018-05-17
- 3.2.0 — 2018-04-17
- 3.1.2 — 2018-01-24
- 3.1.1 — 2018-01-23
- 3.1.0 — 2017-07-04
- 3.0.0 — 2017-01-04
- 2.0.1 — 2016-01-21
- 2.0.0 — 2015-11-07
- 1.2.0 — 2015-10-16
- 1.1.2 — 2015-10-12
- 1.1.1 — 2015-10-03
- … 9 more at https://npm.io/package/supertest-session/versions

## README

# Supertest sessions

Session wrapper around supertest.

[![Coverage
Status](https://coveralls.io/repos/rjz/supertest-session/badge.png)](https://coveralls.io/r/rjz/supertest-session)

References:

  * https://gist.github.com/joaoneto/5152248
  * https://github.com/visionmedia/supertest/issues/46
  * https://github.com/visionmedia/supertest/issues/26

## Installation

    $ npm install --save-dev supertest supertest-session

## Test

    $ npm test

## Usage

Require `supertest-session` and pass in the test application:

```js
var session = require('supertest-session');
var myApp = require('../../path/to/app');

var testSession = null;

beforeEach(function () {
  testSession = session(myApp);
});
```

And set some expectations:

```js
it('should fail accessing a restricted page', function (done) {
  testSession.get('/restricted')
    .expect(401)
    .end(done)
});

it('should sign in', function (done) {
  testSession.post('/signin')
    .send({ username: 'foo', password: 'password' })
    .expect(200)
    .end(done);
});
```

You can set preconditions:

```js
describe('after authenticating session', function () {

  var authenticatedSession;

  beforeEach(function (done) {
    testSession.post('/signin')
      .send({ username: 'foo', password: 'password' })
      .expect(200)
      .end(function (err) {
        if (err) return done(err);
        authenticatedSession = testSession;
        return done();
      });
  });

  it('should get a restricted page', function (done) {
    authenticatedSession.get('/restricted')
      .expect(200)
      .end(done)
  });

});

```

### Accessing cookies

The cookies attached to the session may be retrieved from `session.cookies`:

```js
var sessionCookie = testSession.cookies.find(function (cookie) {
  return cookie.name === connect.sid;
});
```

If you're using

### Request hooks

By default, supertest-session authenticates using session cookies. If your app
uses a custom strategy to restore sessions, you can provide `before` and `after`
hooks to adjust the request and inspect the response:

```js
var testSession = session(myApp, {
  before: function (req) {
    req.set('authorization', 'Basic aGVsbG86d29ybGQK');
  }
});
```

### Cookie Jar Access Options

By default supertest-session will derive the CookieAccessInfo config of the cookie jar from the
agent configuration. There might be cases where you want to override this, e.g. if you're testing
a service which is configured to run behind a proxy but which [sets secure
cookies](https://expressjs.com/en/api.html#req.secure). To have supertest-session expose these
secure cookies you can provide an override config to the internal call to
[CookieAccessInfo](https://github.com/bmeck/node-cookiejar#cookieaccessinfodomainpathsecurescript):

```js
var cookieAccess = {
  domain: 'example.com',
  path: '/testpath',
  secure: true,
  script: true,
};
var testSession = session(myApp, { cookieAccess: cookieAccess });
```

By default the underlying `supertest` agent will still determine the CookieAccessInfo from the URL.
If you want supertest-session to instead send cookies according to this `cookieAccess` config you
can make use of the `before` hook:

```js
var cookieAccess = {
  domain: 'example.com',
  path: '/testpath',
  secure: true,
  script: true,
};
var testSession = session(myApp, {
  cookieAccess: cookieAccess,
  before: function (req) {
    req.cookies = this.cookies.toValueString();
  },
});
```

## License

MIT

---
_Source: https://npm.io/package/supertest-session · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._