Cookie-based session persistence for Supertest

Usage no npm install needed!

<script type="module">
  import contentpassSupertestSession from 'https://cdn.skypack.dev/@contentpass/supertest-session';


Supertest sessions

Session wrapper around supertest.

Build Status Coverage Status



$ npm install supertest supertest-session


$ npm test


Require supertest-session and pass in the test application:

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

var testSession = null;

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

And set some expectations:

it('should fail accessing a restricted page', function (done) {

it('should sign in', function (done) {
    .send({ username: 'foo', password: 'password' })

You can set preconditions:

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

  var authenticatedSession;

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

  it('should get a restricted page', function (done) {


Accessing cookies

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

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:

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. To have supertest-session expose these secure cookies you can provide an override config to the internal call to CookieAccessInfo:

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