To test the Web Annotation Protocol, I started by implementing it within the Web Platform Tests<\/a> system frequently used to test browser-side JavaScript APIs specified by various W3C Working Groups. I sat down to write some Python, receive some HTTP requests, and return some JSON.<\/p>\n However, things quickly got bothersome as testing the internal Python API was only part of the puzzle. I needed to be sure So I ended up testing my test server via a thing called SuperTest.<\/p>\n SuperTest<\/a> is built on the fabulous Node and browser HTTP client called SuperAgent<\/a>.<\/p>\n Here\u2019s what SuperAgent code to send a POST request looks like (cribbing from their opening example):<\/p>\n SuperTest extends that basic (and wonderfully obvious) API with a singular Tasty tests (for me, anyhow) start with some Mocha and some Chai!<\/p>\n Here\u2019s one of the tests (along with the basic setup) that I\u2019ve cribbed from my Web Annotation Protocol Tester<\/a> code:<\/p>\n When run, this outputs a command line report that looks similar to this screenshot:<\/p>\n One thing I like about the mix of Mocha, Chai, and SuperTest is this \u201cspec\u201d report output. In this case, I\u2019ve mapped the various test suites directly to the sections of the Web Annotation Protocol<\/a> and written SuperTest requests to generate HTTP client requests in order to test the server that claims to implement the protocol.<\/p>\n The first of these example tests uses some simple Chai I built the Web Annotation Protocol Tester to test my personal implementations of the Web Annotation Protocol. The code and runtime environment is deliberately separate from the the server and intentionally designed to test any implementation of the Web Annotation Protocol. I didn\u2019t want to put these tests near the server code for fear of \u201ccheating\u201d or mixing them with code-level tests.<\/p>\n The different sort of separation of concerns works as a handy forcing agent to induce good habits on the protocol implementer. It\u2019s TDD for APIs.<\/p>\n You can quaff more Mocha and Chai by digging into their documentation. Today, we\u2019ll focus on SuperTest\u2019s superness!<\/p>\n The SuperTest API<\/a> adds the single In all these cases, the Asserting the response status code is something you\u2019ll do quite often. Use the number of the HTTP Status Code for the value of Check out httpstat.us<\/a> or httpstatus.es<\/a> or http.cat<\/a> if you need help deciding which status to check (or if you just need a great cat photo to display along with the error message).<\/p>\n For instance:<\/p>\n As in the previous section, This one can be very handy for testing error code messages, such as:<\/p>\n Or you may just want to be sure a certain key is returned in the JSON object if the response was successful:<\/p>\n You can also do an exact match on the parsed JSON object (assuming you\u2019re using JSON). See the next section for an example.<\/p>\n In this case, you can focus your error message on the problems with the content of the response. For example:<\/p>\n Often, though, you\u2019ll want to do more than a singe RegEx check on the response content. Hang in there, that option\u2019s around the corner!<\/p>\n Asserting a header field and its value is one of the most common API tests. Here you can use a string equivalency test or a RegEx. Which one you pick will really just depend on the header you\u2019re checking. We saw the RegEx option in use with the This is the catch-all This is the most obvious place to do multiple key existence checking in your JSON documents:<\/p>\n Now that all those expectations are set in your tests, you can make some clean console output in conclusion. If you add an Additionally, it serves as an obvious statement that your code will perform the request and expectations you\u2019ve set and then invoke So, the next time you\u2019re building an API and you want to be sure it\u2019s meaningful<\/a> or doing that hypermedia<\/a> thing, grab a can of SuperTest. It\u2019s proven to find errors you didn\u2019t know your API had and in at least half the time it takes to run those tests over and over using curl<\/code> and the browsers would get the correct output from my API, and<\/em> I needed the ability to test it from \u201cacross the Web\u201d where the various intermediaries (proxies, coffee shops, etc.) might interfere.<\/p>\nMeet SuperTest<\/h2>\n
request\r\n .post('\/api\/pet')\r\n .send({ name: 'Manny', species: 'cat' })\r\n .set('X-API-Key', 'foobar')\r\n .set('Accept', 'application\/json')\r\n .end(function(err, res){\r\n if (err || !res.ok) {\r\n alert('Oh no! error');\r\n } else {\r\n alert('yay got ' + JSON.stringify(res.body));\r\n }\r\n });<\/pre>\n.expect()<\/code> function. With that singular addition, you can expect all kinds of things!<\/p>\nBut First, Mix In Some Chai(.js)<\/h2>\n
\n
\/\/ pull in assert.isTrue() and the rest\r\nvar assert = require('chai').assert;\r\nvar request = require('supertest');\r\nvar uuid = require('node-uuid');\r\n\r\nvar host_url = 'http:\/\/localhost:8080'\r\nvar container_url = host_url + '\/annotations\/';\r\n\r\ndescribe('MUSTs', function() {\r\n describe('4. Annotation Containers', function() {\r\n it.skip('An Annotation Server MUST provide one or more Containers');\r\n it('MUST end in a \"\/\" character', function(done) {\r\n assert.isTrue(container_url[container_url.length-1] === '\/');\r\n done();\r\n });\r\n });\r\n\r\n describe('4.1 Container Retrieval', function() {\r\n container = request(container_url);\r\n it('MUST support GET, HEAD, and OPTIONs methods', function(done) {\r\n container\r\n .get('')\r\n .expect('Allow', \/GET\/)\r\n .expect('Allow', \/HEAD\/)\r\n .expect('Allow', \/OPTIONS\/)\r\n .expect(200, done);\r\n });\r\n });\r\n});<\/pre>\n![\"screenshot\"](\"http:\/\/www.webcodegeeks.com\/wp-content\/uploads\/2016\/07\/screenshot.png\")
<\/a><\/p>\nassert.isTrue()<\/code> goodness to check the shape of a URL. The second uses SuperTest to check that the Allow<\/code> header is set and that it includes GET<\/code>, HEAD<\/code>, and OPTIONS<\/code> methods. This means the server is claiming it allows those methods on the requested resource. There are other tests which test each of those actual methods.<\/p>\nSetting Expectations<\/h2>\n
.expect()<\/code> method to the SuperAgent API<\/a>. This single method, though, has a wide range of uses, which we\u2019ll explore in the next few sections.<\/p>\nfn<\/code> function receives the current err<\/code>. If no function is passed, an error will be thrown. However, if there is an .end()<\/code> function, errors will be passed to that and can be re-thrown or passed to Chai\u2019s done()<\/code> method.<\/p><\/blockquote>\n.expect(status[, fn])<\/h2>\n
status<\/code>.<\/p>\n![\"416\"](\"http:\/\/www.webcodegeeks.com\/wp-content\/uploads\/2016\/07\/416.jpg\")
<\/a><\/p>\n.expect(status, body[, fn])<\/h2>\n
status<\/code> is a number, and body<\/code> can be either a string (for an exact match scenario) or a regular expression (which is likely more useful).<\/p>\nrequest(base_url).get(broken_url).expect(404, \/not found\/ig);<\/pre>\n
request(base_url).get(broken_url).expect(201, \/created\/ig);<\/pre>\n
.expect(body[, fn])<\/h2>\n
request(base_url).get('users').expect(\/total\/, function() {\r\n throw new Error('Users list must have a `total` key);\r\n});<\/pre>\n.expect(field, value[, fn])<\/h2>\n
Allow<\/code> headers in the Web Annotation Protocol example. Here\u2019s a scenario where you might want an exact match:<\/p>\nrequest(base_url).get('users').expect('Content-Type', 'application\/json', function() {\r\n throw new Error('Default response MUST be in `application\/json`);\r\n});<\/pre>\n.expect(function(res) {})<\/h2>\n
.expect<\/code> option for checking the request according to anything not handled by the earlier examples. You get the whole request object sent down from SuperAgent<\/a>. Which means, your test function will have access to the raw response text (res.text<\/code>), the parsed response content (res.body<\/code>), the headers (res.header<\/code> as an array with headers lowercased), the media type (res.type<\/code>), the character set (res.charset<\/code>), and of course the status.<\/p>\nrequest(base_url).get('users').expect(function(res) {\r\n if (!('total' in res.body) && !('first' in res.body)) {\r\n throw new Error('Missing pagination information and hypermedia controls');\r\n }\r\n});<\/pre>\nHere\u2019s How it
.end(fn)<\/code>s<\/h2>\n.end()<\/code> method to your chain of .expect()<\/code> calls, it will get whatever error is thrown handed down. In addition to the error, this method also gets the response for one last processing, logging, or whatever.<\/p>\nfn(err, res)<\/code>.<\/p>\nrequest(base_url).get('users')\r\n .expect('Content-Type', 'application\/json', function() {\r\n throw new Error('Default response MUST be in `application\/json`);\r\n })\r\n .expect(200)\r\n .expect(function(res) {\r\n if (!('total' in res.body) && !('first' in res.body)) {\r\n throw new Error('Missing pagination information and hypermedia controls');\r\n }\r\n })\r\n .expect(function(err, res) {\r\n \/\/ in this case, just rethrow it via Chai\r\n if (err) return done(err);\r\n \/\/ or if successful, just be done\r\n done();\r\n });<\/pre>\nSuperTest Your API!<\/h2>\n
curl<\/code> or a browser and reading the output with your eyes.<\/p>\n