bluecat

Bluecat

A REST API testing framework built on Node.js that makes testing API endpoints straightforward.

• Define your APIs in a json file, Bluecat will create all the methods for you
• Callbacks are removed so complex requests flow is more clear
• Full control over the request URL query, headers and body in test case
• Automatically maintains session cookies for you for HTTP API call flows
• Convenience methods that help to handle complex scenario

Table of contents

• Installation
• Example
• Usage
• Logging
• License

---

Installation

$ npm install bluecat

---

Example

Regular RESTful API

POST /checkout/contract
GET  /checkout/contract

• First define your API in config/api.json:

{
  "api": {
    "checkout": {
      "contract": {
        "schema": "http",
        "method": ["GET", "POST"]
      }
    }
  }
}

• Then create a Bluecat service object. You are all set to send request and validate response:

var expect = require('chai').expect;
var Bluecat = require('bluecat');
var Service = new Bluecat.ServiceSync(Bluecat.Api('api'), 'sample-host.com');

// All requests need to be put into Api.run(), so they will run synchronously
Service.run(function() {
    // send POST http://sample-host.com/checkout/contract
    // with body: {"cartid": "test-cart-id"}
    var r = Service.checkout.contract.POST({
      body: {
        cartid: 'test-cart-id'
      }
    });
    // verify response
    expect(r.data.statusCode).to.equal(200);
    expect(r.data.body).to.have.ownProperty('id');

    // send GET http://sample-host.com/checkout/contract
    // cookies are automatically maintained if there is any
    r = Service.checkout.contract.GET();
    // verify response
    expect(r.data.statusCode).to.equal(200);
    expect(r.data.body.cartId).to.eql('test-cart-id');
})

RESTful API with parameters in the URL

GET /checkout/${uuid}/contract

• First define your API in config/api.json:

{
  "api": {
    "checkout": {
      "${uuid}": {
        "contract": {
          "schema": "http",
          "method": ["GET"]
        }
      }
    }
  }
}

• Then create a Bluecat service object. You are all set to send request and validate response:

var expect = require('chai').expect;
var Bluecat = require('bluecat');
var Service = new Bluecat.ServiceSync(Bluecat.Api('api'), 'sample-host.com');

// All requests need to be put into Api.run(), so they will run synchronously
Service.run(function() {
    // send GET http://sample-host.com/checkout/5e586387-6d5a-4874-8a98-5836bdc45c7b/contract
    var r = Service.checkout['${uuid}'].contract.GET({
      params: {
        uuid: '5e586387-6d5a-4874-8a98-5836bdc45c7b'
      }
    });
    // verify response
    expect(r.data.statusCode).to.equal(200);
})

---

Usage

Bluecat.ServiceSync(api, host, options)

Create a new bluecat service object, with desired options.

var Bluecat = require('bluecat');
var Api = Bluecat.Api('mobileapi');
var Service = new Bluecat.ServiceSync(Api, 'api.mobile.walmart.com', {
  gzip: true
});

rawRequest(options)

Sometimes we just want to send a request to some host, which is different than the API host we are testing. You can use rawRequest(options) to fully to send it.

var Bluecat = require('bluecat');
var Api = Bluecat.Api('mobileapi');
var Service = new Bluecat.ServiceSync(Api, 'api.mobile.walmart.com');

var r = Service.rawRequest({
  method: 'GET',
  json: true,
  uri: 'https://thirdparty-host/creditcard/encryption.js',
  headers: {'accept-encoding': 'gzip'},
});
expect(r.err).to.equal(null);
expect(r.data.statusCode).to.equal(200);

setProxy(proxy)

Set proxy address, all the requests will be sent via a connection to the proxy server.

var Bluecat = require('bluecat');
var Api = Bluecat.Api('mobileapi');
var Service = new Bluecat.ServiceSync(Api, 'api.mobile.walmart.com');

Service.setProxy('http://127.0.0.1:8888')

resetCookie()

Clean up cookie jar, so the next request won't set any cookies in the header.

var Bluecat = require('bluecat');
var Api = Bluecat.Api('mobileapi');
var Service = new Bluecat.ServiceSync(Api, 'api.mobile.walmart.com');

Service.v1.products.search.GET();
Service.resetCookie();
Service.v1.cart.POST({
  body: {
    location: '94066'
  }
})

setHeaders(headers)

Set headers that will be sent in all the requests.

var Bluecat = require('bluecat');
var Api = Bluecat.Api('mobileapi');
var Service = new Bluecat.ServiceSync(Api, 'api.mobile.walmart.com');

Service.setHeaders({'User-Agent': 'Automation'});

setSessionRules(rules)

Set extra session rules other than cookie. Some RESTful APIs defines their own session rules, you can set it in the Bluecat framework so you don't have to deal with it in the actual test case.

var Bluecat = require('bluecat');
var Api = Bluecat.Api('mobileapi');
var Service = new Bluecat.ServiceSync(Api, 'api.mobile.walmart.com');

// The following sessions rules start with 'start-auth-token-value' in the request header AUTH_TOKEN,
// then grab new value from response header REFRESH_AUTH_TOKEN
// and put it in the next request header AUTH_TOKEN
Service.setSessionRules({
  requestHeader: 'AUTH_TOKEN',
  responseHeader: 'REFRESH_AUTH_TOKEN',
  startSessionHeader: 'start-auth-token-value'
});

---

Logging

• Launch the node process like BLUECAT_DEBUG_FILE=/path/to/bluecat.log node script.js to keep a log file of all the requests/responses information.

• Launch the node process like BLUECAT_DEBUG_CONSOLE=true node script.js to see all the requests/responses information from your console (stdout).

---

License

Licensed under the MIT