Project

awspec

0.62
A long-lived project that still receives updates
awspeck1low/awspecHomepageDocumentationSource CodeBug Tracker
RSpec tests for your AWS resources.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Popularity
Downloads
2,406,294
Stars
1,173
Forks
189
Watchers
32
 Releases
Current version
1.30.0
Total releases
251
First release
2015-07-28
Latest release
2024-04-16
 Issues
Open Issues
34
Closed Issues
103
Total Issues
137
Issue Closure Rate
75%
 Pull Requests
Open Pull Requests
6
Closed Pull Requests
27
Merged Pull Requests
417
Pull Request Acceptance Rate
92%
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2023-11-22
Reverse Dependencies
5

 Dependencies

Development

bundler
>= 1.9, < 3.0
octorelease
>= 0
pry
>= 0
rake
~> 12.0
rubocop
>= 0
parallel
>= 0

Runtime

addressable
>= 0
awsecrets
~> 1
aws-sdk
~> 3
dry-inflector
>= 0
ipaddress
>= 0
rspec
~> 3.0
rspec-its
>= 0
term-ansicolor
>= 0
thor
>= 0
 Project Readme

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.