cloudmonkey

CloudMonkey

Small infrastructure testing framework -- EXPERIMENTAL -- use at your own risk!

The idea is to fill the gap between unit testing of infrastructure scripts (Terraform, CloudFormation, etc.) on the one hand, and live integration testing of the real infrastructure on the other hand. CloudMonkey pulls meta information of cloud infrastructure elements and provides them through a unified abstract interface for testing. Write assertions using your preferred test runner and assertion library. Services and resource types are extendable and pluggable. This project is EXPERIMENTAL and at a very early stage.

Install

npm install cloudmonkey

Usage

A quick example (mocha/chai):

const { CloudMonkey, EC2 } = require('cloudmonkey');

const monkey = new CloudMonkey();
monkey.register(new EC2({ region: 'eu-central-1' }));

describe('my subnets', () => {
  it('should be tagged "zone c" if public', async () => {
    const igw = await monkey.select.one.ec2.internetGateway({ vpc: 'vpc-12345678' });
    const rtb = await igw.travel.to.all.routeTables();
    const sn = await rtb.travel.to.all.subnets();
    expect(sn).to.containAll(subnet =>
      subnet.Tags.filter(tag => tag.Key === 'security-zone' && tag.Value === 'c').length);
  });
});

Prerequisites

Setup access to your AWS account.

Features

Register services and resource types

The underlying model knows services and resource types. Services must be registered with CloudMonkey. Each service defines its resource types. Services are registered like this:

const { CloudMonkey, EC2 } = require('cloudmonkey');

const monkey = new CloudMonkey();
monkey.register(new EC2({ region: 'eu-central-1' }));
monkey.help();

Use help() to printout some information such as the registered services, their resource types, filter and travel options:

CloudMonkey 1.0.0-alpha.0

service "ec2"
* resource type "instance"
  filter by "id", "vpc"
* resource type "internetGateway"
  filter by "id", "vpc"
  travel to "routeTable"
* resource type "routeTable"
  filter by "id", "vpc"
  travel to "subnet"
* resource type "securityGroup"
  filter by "id", "name", "vpc"
* resource type "subnet"
  filter by "id", "vpc"

Selecting resources

The selection syntax provides a means to select resources. For example:

const monkey = new CloudMonkey();
...
const igw = await monkey.select.one.ec2.internetGateway({ vpc: 'vpc-12345678' });

The general form of select is:

select.<quantifier>.<service>.<resourceType>(<filter>)

Quantifier is one, some or all. one returns one single object while all and some always return an array. one will throw an error if there is none or multiple objects available. <service> must be one of the services registered. <resourceType> must be one of the resource types provided by the service (plural, i.e., adding an s for nicer reading, is working as well).

Both cases, an array representing multiple resources or a single object, can be used for further assertions. Use mocha or jasmine or chai or any assertion library.

Both cases are decorated. You can use dump() and travel to related resources within the same service.

const igw = await monkey.select.one.ec2.internetGateway({ vpc: 'vpc-12345678' });
igw.dump();
const rtb = await monkey.select.all.ec2.routeTables();
rtb.dump();

Travel to other resources

The travel syntax allows to travel from resources (of one resource type) to related resources (of another resource type within the same service). Use help() (see above) to learn which travel and filter options are available for a particular resource type.

const igw = await monkey.select.one.ec2.internetGateway();
const rtb = await igw.travel.to.all.routeTables();
const sn = await rtb.travel.to.all.subnets();
sn.dump();

The general form is:

data.travel.to.<quantifier>.<resourceType>(<filter>)