Home

Awesome

awspec Gem CI

Logo

RSpec tests for your AWS resources.

Resource Types | Contributing

Installation

Add this line to your application's Gemfile:

gem 'awspec'

And then execute:

$ bundle

Or install it yourself as:

$ gem install awspec

Getting Started

STEP 1. Generate awspec init files

If you're starting on a fresh RSpec project, you can use awspec to generate your init files:

$ awspec init

If you're working on an existing RSpec project, you will need to add the following lines to your spec_helper.rb file:

require 'awspec'
Awsecrets.load(secrets_path: File.expand_path('./secrets.yml', File.dirname(__FILE__)))

STEP 2. Set AWS config

2-1. Use Shared Credentials like AWS CLI

$ aws configure

...

(See http://docs.aws.amazon.com/ja_jp/cli/latest/userguide/cli-chap-getting-started.html#config-settings-and-precedence)

2-2. Use secrets.yml

$ cat <<EOF > spec/secrets.yml
region: ap-northeast-1
aws_access_key_id: XXXXXXXXXXXXXXXXXXXX
aws_secret_access_key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
EOF

STEP 3. Write spec/*_spec.rb

require 'spec_helper'

describe ec2('my-ec2-tag-name') do
  it { should be_running }
  its(:instance_id) { should eq 'i-ec12345a' }
  its(:image_id) { should eq 'ami-abc12def' }
  its(:public_ip_address) { should eq '123.0.456.789' }
  it { should have_security_group('my-security-group-name') }
  it { should belong_to_vpc('my-vpc') }
  it { should belong_to_subnet('subnet-1234a567') }
  it { should have_eip('123.0.456.789') }
  it { should be_disabled_api_termination }
end

Using shared_context: region

require 'spec_helper'

describe sqs('my-sqs-queue'), region: 'us-west-2' do
  it { should exist }
  its(:queue_url) { should eq 'https://sqs.us-west-2.amazonaws.com/xxxxxxxxxxxx/my-sqs-queue' }
  its(:queue_arn) { should eq 'arn:aws:sqs:us-west-2:xxxxxxxxxxxx:my-sqs-queue' }
  its(:visibility_timeout) { should eq '30' }
  its(:maximum_message_size) { should eq '256000' }
  its(:message_retention_period) { should eq '86400' }
  its(:delay_seconds) { should eq '0' }
  its(:receive_message_wait_time_seconds) { should eq '10' }
end

Using terraform outputs as identifier

Especially in cases, where resources created by terraform have the same names (e.g. created by VPC module), it is helpful to use terraform outputs as unique identifiers.

output "my_ec2_instance" {
    value = aws_instance.my_instance.id
}

require 'spec_helper'

my_ec2_instance = `terraform output my_ec2_instance`.strip

describe ec2(my_ec2_instance) do
  it { should be_running }
  its(:image_id) { should eq 'ami-abc12def' }
  its(:public_ip_address) { should eq '123.0.456.789' }
  it { should have_security_group('my-security-group-name') }
  it { should belong_to_vpc('my-vpc') }
  it { should belong_to_subnet('subnet-1234a567') }
  it { should have_eip('123.0.456.789') }
  it { should be_disabled_api_termination }
end

STEP 4. Run tests

Add gem "rake" in your Gemfile if you are starting a blank project.

$ bundle exec rake spec

Advanced Tips: Spec generate command

Generate spec from AWS resources already exists.

$ awspec generate ec2 vpc-ab123cde >> spec/ec2_spec.rb

Make sure you have added in your spec file

require 'spec_helper'

Advanced Tips: Use Shared Credentials (~/.aws/config ~/.aws/credentials)

$ awspec generate ec2 vpc-ab123cde --profile mycreds

$ AWS_PROFILE=mycreds bundle exec rake spec

Advanced Tips: Configuring the AWS client retries

The ClientWrap class provides mechanisms for retrying AWS API calls when it receives a RequestLimitExceeded error. ClientWrap implements a backoff algorithm where the client will sleep for successively longer periods of time until the algorithm has calculated a backoff greater than or equal to the backoff_limit, at which point it will give up and re-raise the error. You can see the full implementation in ClientWrap#method_missing.

You can configure this retry and backoff logic in your spec_helper.rb:

require 'awspec'

# These are the defaults, but you can change them.
Awspec.configure do |config|
  config.client_backoff 0.0
  config.client_backoff_limit 30
  config.client_iteration 1
end

Advanced Tips: Setting A Custom Endpoint

Set the endpoint environment variable to tell awspec to use a different endpoint to connect to aws. Common use cases are connecting to aws through a proxy, using a different service with an aws compatible interface, or connecting to a local mock aws environment.

For example, first create a resource on a local aws service using the aws cli:

AWS_SECRET_ACCESS_KEY=dummy AWS_ACCESS_KEY_ID=dummy \
    aws --endpoint-url http://localhost:5000 s3 mb s3://my-bucket

Then you can tell awspec to run the test suite using the same custom endpoint:

endpoint=http://localhost:5000 bundle exec rake spec

Support AWS Resources

Resource Types information here

awspec AWS key/secrets precedence

Dependent on awsecrets.

References

awspec is inspired by Serverspec.