node package manager
Painless code sharing. npm Orgs help your team discover, share, and reuse code. Create a free org »


Consumer Driven Contracts (CDC)

wercker status Coverage Status Code Climate Standard - JavaScript Style Guide Gitter

CDC provides a way to define mock provider for consumer and verify contracts against provider. It is written in JavaScript, however can be run in any setup using docker.

Getting started

Using docker-compose

version: '2'
      context: .
      - dependency
    command: npm start
    image: uldissturms/cdc
      - ./contracts/dependency:/usr/app/src/contracts
    command: mock
      - "3000:3000"

Where ./contracts/dependency contains index.js that describes contract.

└── dependency
    └── index.js

Using docker

docker run -p 3000:3000 -v ${PWD}/contracts:/usr/app/src/contracts uldissturms/cdc mock ./contracts/simple

Using npm

npm i cdc
./node_modules/.bin/cdc mock ./contracts/simple
./node_modules/.bin/cdc verify ./contracts/simple --baseUrl http://localhost:3000


Simple contract with schema validation

const joi = require('joi')
module.exports = {
  name: 'simple request/response schema',
  request: {
    path: '/api/simple-schema',
    method: 'POST',
    headers: {
      'content-type': 'application/json'
    body: {
      hello: 'world'
    bodySchema: joi.object().keys({
      hello: joi.string()
  response: {
    body: {
      id: 12345
    bodySchema: joi.object().keys({
      id: joi.number().integer()


curl localhost:3000/api/simple-schema -H 'content-type: application/json' -d '{"hello": "world"}'
{"id": 12345}


Why I wrote my own

request response
consumer verify schema mock
provider request verify schema
  • mock - mocks responses for consumer
  • verify - verifies contracts agains provider


  • mock
    • --port, -p - port for running mock server, defaults to 3000 (optional)
    • --no-cors, -C - disable CORS support (optional)
    • --watch, -w - to watch current directory for contract changes (optional)
    • --tls, -t - enable TLS with a self signed certificate ( setting NODE_TLS_REJECT_UNAUTHORIZED=0 when consuming from node might be required )
  • verify
    • --baseUrl, -b - base url to run verifications against (required)


For more examples take a look at contracts in ./contracts used for tests.

Libraries used

  • Joi (schema valiations)
  • Hapi (mock provider server)
  • Tape (verify consumer contracts against a provider)


Further reading