`js
const users = {
'secret-token': 'ExampleUser',
}

/**
* User Authentication Route.
* @param {http.IncomingMessage} req
* @param {http.ServerResponse} res
*/
const middleware = (req, res) => {
const token = req.headers['x-auth']
if (!token) throw new Error('The authentication is required.')
const user = users[token]
if (!user) throw new Error('The user is not found.')
res.setHeader('set-cookie', user=${user})
res.end(Hello, ${user})
}

export default middleware

/**
* @typedef {import('http').IncomingMessage} http.IncomingMessage
* @typedef {import('http').ServerResponse} http.ServerResponse
*/
`


`
example/test/spec/default.js
✓ prevents unauthorised
✓ does not find the user
✓ authenticates known user

🦅 Executed 3 tests.
`


`js
/**
* Creates a middleware for the given list of users.
* @param {Object} users
*/
const makeMiddleware = (users) => {
/**
* Updates the request to have the user information if the token is found.
* @param {http.IncomingMessage} req
*/
const middleware = (req) => {
const token = req.headers['x-auth']
const user = users[token]
if (user) req['user'] = user
}
return middleware
}

export default makeMiddleware

/**
* @typedef {import('http').IncomingMessage} http.IncomingMessage
* @typedef {import('http').ServerResponse} http.ServerResponse
*/
`


`js
import { ok, equal } from 'assert'
import HttpContext from '@contexts/http'
import createMiddleware from '../../src/constructor'

class Context {
/**
* Creates a request listener for testing.
* @param {function(http.IncomingMessage, http.ServerResponse)} next
* Assertion method.
* @param {Object} [users] The list of tokens-users.
*/
c(next, users = {}) {
return (req, res) => {
const mw = createMiddleware(users)
mw(req, res) // set the user on request
next(req, res)
}
}
}

/* @type {Object/
const TS = {
context: [Context, HttpContext],
async 'does not set the user without token'({ c }, { start }) {
await start(c((req) => {
ok(!req.user)
}))
.get('/')
.assert(200)
},
async 'does not set the user with missing token'({ c }, { start }) {
await start(c((req) => {
ok(!req.user)
}), { 'secret-token': 'User' })
.set('x-auth', 'missing-token')
.get('/')
.assert(200)
},
async 'sets the user with https'({ c }, { start }) {
await start(c((req) => {
ok(req.user)
ok(req.connection.encrypted)
}, { 'secret-token': 'User' }), true)
.set('x-auth', 'secret-token')
.get('/')
.assert(200)
},
async 'sets the correct name'({ c }, { start }) {
await start(c((req) => {
equal(req.user, 'Expected-User')
}, { 'secret-token': 'Actual-User' }))
.set('x-auth', 'secret-token')
.get('/')
.assert(200) // expecting fail
},
}

export default TS

/**
* @typedef {import('http').IncomingMessage} http.IncomingMessage
* @typedef {import('http').ServerResponse} http.ServerResponse
*/
`


`
example/test/spec/constructor.js
✓ does not set the user without token
✓ does not set the user with missing token
✓ sets the user with https
✗ sets the correct name
| Error: 500 == 200 'Actual-User' == 'Expected-User'
| at sets the correct name (example/test/spec/constructor.js:54:8)

example/test/spec/constructor.js > sets the correct name
Error: 500 == 200 'Actual-User' == 'Expected-User'
at sets the correct name (example/test/spec/constructor.js:54:8)

🦅 Executed 4 tests: 1 error.
`


`js
import Http from '@contexts/http'

/* @type {Object/
const TS = {
context: Http,
async 'sets the status code and body'(
{ startPlain }) {
await startPlain((req, res) => {
res.statusCode = 200
res.end('Hello World')
})
.get('/')
.assert(200, 'Hello World')
},
// expect to fail with global error
async 'throws an error'({ startPlain }) {
await startPlain(() => {
throw new Error('Unhandled error.')
})
.get('/')
},
// expect to timeout
async 'does not finish the request'(
{ startPlain }) {
await startPlain((req, res) => {
res.write('hello')
})
.get('/')
},
}

export default TS
`


`js
class C {
c(listener) {
return (req, res) => {
try {
listener(req, res)
} catch (err) {
res.statusCode = 500
} finally {
res.end()
}
}
}
}

/* @type {Object/
export const handled = {
context: [C, Http],
async 'throws an error'({ c },
{ startPlain }) {
await startPlain(c(() => {
throw new Error('Unhandled error.')
}))
.get('/')
.assert(500)
},
async 'times out'({ c }, { startPlain }) {
await startPlain(c((req, res) => {
res.write('hello')
}))
.get('/')
.assert(200, 'hello')
},
}
`


`
example/test/spec/plain
handled
✓ throws an error
✓ times out
plain
✓ sets the status code and body
✗ throws an error
| Error: Unhandled error.
| at startPlain (example/test/spec/plain/plain.js:18:13)
| at Server.handler (src/index.js:88:15)
✗ does not finish the request
| Error: Test has timed out after 200ms

example/test/spec/plain > plain > throws an error
Error: Unhandled error.
at startPlain (example/test/spec/plain/plain.js:18:13)
at Server.handler (src/index.js:88:15)

example/test/spec/plain > plain > does not finish the request
Error: Test has timed out after 200ms

🦅 Executed 5 tests: 2 errors.
`


`js
import { createServer } from 'http'
import connect from 'connect'

const app = connect()
app.use((req, res, next) => {
if (req.url == '/error')
throw new Error('Uncaught error')
res.write('hello, ')
next()
})
app.use((req, res) => {
res.statusCode = 200
res.end('world!')
})

export default createServer(app)
`


`js
import H from '@contexts/http'
import server from '../../src/server'

/* @type {Object/
const TS = {
context: H,
async 'access the server'({ listen }) {
await listen(server)
.get('/')
.assert(200, 'hello, world!')
},
async 'connect catches errors'({ listen }) {
await listen(server)
.get('/error')
.assert(500)
},
}

export default TS
`


`
example/test/spec/listen.js
✓ access the server
✓ connect catches errors

🦅 Executed 2 tests.
`


`js
async 'sets the code to 200'({ start, debug }) {
debug()
await start(middleware)
.get()
.assert(200)
},
`


`
example/test/spec/debug.js
✗ sets the code to 200
| Error: 500 == 200 The authentication is required.
| at sets the code to 200 (example/test/spec/debug.js:12:8)

example/test/spec/debug.js > sets the code to 200
Error: 500 == 200 The authentication is required.
at sets the code to 200 (example/test/spec/debug.js:12:8)

🦅 Executed 1 test: 1 error.
`


`
Error: The authentication is required.
at middleware (/Users/zavr/idiocc/http/example/src/index.js:12:21)
at Server.handler (/Users/zavr/idiocc/http/src/index.js:67:15)
`


Send a GET request. View examples at Wiki
`js
async 'redirects to /'({ start }) {
await start(middleware)
.get()
.assert(302)
.assert('location', 'index.html')
},
async 'opens sitemap'({ start }) {
await start(middleware)
.get('/sitemap')
.assert(200)
},
`


Send a request for the Allow and CORS pre-flight headers.
`js
async 'sends options request'({ start }) {
let method
await start((req, res) => {
method = req.method
res.setHeader('allow', 'HEAD, GET')
res.statusCode = 204
})
.options('/')
.assert(204)
.assert('allow', 'HEAD, GET')
equal(method, 'OPTIONS')
},
`


Send a HEAD request. View examples at Wiki
`js
async 'sends redirect for index'({ start }) {
await start(middleware)
.head()
.assert(302)
.assert('location', 'index.html')
},
async 'sends 200 for sitemap'({ start }) {
await start(middleware)
.head('/sitemap')
.assert(200)
},
`


`js
async 'status code'({ startPlain }) {
await startPlain((_, res) => {
res.statusCode = 205
res.end()
})
.get()
.assert(205)
},
async 'status code with message'({ startPlain }) {
await startPlain((_, res) => {
res.statusCode = 205
res.end('example')
})
.get('/sitemap')
.assert(205, 'example')
},
async 'status code with regexp'({ startPlain }) {
await startPlain((_, res) => {
res.statusCode = 205
res.end('Example')
})
.get('/sitemap')
.assert(205, /example/i)
},
async 'status code with json'({ startPlain }) {
await startPlain((_, res) => {
res.statusCode = 205
res.setHeader('content-type', 'application/json')
res.end(JSON.stringify({ hello: 'world' }))
})
.get('/sitemap')
.assert(205, { hello: 'world' })
},
`


`
example/test/spec/assert/code.js
✓ status code
✓ status code with message
✓ status code with regexp
✓ status code with json

🦅 Executed 4 tests.
`


`js
// pass
async 'header'({ startPlain }) {
await startPlain((_, res) => {
res.statusCode = 205
res.setHeader('content-type',
'application/json')
res.end('[]')
})
.get('/sitemap')
.assert(205)
.assert('content-type',
'application/json')
},
async 'header with regexp'({ startPlain }) {
await startPlain((_, res) => {
res.setHeader('content-type',
'application/json; charset=utf-8')
res.end('[]')
})
.get('/')
.assert('content-type',
/application\/json/)
},
async 'absence of a header'({ startPlain }) {
await startPlain((_, res) => {


res.end()
})
.get('/sitemap')
.assert('content-type', null)
},
`


`js
// fail
async 'header'({ startPlain }) {
await startPlain((_, res) => {
res.statusCode = 205
res.setHeader('content-type',
'application/xml')
res.end('')
})
.get('/sitemap')
.assert(205)
.assert('content-type',
'application/json')
},
async 'header with regexp'({ startPlain }) {
await startPlain((_, res) => {
res.setHeader('content-type',
'application/json; charset=utf-8')
res.end('[]')
})
.get('/')
.assert('content-type',
/application\/xml/)
},
async 'absence of a header'({ startPlain }) {
await startPlain((_, res) => {
res.setHeader('content-type',
'text/plain')
res.end()
})
.get('/sitemap')
.assert('content-type', null)
},
`


`js
async 'using a function'({ start }) {
await start((_, res) => {
res.statusCode = 205
res.setHeader('content-type', 'application/xml')
res.end()
})
.get('/sitemap')
.assert((res) => {
equal(res.headers['content-type'],
'application/xml')
})
},
async 'with response object'({ start, getResponse }) {
await start((_, res) => {
res.setHeader('content-type', 'application/xml')
res.end()
})
.get('/sitemap')
.assert(() => {
const res = getResponse()
equal(res.getHeader('content-type'),
'application/xml')
})
},
`


`
example/test/spec/assert/function.js
✓ using a function
✓ with response object

🦅 Executed 2 tests.
`


`js
async 'sets the header'({ startPlain }) {
await startPlain((req, res) => {
if (req.headers['x-auth'] == 'token') {
res.statusCode = 205
res.end('hello')
} else {
res.statusCode = 403
res.end('forbidden')
}
})
.set('x-auth', 'token')
.get()
.assert(205)
},
`


`js
async 'sets a header with a function'({ start }) {
let cookie
await start((req, res) => {
res.setHeader('x-test', 'world')
res.end(req.headers['test'])
})
.set('test', 'hello')
.get('/')
.assert(200, 'hello')
.assert(({ headers: h }) => {
cookie = h['x-test']
})
.set('test', () => cookie)
.get('/')
.assert(200, 'world')
},
`


`js
async 'posts string data'({ startPlain }, { middleware }) {
await startPlain(middleware)
.post('/submit', 'hello')
.assert(200, Received data: hello
+ with Content-Type text/plain)
},
async 'posts object data'({ startPlain }, { middleware }) {
await startPlain(middleware)
.post('/submit', { test: 'ok' })
.assert(200, Received data: {"test":"ok"}
+ with Content-Type application/json)
},
async 'posts urlencoded data'({ startPlain }, { middleware }) {
await startPlain(middleware)
.post('/submit', { test: 'ok' }, {
type: 'form',
headers: {
'User-Agent': 'testing',
},
})
.assert(200, Received data: test=ok
+ with Content-Type application/x-www-form-urlencoded
+ and User-Agent testing)
},
`


`js
async 'posts multipart/form-data'({ startPlain }, { middleware }) {
await startPlain(middleware)
.postForm('/submit', async (form) => {
form.addSection('field', 'hello-world')
await form.addFile('test/fixture/test.txt', 'file')
await form.addFile('test/fixture/test.txt', 'file', {
filename: 'testfile.txt',
})
})
.assert(200, [
[ 'field', 'hello-world', '7bit', 'text/plain' ],
[ 'file', 'test.txt', '7bit', 'application/octet-stream' ],
[ 'file', 'testfile.txt', '7bit', 'application/octet-stream' ],
])
},
`


`js
import HttpContext from '../../src'

/* @type {TestSuite} /
export const viaSessionMethod = {
context: HttpContext,
async 'maintains the session'({ start, debug }) {
debug()
await start((req, res) => {
if (req.url == '/') {
res.setHeader('set-cookie', 'koa:sess=eyJtZ; path=/; httponly')
res.end('hello world')
} else if (req.url == '/exit') {
res.setHeader('set-cookie', 'koa:sess=; path=/; httponly')
res.end()
} else if (req.url == '/test') {
res.end(req.headers['cookie'])
}
})
.session()
.get('/')
.assert(200, 'hello world')
.set('Cookie', 'testing=true')
.get('/test')
.assert(200, 'koa:sess=eyJtZ;testing=true')
.get('/exit')
.get('/test')
.assert(200, 'testing=true')
},
}

/* @type {TestSuite} /
export const viaExtendingContext = {
context: class extends HttpContext {
constructor() {
super()
this.session = true
}
},
async 'maintains the session'({ start, debug }) {
debug()
await start((req, res) => {
if (req.url == '/') {
res.setHeader('set-cookie', 'koa:sess=eyJtZ; path=/; httponly')
res.end('hello world')
} else if (req.url == '/exit') {
res.setHeader('set-cookie', 'koa:sess=; path=/; httponly')
res.end()
} else if (req.url == '/test') {
res.end(req.headers['cookie'])
}
})
.get('/')
.assert(200, 'hello world')
.get('/test')
.assert(200, 'koa:sess=eyJtZ')
.get('/exit')
.get('/test')
.assert(200, '')
},
}

/* @typedef {import('../context').TestSuite} TestSuite /
`


`js
import Http from '@context/http'
import CookiesTester from './tester'
import mistmatch from 'mismatch'

/**
* Extends _HTTPContext_ to assert on the cookies.
*/
export default class Cookies extends Http {
constructor() {
super()
this.TesterConstructor = CookiesTester
/**
* Parsed cookies.
* @private
*/
this._cookies = null
}
/**
* Creates a server and wraps the supplied listener in the handler that will
* set status code 500 if the listener threw and the body to the error text.
* @param {function(http.IncomingMessage, http.ServerResponse)} fn
* @param {boolean} secure
*/
start(fn, secure) {
const tester = /* @type {CookiesTester} / (super.start(fn, secure))
return tester
}
/**
* Creates a server with the supplied listener.
* @param {function(http.IncomingMessage, http.ServerResponse)} fn
* @param {boolean} secure
*/
startPlain(fn, secure) {
const tester = /* @type {CookiesTester} / (super.startPlain(fn, secure))
return tester
}
getCookies() {
if (this._cookies) return this._cookies
const setCookies = /* @type {Array} /
(this.tester.res.headers['set-cookie']) || []
const res = setCookies.map(Cookies.parseSetCookie)
this._cookies = res
return res
}
/**
* Parses the set-cookie header.
* @param {string} header
*/
static parseSetCookie(header) {
const pattern = /\s([^=;]+)(?:=([^;]);?|;|$)/g

const pairs = mistmatch(pattern, header, ['name', 'value'])

/* @type {{ name: string, value: string }} /
const cookie = pairs.shift()

for (let i = 0; i < pairs.length; i++) {
const match = pairs[i]
cookie[match.name.toLowerCase()] = (match.value || true)
}

return cookie
}
/**
* Returns the cookie record for the given name.
* @param {string} name
*/
getCookieForName(name) {
const cookies = this.getCookies()

return cookies.find(({ name: n }) => {
return name == n
})
}
_reset() {
super._reset()
this._cookies = null
}
}
`


`js
import { Tester } from '@context/http'
import erotic from 'erotic'

/**
* The tester for assertion on cookies.
*/
export class CookiesTester extends Tester {
constructor() {
super()
/* @type {import('./').default} /
this.context = null
}
/**
* Assert on the number of times the cookie was set.
* @param {number} num The expected count.
*/
count(num) {
const e = erotic(true)
this._addLink(() => {
const count = this.context.getCookies().length
equal(count, num, 'Should set cookie ' + num + ' times, not ' + count + '.')
}, e)
return this
}

/**
* Asserts on the value of the cookie.
* @param {string} name The name of the cookie.
* @param {string} val The value of the cookie.
*/
value(name, val) {
const e = erotic(true)
this._addLink(() => {
const cookie = this.context.getCookieForName(name)
ok(cookie, wasExpectedError('Cookie', name, val))
equal(cookie.value, val,
didNotMatchValue('Cookie', name, val, cookie.value))
}, e)
return this
}
/**
* Asserts on the presence of an attribute in the cookie.
* @param {string} name The name of the cookie.
* @param {string} attrib The name of the attribute.
*/
attribute(name, attrib) {
const e = erotic(true)
this._addLink(() => {
const cookie = this.context.getCookieForName(name)
assertAttribute(name, cookie, attrib)
}, e)
return this
}
}
`


`
example/test/spec/cookie/
✓ sets the HttpOnly cookie
✓ deletes the cookie
✗ sets cookie for a path
| Error: Attribute path of cookie example was expected.
| at sets cookie for a path (example/test/spec/cookie/default.js:32:8)

example/test/spec/cookie/ > sets cookie for a path
Error: Attribute path of cookie example was expected.
at sets cookie for a path (example/test/spec/cookie/default.js:32:8)

🦅 Executed 3 tests: 1 error.
`