WIP: Dreddful Dredd Setup

5 minute read

April 14, 2018

My experience setting up Dredd wasn't all sunshine and rainbows (and that's something I would like to fix in the future). So here's what I did to get it 90% working for those curious kids out there.

Intro

What in the world is dredd? Here's what their docs say:

"Dredd is a language-agnostic command-line tool for validating API description document against backend implementation of the API.
Dredd reads your API description and step by step validates whether your API implementation replies with responses as they are described in the documentation."

View their docs

I wanted to add it to my current work project for awhile, but whenever I tried to get started I honestly got scared away by the implementation and the vastness of the docs. Finally I got to a point where I really had no other choice and hunkered down for a few days (yes days) and got it kinda working.

Installation

Adding Dredd Globally

If you have any issues with the steps below, check out the Dredd docs because they've got a lot more information that I didn't want to copy and paste here.

  1. Make sure node is installed by running node -v and npm -v
  2. Install Dredd npm install -g dredd
    • The -g ensures Dredd will be installed “globally”. Which means you’ll be able to access it from any directory just by typing dredd.
  3. Make sure Dredd is installed by running dredd -v

Configuring dredd.yaml

Now that Dredd is installed globablly on your machine, we can start configuring it for your project.

cd into your project directory and run dredd init. This starts a command wizzard for configuring your dredd.yml file.

  1. First it asks you for the location of the API description document. For me my blueprint.apib was in the root of my project, so I just typed blueprint.apib.
  2. Next it asks Command to start API backend server e.g. (bundle exec rails server). If you are using Laravel, you could add php artisan serve but I didn't for my config (half because I didn't know what I was doing and half because I figured valet would work)
  3. URL of tested API endpoint is next. For me it was http://fruitmart.valet/ so you can change that to your url.
    • Note: in my blueprint.apib all of my endpoints are prefixed with /api/ so I didn't need to add it here
  4. Next it asks for your language of choice, for me I chose php
  5. Then it asks about Apiary, when doing this myself I skipped it and then ended up going back and adding it to my dredd.yaml later.
  6. Finally Dredd is best served with Continuous Integration. appears, I said yes so I'd have the option to add it later.
$ dredd init
? Location of the API description document: blueprint.apib
? Command to start API backend server e.g. (bundle exec rails server)
? URL of tested API endpoint: http://fruitmart.valet
? Programming language of hooks:
  nodejs
  python
  ruby
❯ php
? Dredd is best served with Continuous Integration. Create CircleCI config for Dredd? Yes

Here's what my inital dredd.yaml looked like.

Installing dredd-hooks-php

Right now, you can run dredd, and I did and got a whole bunch of red goodness. This was because I hadn't set up any hooks for my application. What are hooks? We'll get to that in a second, but for now trust me and install dredd-hooks-php.

composer require ddelnano/dredd-hooks-php --dev

Congrats! You've got everything installed.

Okay what are hooks?

Here's what the docs say:

"Dredd’s hooks enable you to write some glue code in your favorite language to support enhanced scenarios in your API tests. Read the documentation about hooks to learn more on how to write them. Choose your language and install corresponding hook handler library."

This paragraph really didn't help me figure out what hooks were, and to be honest I don't know if I have a better definition. But I've started thinking of them as part of the arrange step of my tests, which I think does help me get in the right mental map.

Side note: If you don't have much experience with testing I highly reccomend Adam Wathan's Test-Driven Laravel course (his course got me from never writing tests, to not being able to live without them and I sleep much better because of it).

When writing hooks you've got a few options:

  • beforeEach, beforeEachValidation, afterEach
    • accepts a closure as a first argument passing a Transaction object as a first argument
  • before, beforeValidation, after
    • accepts transaction name as a first argument accepts a block as a second argument passing a Transaction object as a first argument of it
  • beforeAll, afterAll
    • accepts a block as a first argument passing an Array of Transaction objects as a first argument

What are transactions?

TBH: I'm still figuring that out. Right now I'm thinking of it as everything in dredd's request lifecycle.

While writing this post I did find the Transaction object documentation, which does help me get a sense of what's avaliable to play with.

Writing Hooks

api Laravel dredd

That's all for now folks, I'll add more soon!

Looking for more?

WIP: Laracon 2018

Laracon was this past week and it was amazing! Last night I tweeted this out:

I don't know where to begin, or how to fit everything I'm feeling into a tweet, but...

Jul 27, 2018

2 minute read

My Work Spotify Playlists

Here's a list of playlists I rotate through when I need get down to business.

  • Deep Work created by Chris Gmyr
  • Deep House Relax created by Spotify
  • mint...

May 14, 2018

1 minute read