{"id":15510,"date":"2016-12-28T12:15:36","date_gmt":"2016-12-28T10:15:36","guid":{"rendered":"https:\/\/www.webcodegeeks.com\/?p=15510"},"modified":"2016-12-23T14:24:15","modified_gmt":"2016-12-23T12:24:15","slug":"testing-code-examples-documentation","status":"publish","type":"post","link":"https:\/\/www.webcodegeeks.com\/web-development\/testing-code-examples-documentation\/","title":{"rendered":"Testing Code Examples in Documentation"},"content":{"rendered":"

In my last post, I covered how to improve the written component of your documentation<\/a> with automated spell-checking and suggestions for better writing. In this post, I\u2019ll cover the code component of good documentation; trying an example and finding it doesn\u2019t work is a sure-fire way to annoy a reader.<\/p>\n

The techniques for testing code fall into two distinct camps, depending on what you\u2019re testing. Again, I will present one example in detail and then link to alternatives with similar functionality.<\/p>\n

Testing API Examples with Dredd<\/h2>\n

Whether you generate your API documentation from the source code or write it externally, the more distinct nature of an (your) API makes it easier to test. Tooling options also frequently offer the auto-generation of examples as well as tests, automating even more mundane tasks for you.<\/p>\n

Dredd<\/h3>\n

I have had the most experience with using Dredd<\/a>. It works with API documentation outlined in the swagger<\/a> and API blueprint<\/a> formats, so documentation is written externally to your API source code.<\/p>\n

I will use the Marvel API<\/a> as an example for this section. Instead of attempting to create an entire API definition of the API from scratch, I found an existing API Blueprint file floating on the internet and created a demo project around it. You can find the project on GitHub<\/a>.<\/p>\n

I\u2019ll only cover the essentials of what\u2019s inside the projects. Otherwise this article would turn into a fully fledged API Blueprint and Dredd tutorial.<\/p>\n

The API definitions in the file I found are out of date, so running the tests will fail. I decided to leave this as is for a couple reasons. First, you\u2019ll still be able to appreciate the setup process for Dredd and its potential. Also it\u2019s unlikely that you want to test the Marvel API. Unless you work for Marvel, in which case, release an updated file &#55357;&#56861;.<\/p>\n

As Dredd integrates with Node and npm, you can use the default setup with a new Codeship project, selecting node.js<\/em> as the language of the project.<\/p>\n

<\/a><\/p>\n

The dependencies defined in package.json<\/em> are:<\/p>\n

...\r\n\"dependencies\": {\r\n  \"dredd\": \"^2.2.5\",\r\n  \"md5\": \"^2.1.0\",\r\n  \"dotenv\": \"^2.0.0\"\r\n}\r\n...<\/pre>\n
With most needed for using the Marvel API, not Dredd.<\/p>\n
<\/a><\/p>\n
And the test command defined in package.json<\/em> is:<\/p>\n
...\r\n\"scripts\": {\r\n   \"test\": \"dredd\"\r\n }\r\n...<\/pre>\n
The final piece of the setup puzzle is the dredd.yml<\/em> configuration file, which you can auto-generate with the dredd init<\/code> command. The overridden settings are:<\/p>\n
hookfiles: .\/hooks.js\r\nlanguage: nodejs\r\nconfig: .\/dredd.yml\r\nblueprint: marvel.apib\r\nendpoint: 'https:\/\/gateway.marvel.com:443\/v1\/public\/'<\/pre>\n
You can find more here about Dredd configuration in their documentation<\/a>.<\/p>\n
You can find the API definitions in the marvel.apib<\/em> file, which are a series of endpoints, with parameters passed to them and an expected response. The API Blueprint format is standard markdown with extras added for API modelling, which means it\u2019s well-suited for adding good explanatory text around the API definitions.<\/p>\n
All calls to the Marvel API need an apikey<\/code> parameter appended, constructed in a slightly complicated way<\/a>. You could add this as a parameter to every endpoint definition, but there\u2019s a much better way.<\/p>\n
Dredd\u2019s \u2018hooks<\/a>\u2018 feature allows you to interrupt the processing flow and make amendments. The hooks.js<\/em> file below interrupts every API call before it\u2019s sent to the API and adds the apikey<\/code> that the Marvel API expects:<\/p>\n
'use strict';\r\n\r\nrequire('dotenv').config();\r\n\r\nvar hooks = require('hooks');\r\nvar md5 = require('md5');\r\n\r\nhooks.beforeEach(function (transaction) {\r\n  var publicKey = process.env.MARVEL_PUBLIC_KEY;\r\n  var privateKey = process.env.MARVEL_PRIVATE_KEY;\r\n  var ts = String(new Date().getTime());\r\n  var hash = md5(ts+privateKey+publicKey);\r\n\r\n  transaction.fullPath = transaction.fullPath + '?ts=' + ts + '\u2248ikey=' + publicKey + '&hash=' + hash ;\r\n});<\/pre>\n
Now whenever you push to the repository, Codeship will run the tests you\u2019ve defined. As I mentioned, the build will currently fail, as the expected response doesn\u2019t match the actual response. If you want to experiment and learn further, then you can try updating the API Blueprint file to match the new response structure. Or spend that time making Dredd work with your own API.<\/p>\n
<\/a><\/p>\n
Other options<\/h3>\n
If you want to use a SaaS to design\/host\/test your APIs, then a quick search will show that there are dozens of options. Here\u2019s a quick roundup of other open-source and free options; not all work that well within a CI context.<\/p>\n