Package Exports

tfxjs
tfxjs/lib/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (tfxjs) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

tfxjs

tfxjs is a terrafrom acceptance test framework built with mocha and chai to allow users to quickly create acceptance tests for terraform templates.

Installation
Prerequisites
Usage
Example Usage
Methods
Contributing
Code Test Coverage

Installation

npm install tfxjs -g

Prerequisites

Create a .env file for your environment and set the API_KEY value
If mocha is not installed globally run:

npm install mocha -g

Usage

tfx <path to test file>

Example Usage

const tfxjs = require("tfxjs"); // Initialize tfxjs
const tfx = new tfxjs(" <path to template directory> ", "<name of terraform environment api key variable >"); // Create a new constructor for terraform teplate

tfx.plan("MyModule", () => { // Gerate a plan in the directory
  // Run tests for the module
  tfx.module("Root Module", "module.my_module", [
    // List of resources to test
    {
      name: "Activity Tracker Route", // Name of the resource (decorative)
      address: "ibm_atracker_route.atracker_route", // Expected address within module
      values: { // List of values to check in that resource
        name: "tfx-atracker-route",
        receive_global_events: true,
      },
    },
  ]);
});

Example Output

* tfxjs testing

##############################################################################
# 
#  Running `terraform plan`
#  Teplate File:
#     < your file path >
# 
##############################################################################



  MyModule

    ✔ Successfully generates a terraform plan file
    ✔ module.my_module should not contain additional resources

  Module Root Module
    ✔ Plan should contain the module module.my_module
    Activity Tracker Route
      ✔ Module module.my_module should contain resource ibm_atracker_route.atracker_route
      ✔ Activity Tracker Route should have the correct name value
      ✔ Activity Tracker Route should have the correct receive_global_events value


  5 passing (7s)

Methods

plan

  /**
   * Plan Terraform module from directory and return data using mocha
   * @param {string} moduleName Name of the module that is being tested
   * @param {Function} callback Callback function
   */
  tfx.plan(moduleName, callback)

tfx.plan runs a terraform plan command in the directory where tfx is initialized and adds the plan data to the tfx object. After the plan has been completed, the callback function will be executed.

module

  /**
   * Run tests for a module
   * @param {string} moduleName decorative string for module name
   * @param {string} moduleAddress relative module address from root
   * @param {Array<object>} resources Array of resources from the module to check
   */
  tfx.module(moduleName, moduleAddress, resources)

tfx.module runs a set of tests against a module inside the plan data. In order to call tfx.module, a tfx.plan command must be run first.

tfx.module checks for children relative to the parent.

Example

module.my_module has a sub module module.sub_module creating a composed module address of module.my_module.module.sub_module. tfx will dynamically add the parent module name to child modules. This allows sub modules to be accessed like this:

tfx.plan("MyModule", "module.my_module", () => {
  tfx.module("SubModudle", "module.sub_module", [
    ...resources
  ]})
})

Module Resource Test definitions

Resources for modules are described in an object with a name, address, and values.

{
  {
    name: "Activity Tracker Route",
    address: "ibm_atracker_route.atracker_route",
    values: {
      name: "ut-atracker-route",
      receive_global_events: true,
    }
  }
}

In addition to being any other data type, a function can also be passed in values.

function (value) {
  // your code here
  return {
    expectedData: // Must be `true` or `false` after evaluation
    appendMessage: // String message to append to the end of a test
  }
}

Example resource with a function:

{
  {
    name: "Activity Tracker Route",
    address: "ibm_atracker_route.atracker_route",
    values: {
      name: function(value) {
        return {
          expectedData: value.indexOf("_") === -1,
          appendMessage: "to not contain the underscore character."
        }
      },
      receive_global_events: true,
    }
  }
}

apply

  /**
   * Apply Terraform module from directory and return tfstate data using mocha
   * @param {string} moduleName Name of the module that is being tested
   * @param {Function} callback Callback function
   */
  tfx.plan(moduleName, callback)

tfx.apply runs a terraform apply command in the directory where tfx is initialized and adds the terraform.tfstate data to the tfx object. After the plan has been completed, the callback function will be executed.

state

  /**
   * Run tests for terraform state
   * @param {string} moduleName decorative string for module name
   * @param {string} moduleAddress relative module address from root
   * @param {Array<object>} resources Array of resources from the module to check
   */
  tfx.state(moduleName, moduleAddress, resources)

tfx.state runs a set of tests against a module inside the tf.state data. In order to call tfx.module, a tfx.apply command must be run first.

tfx.state runs commands only against specific resources. Ex:

tfx.apply("myModule", () => {
  tfx.state("myTests", [
    ...tests
  ])
})

State Resource Test definitions

[
  {
    name: // Decorative name of the resource
    address: // Address for resource
    instances: [
      {
        index_key: // Optional, use only if the index of the instance is a string, otherwise index will
        // be generated automatically
        ...attributes // Any attributes that will be tested for that instance
      }
    ]
  }
]

In addition to being any other data type, a function can also be passed in values.

function (value) {
  // your code here
  return {
    expectedData: // Must be `true` or `false` after evaluation
    appendMessage: // String message to append to the end of a test
  }
}

Contributing

If you have any questions or issues you can create a new [issue here][issues]. See the full contribution guidelines here.

Pull requests are very welcome! Make sure your patches are well tested. Ideally create a topic branch for every separate change you make. For example:

Fork the repo
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Added some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

Code Test Coverage

This module uses nyc for unit test coverage.

To get test coverage, run the command

npm run coverage

Current Test Coverage

File	% Stmts	% Branch	% Funcs	% Lines	Uncovered Line #s
All files	100	100	100	100	🏆
lib	100	100	100	100	🏆
helpers.js	100	100	100	100	🏆
index.js	100	100	100	100	🏆
utils.js	100	100	100	100	🏆
unit-tests	100	100	100	100	🏆
tfx.mocks.js	100	100	100	100	🏆

tfxjs

Package Exports

Readme

tfxjs

Table of Contents

Installation

Prerequisites

Usage

Example Usage

Example Output

Methods

plan

module

Example

Module Resource Test definitions

apply

state

State Resource Test definitions

Contributing

Code Test Coverage

Current Test Coverage