Merge pull request #868 from dmurvihill/cookie-assertions

Add cookie assertions framework

Author: titanism

LICENSE

@@ -1,6 +1,7 @@
 (The MIT License)
 
-Copyright (c) 2014 TJ Holowaychuk <[email protected]>
+Copyright (c) 2014 TJ Holowaychuk <[email protected]> and other
+contributors.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

README.md

@@ -319,6 +319,138 @@ function hasPreviousAndNextKeys(res) {
 
 Perform the request and invoke `fn(err, res)`.
 
+## Cookies
+
+Here is an example of using the `set` and `not` cookie assertions:
+
+```js
+// setup super-test
+const request = require('supertest');
+const express = require('express');
+const cookies = request.cookies;
+
+// setup express test service
+const app = express();
+
+app.get('/users', function(req, res) {
+  res.cookie('alpha', 'one', { domain: 'domain.com', path: '/', httpOnly: true });
+  res.send(200, { name: 'tobi' });
+});
+
+// test request to service
+request(app)
+  .get('/users')
+  .expect('Content-Type', /json/)
+  .expect('Content-Length', '15')
+  .expect(200)
+  // assert 'alpha' cookie is set with domain, path, and httpOnly options
+  .expect(cookies.set({ name: 'alpha', options: ['domain', 'path', 'httponly'] }))
+  // assert 'bravo' cookie is NOT set
+  .expect(cookies.not('set', { name: 'bravo' }))
+  .end(function(err, res) {
+    if (err) {
+      throw err;
+    }
+  });
+```
+
+It is also possible to chain assertions:
+
+```js
+cookies.set({/* ... */}).not('set', {/* ... */})
+```
+
+### Cookie assertions
+
+Functions and methods are chainable.
+
+#### cookies([secret], [asserts])
+
+Get assertion function for [super-test](https://github.com/visionmedia/supertest) `.expect()` method.
+
+*Arguments*
+
+- `secret` - String or array of strings. Cookie signature secrets.
+- `asserts(req, res)` - Function or array of functions. Failed custom assertions should throw.
+
+#### .set(expects, [assert])
+
+Assert that cookie and options are set.
+
+*Arguments*
+
+- `expects` - Object or array of objects.
+  - `name` - String name of cookie.
+  - `options` - *Optional* array of options.
+- `assert` - *Optional* boolean "assert true" modifier. Default: `true`.
+
+#### .reset(expects, [assert])
+
+Assert that cookie is set and was already set (in request headers).
+
+*Arguments*
+
+- `expects` - Object or array of objects.
+  - `name` - String name of cookie.
+- `assert` - *Optional* boolean "assert true" modifier. Default: `true`.
+
+#### .new(expects, [assert])
+
+Assert that cookie is set and was NOT already set (NOT in request headers).
+
+*Arguments*
+
+- `expects` - Object or array of objects.
+  - `name` - String name of cookie.
+- `assert` - *Optional* boolean "assert true" modifier. Default: `true`.
+
+#### .renew(expects, [assert])
+
+Assert that cookie is set with a strictly greater `expires` or `max-age` than the given value.
+
+*Arguments*
+
+- `expects` - Object or array of objects.
+  - `name` - String name of cookie.
+  - `options` - Object of options. `use one of two options below`
+  - `options`.`expires` - String UTC expiration for original cookie (in request headers).
+  - `options`.`max-age` - Integer ttl in seconds for original cookie (in request headers).
+- `assert` - *Optional* boolean "assert true" modifier. Default: `true`.
+
+#### .contain(expects, [assert])
+
+Assert that cookie is set with value and contains options.
+
+Requires `cookies(secret)` initialization if cookie is signed.
+
+*Arguments*
+
+- `expects` - Object or array of objects.
+  - `name` - String name of cookie.
+  - `value` - *Optional* string unsigned value of cookie.
+  - `options` - *Optional* object of options.
+  - `options`.`domain` - *Optional* string domain.
+  - `options`.`path` - *Optional* string path.
+  - `options`.`expires` - *Optional* string UTC expiration.
+  - `options`.`max-age` - *Optional* integer ttl, in seconds.
+  - `options`.`secure` - *Optional* boolean secure flag.
+  - `options`.`httponly` - *Optional* boolean httpOnly flag.
+- `assert` - *Optional* boolean "assert true" modifier. Default: `true`.
+
+#### .not(method, expects)
+
+Call any cookies assertion method with "assert true" modifier set to `false`.
+
+Syntactic sugar.
+
+*Arguments*
+
+- `method` - String method name. Arguments of method name apply in `expects`.
+- `expects` - Object or array of objects.
+  - `name` - String name of cookie.
+  - `value` - *Optional* string unsigned value of cookie.
+  - `options` - *Optional* object of options.
+
 ## Notes
 
 Inspired by [api-easy](https://github.com/flatiron/api-easy) minus vows coupling.

index.js

@@ -12,6 +12,7 @@ try {
 }
 const Test = require('./lib/test.js');
 const agent = require('./lib/agent.js');
+const cookies = require('./lib/cookies');
 
 /**
  * Test against the given `app`,
@@ -59,3 +60,8 @@ module.exports.Test = Test;
  * Expose the agent function
  */
 module.exports.agent = agent;
+
+/**
+ * Expose cookie assertions
+ */
+module.exports.cookies = cookies;