Introducing Silk: Markdown driven API tests

Mat Ryer
Mat Ryer
Feb 9, 2016 · 4 min read
Image for post
Image for post

The problem

I write a lot of code to test my API endpoints — especially because I am interested in the impact of everything that runs during the lifecycle of a request; how the route is interpreted, what middleware does to the request, how the business logic behaves, and what kind of response I get. Not to mention that sometimes I care about the impact of request headers, and the contents of response headers.

Documentation also quickly gets out of sync as the APIs evolve.

Meet Silk

Silk (silktest.org) lets you write your API documentation in Markdown, and then execute it as an automated test. If your API changes and your documentation is out-of-sync, the tests will fail.

Image for post
Image for post
Silk lets you write Markdown documentation for your APIs, and then execute as an automated test.

Tutorial

To explain how Silk works, we will write a simple markdown document describing a Hello World API, and then execute it with the `silk` tool.

# Hello API## `GET /hello`Gets a personalised greeting.* `?name=Mat` // The name of the person to greet===* Status: `404````
Hello there
```
Image for post
Image for post
Markdown renders nicely to look like real API documentation.
$ silk -silk.url=”http://outlearn-hello.appspot.com" hello-api.silk.md
running 1 file(s)
body expected:
```
Hello there
```
actual:
```
Hello Mat.
```
— — FAIL: GET /hello
hello-api.silk.md:14 — body doesn’t match
— — FAIL: silk (0.31s)
FAIL
# Hello API## `GET /hello`Gets a personalised greeting.* `?name=Mat` // The name of the person to greet===* Status: `404````
Hello Mat.
```
$ silk -silk.url=”http://outlearn-hello.appspot.com" hello-api.silk.mdrunning 1 file(s)
Status expected: 404 actual: 200
— — FAIL: GET /hello
hello-api.silk.md:11 — Status doesn’t match
— — FAIL: silk (1.24s)
FAIL
# Hello API## `GET /hello`Gets a personalised greeting.* `?name=Mat` // The name of the person to greet===* Status: `200`
* Content-Type: `text/html; charset=utf-8`
```
Hello Mat.
```
$ silk -silk.url=”http://outlearn-hello.appspot.com" hello-api.silk.mdrunning 1 file(s)PASS

Conclusion

Silk lets you write human readable documentation, and run it as part of your automated test suite.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store