Writing Dredd hook handler for new language

Dredd hooks handler client

Dredd comes with concept of hooks language abstraction bridge via simple TCP socket.

When you run Dredd with --language argument, it runs the command in argument and tries to connect to http://localhost:61321. If connection to the hook handling server wasn't successful, it exits with exit code 3.

Dredd internally registers a function for each type of hooks and when this function is executed it assigns execution uuid to that event, serializes received function parameters (a Transaction object or an Array of it), sends it to the TCP socket to be handled (executed) in other language and waits until message with same uuid is received. After data reception it assigns received data back to the transaction, so other language can interact with transactions same way like native Node.js hooks.

Language agnostic test suite

Dredd hooks language abstraction bridge comes with the language agnostic test suite. It's written in Gherkin - language for writing Cucumber scenarios and Aruba CLI testing framework and it tests your new language handler integration with CLI Dredd and expected behavior from user's perspective.

What to implement

If you want to write a hook handler for your language you will have to implement:

  • CLI Command runnning TCP socket server
  • Must return message Starting to stdout

  • Hooks API in your language for registering code being executed during the Dredd lifecycle:

  • before all transactions
  • before each transaction
  • before transaction
  • before each transaction validation
  • before transaction validation
  • after transaction
  • after each transaction
  • after all transactions

  • When CLI command is executed

  • it loads files specified as CLI server arguments

    • it exposes API similar to those in Ruby, Python and Node.js to each loaded file
    • it registers functions declared in files for later execution
  • starts a TCP socket server and starts listening on http://localhost:61321.

  • When any data is received by the server

  • Adds every received character to a buffer

  • When delimiting newline ("\n") character is received

    • It parses the message in the buffer as JSON
    • It looks for event key in received object and executes appropriate registered hooks functions

    • When the hook function is being executed

    • It passes value of data key from received object to the executed function
    • Hook function is able to modify data

    • When function was executed

    • It should serialize message to JSON
    • Send the serialized message back to the socket with same uuid as received
    • Send a newline character as message delimiter

TCP Socket Message format

  • transaction (object)

    • uuid: 234567-asdfghjkl (string) Id used for event unique identification on both server and client sides

    • event: event (enum) Event type

    • beforeAll (string)
    • beforeEach (string)
    • before (string)
    • beforeEachValidation (string)
    • beforeValidation (string)
    • after (string)
    • afterEach (string)
    • afterAll (string)

    • data: (object, array) Data passed as a argument to the function

Configuration Options

There are several configuration options, which can help you during development:

Need help? No problem!

If you have any questions, please: