vault-test-tools 0.3.4 → 0.3.5

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 2.0.0
+  - 1.9.3
+  - jruby-19mode # JRuby in 1.9 mode
+  - rbx-2.1.1

data/Gemfile

@@ -1,9 +1,13 @@
 source 'https://rubygems.org'
-ruby '1.9.3'
-
-# Specify your gem's dependencies in vault-dev-tools.gemspec
+# Specify your gem's dependencies in vault-test-tools.gemspec
 gemspec
 
+group :development do
+  gem 'rake'
+  gem 'yard'
+end
+
 group :test do
   gem 'fakeweb'
+  gem 'scrolls', '~> 0.2.6'
 end

data/README.md

@@ -3,25 +3,65 @@
 Test is the English phrase for テスト.  Test tools for the Heroku
 Vault Team.
 
-## Installation
+## Overview
 
-Add this line to your application's Gemfile:
+### Installation
+
+Add this line to your application's `Gemfile`:
 
     group :test do
       gem 'vault-test-tools'
     end
 
-## Usage
+### Usage
+
+#### Rakefile
+
+```ruby
+desc 'Run the test suite'
+require 'vault-test-tools/rake_task'
+```
+
+##### note: we plan on renaming this to `test_task`
+
+### bin files
+
+#### Run the tests with `t`
+
+    > t
+
+Runs `bundle exec rake test`
+
+#### Profile the tests with `pt`
+
+    > pt
+
+#### Build the docs with `d`
+
+    > d
+
+Runs `bundle exec yardoc`
 
 ### test/helper.rb
 
+If you're using `vault-tools` and calling `Vault.setup` in
+`my-lib-that-calls-vault-setup.rb` then it will automatically be
+required when `RACK_ENV` is `test`.
+
+```ruby
+ENV['RACK_ENV'] = 'test'
+require 'my-lib-that-calls-vault-setup'
+```
+
+Otherwise just require it:
+
 ```ruby
 require 'vault-test-tools'
 ```
 
-### Test Base Classes
+#### Test Base Classes
 
-Sublcass and go:
+Subclass and go:
 
 ```ruby
 class MyTest < Vault::TestCase
@@ -31,9 +71,18 @@ class MyTest < Vault::TestCase
 end
 ```
 
-### Spec Base Class
+#### Spec Base Class
 
-Automatically installed as default.  Just:
+##### in spec/helper.rb
+
+We removed this from the gem so you have do to it in your helper file.
+
+```ruby
+# Register our Spec class as the default.
+MiniTest::Spec.register_spec_type //, Vault::Spec
+```
+
+##### go write some specs
 
 ```ruby
 describe 'Anything' do
@@ -43,30 +92,130 @@ describe 'Anything' do
 end
 ```
 
-### Uniform Module Sharing
+#### Test Helpers
+
+You just include the helper you need into the test file you're writing.
+This makes tests very self-contained and also provides a way to document
+what you're pulling into the test.
+
+If you really want to share something to all the tests then include
+them into `Vault::TestCase`.
+
+##### in `test/helper.rb`
+
+```ruby
+class Vault::TestCase
+  include Vault::Test::EnvironmentHelpers
+end
+```
+
+##### `Vault::Test::EnvironmentHelpers`
+
+Provides a `#set_env` method that temporarily overrides an environment
+variable.
+
+```ruby
+class MyTest < Vault::TestCase
+  include Vault::Test::EnvironmentHelpers
+
+  def test_env_changes
+    assert_equal('var', ENV['FOO'])
+    set_env 'FOO', '42'
+    assert_equal('42', ENV['FOO'])
+  end
+end
+```
+
+##### `Vault::Test::HTMLHelpers`
+
+Provides `#assert_css` and `#save_and_open_page` to make assertions
+against the `last_response.body` simple.
+
+```ruby
+class Test < Vault::TestCase
+  include Vault::Test::HTMLHelpers
+
+  def test_env_changes
+    get '/my-awesome-page'
+    save_and_open_page
+    assert_css('#selector', 'text')
+  end
+end
+```
+
+##### `Vault::Test::SpecHelpers`
+
+Provides `#usage_json`, `#statement_json` and `#vault_spec` methods to
+pull down and vendor latest specs from the `vault-specs` app.  The
+json files are stored in `test/support/<filename>.json` and are used
+only when the live HTTP request against the vault-specs app fails.
 
-To extend your test and spec base classes uniformly, use the method
-`Vault::Test.include_in_all`
+Yes, this means your tests are making an HTTP request.  This enables
+us to update specs and then run tests that immediately use the specs
+on the server.  However, if you're on a plane or don't have internet
+we can easily fall back to the saved JSON.
 
 ```ruby
-module MyTestHelperClass
-  def app; Vault::InvoiceBuilder::Web; end
+class Test < Vault::TestCase
+  include Vault::Test::SpecHelpers
+
+  def test_env_changes
+    put '/statement/1', statement_json
+    put '/statement/1', vault_spec('statement2.json')
+    assert_equal(statement_json, vault_spec('statement.json'))
+    assert_equal(usage_json,     vault_spec('usage.json'))
+  end
 end
+```
+
+##### `Vault::Test::LoggingHepers`
 
-Vault::Test.include_in_all Vault::MyTestHelperClass
+Attaches a `StringIO` to `Scrolls.stream` to capture logs in memory.
+
+```ruby
+class Test < Vault::TestCase
+  include Vault::Test::LoggingHelpers
+
+  def test_logging
+    Scrolls.log(message: 'A log message')
+    assert_equal(Scrolls.stream.string, 'A log message\n')
+  end
+end
 ```
 
-Now you have an `#app` method in your `Vault::TestCase` and your `Vault::Spec`
+## Setting up a development environment
+
+Install dependencies and setup test databases:
 
-## Contributing
+    bundle install --binstubs vendor/bin
+    rbenv rehash
+    rake
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+Run tests:
 
-## Releasing
+    bundle exec rake test
+
+See tasks:
+
+    rake -T
+
+Generate API documentation:
+
+    bundle exec yard
+
+## Creating and shipping a change
+
+Create a change by making a branch with the changes you want to merge.
+Open a pull request and signal it to the Vault Team by creating a
+Trello card in the *Needs review* list on the
+[focus board](https://trello.com/b/mV7Qy3aq/vault-team-focus).
 
 Update the version in `lib/vault-test-tools/version` and run
 `bundle exec rake release`.
+
+## Where to get help
+
+Ask for help in the
+[Vault](https://heroku.hipchat.com/rooms/show/175790/vault) room in
+HipChat or send the Vault Team an
+[email](https://groups.google.com/a/heroku.com/forum/#!forum/vault).

data/Rakefile

@@ -1,2 +1,8 @@
 require "bundler/gem_tasks"
 require 'vault-test-tools/rake_task'
+require 'yard'
+
+desc "Doc the things"
+YARD::Rake::YardocTask.new
+
+task default: :test

data/lib/vault-test-tools.rb

@@ -1,11 +1,20 @@
+module Vault
+  # `Vault::Test` provides support for writing automated tests.
+  module Test
+  end
+end
+
 require "vault-test-tools/version"
 
 require 'rack/test'
-require 'nokogiri'
+# require 'nokogiri'
 
-require "vault-test-tools/test_case"
-require "vault-test-tools/spec"
+# Test case mixins.
 require "vault-test-tools/environment_helpers"
 require "vault-test-tools/html_helpers"
-require "vault-test-tools/db_helpers"
+require "vault-test-tools/logging_helpers"
 require "vault-test-tools/spec_helpers"
+
+# Test case base classes.
+require "vault-test-tools/test_case"
+require "vault-test-tools/spec"

data/lib/vault-test-tools/environment_helpers.rb

@@ -1,11 +1,11 @@
 module Vault::Test::EnvironmentHelpers
-  # Override an ENV variable for the current test.  The original value will be
-  # restored automatically when the test finishes.
+  # Override an environment variable in the current test.
   def set_env(key, value)
     overrides[key] = ENV[key] unless overrides.has_key?(key)
     ENV[key] = value
   end
 
+  # Restore the environment back to its state before tests ran.
   def teardown
     overrides.each { |key, value| ENV[key] = value }
     super

data/lib/vault-test-tools/html_helpers.rb

@@ -1,4 +1,8 @@
 module Vault::Test::HTMLHelpers
+  # Save and open an HTML document in your browser.
+  #
+  # @param html [String] The page to open or nil to fetch it from
+  #   `last_response.body` if testing a Sinatra app.
   def save_and_open_page(html = nil, name = 'page.html', i = 1)
     html ||= last_response.body
     name = "page_#{i=i+1}.html" while File.exist? name
@@ -6,26 +10,49 @@ module Vault::Test::HTMLHelpers
     system "open #{name}"
   end
 
+  # Parse an HTML document into a `Nokogiri::HTML` instance and store it as
+  # the current document.
   def set_doc(body)
     @doc = Nokogiri::HTML(body)
   end
 
+  # Get the current document or parse `last_response.body` into a
+  # `Nokogiri::HTML` instance.
+  #
+  # @return [Nokogiri::HTML] The current HTML document.
   def doc
     @doc || Nokogiri::HTML(last_response.body)
   end
 
-  def css(string)
-    doc.css(string)
+  # Get a list of text matches in the current document for a CSS selector.
+  #
+  # @param selector [String] A CSS selector to match elements in the document
+  #   with.
+  # @return [Array] A list of matching elements from the current document.
+  def css(selector)
+    doc.css(selector)
   end
 
-  def assert_includes_css(css_string)
-    exists = doc.css(css_string).first
-    assert exists, "Last response must include #{css_string}"
+  # Assert that at least one element in the current document matches the CSS
+  # selector.
+  #
+  # @param selector [String] A CSS selector to match elements in the document
+  #   with.
+  def assert_includes_css(selector)
+    exists = doc.css(selector).first
+    assert exists, "Last response must include #{selector}"
   end
 
-  def assert_css(css_string, content)
-    e = css(css_string).first
-    assert e, "Element not found: #{css_string}"
+  # Assert that the content in the first element matching the CSS selector
+  # matches the specified value.
+  #
+  # @param selector [String] A CSS selector to match elements in the document
+  #   with.
+  # @param content [String] The content to match in the first matching
+  #   element.
+  def assert_css(selector, content)
+    e = css(selector).first
+    assert e, "Element not found: #{selector}"
     assert_includes e.content, content
   end
 end

data/lib/vault-test-tools/logging_helpers.rb

@@ -0,0 +1,8 @@
+require 'scrolls'
+
+module Vault::Test::LoggingHelpers
+  def setup
+    super
+    Scrolls.stream = StringIO.new if defined? Scrolls
+  end
+end

data/lib/vault-test-tools/rake_task.rb

@@ -1,10 +1,8 @@
 require 'rake/testtask'
 
-ENV['CPUPROFILE'] = './test/.test.profile'
 Rake::TestTask.new do |t|
   t.verbose = true
   t.ruby_opts << '-r turn/autorun'
-  t.ruby_opts << '-r perftools'
   t.ruby_opts << '-I test'
   t.test_files = FileList['test/**/*_test.rb', 'test/**/*_spec.rb']
 end

data/lib/vault-test-tools/spec_helpers.rb

@@ -13,7 +13,8 @@ module Vault::Test
       vault_spec('statement.json')
     end
 
-    # memoizes return value so we don't keep making a request
+    # Memoizes return value so we don't keep making a request to download the
+    # spec.
     def vault_spec(filename)
       return cache[filename] if cache[filename]
       cache[filename] = read_spec(filename)
@@ -24,6 +25,7 @@ module Vault::Test
     end
 
     protected
+
     def cache
       @@cache ||= {}
     end
@@ -36,8 +38,8 @@ module Vault::Test
       "./test/support/#{name}"
     end
 
-    # Uses JSON at URL when it can, but will use
-    # the cached statement when it can't
+    # Uses JSON at URL when it can, but will use the cached statement when it
+    # can't.
     def read_spec(name)
       data = ::Net::HTTP.get(URI.parse(url(name)))
       FileUtils.mkdir_p(File.dirname(file(name)))

data/lib/vault-test-tools/test_case.rb

@@ -2,8 +2,5 @@ require 'minitest/unit'
 
 # Base class for Vault test cases.
 class Vault::TestCase < MiniTest::Unit::TestCase
-  def setup
-    super
-    Scrolls.stream = StringIO.new if defined? Scrolls
-  end
+  include Vault::Test::LoggingHelpers
 end

data/lib/vault-test-tools/version.rb

@@ -1,5 +1,5 @@
 module Vault
   module Test
-    VERSION = "0.3.4"
+    VERSION = '0.3.5'
   end
 end

data/test/logging_helpers_test.rb

@@ -0,0 +1,12 @@
+require 'helper'
+
+class LoggingHelpersTest < Vault::TestCase
+  include Vault::Test::LoggingHelpers
+
+  # The LoggingHelpers mixin attaches a StringIO to Scrolls to capture log
+  # messages.
+  def test_scrolls_logs_to_stream
+    Scrolls.log(key: 'value')
+    assert_equal("key=value", Scrolls.stream.string.strip)
+  end
+end

data/vault-test-tools.gemspec

@@ -13,17 +13,13 @@ Gem::Specification.new do |gem|
   gem.homepage      = ""
 
   gem.files         = `git ls-files`.split($/)
-  gem.executables   = ['t','d','pt']
+  gem.executables   = ['t']
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
 
   gem.add_dependency 'minitest', '4.7.4'
   gem.add_dependency 'turn'
-  gem.add_dependency 'rack-perftools_profiler'
   gem.add_dependency 'nokogiri'
   gem.add_dependency 'rack-test'
-  gem.add_dependency 'rdoc'
-  gem.add_dependency 'yard'
-  gem.add_dependency 'redcarpet'
   gem.add_dependency 'rr'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vault-test-tools
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.3.5
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-17 00:00:00.000000000 Z
+date: 2013-12-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -44,22 +44,6 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: rack-perftools_profiler
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: nokogiri
   requirement: !ruby/object:Gem::Requirement
@@ -92,54 +76,6 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: rdoc
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: yard
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: redcarpet
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: rr
   requirement: !ruby/object:Gem::Requirement
@@ -163,24 +99,22 @@ email:
 - jkakar@heroku.com
 executables:
 - t
-- d
-- pt
 extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
 - .ruby-version
+- .travis.yml
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
-- bin/d
 - bin/pt
 - bin/t
 - lib/vault-test-tools.rb
-- lib/vault-test-tools/db_helpers.rb
 - lib/vault-test-tools/environment_helpers.rb
 - lib/vault-test-tools/html_helpers.rb
+- lib/vault-test-tools/logging_helpers.rb
 - lib/vault-test-tools/rake_task.rb
 - lib/vault-test-tools/spec.rb
 - lib/vault-test-tools/spec_helpers.rb
@@ -188,6 +122,7 @@ files:
 - lib/vault-test-tools/version.rb
 - test/environment_helpers_test.rb
 - test/helper.rb
+- test/logging_helpers_test.rb
 - test/spec_helpers_test.rb
 - test/test_spec.rb
 - vault-test-tools.gemspec
@@ -205,7 +140,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -4588855188946910642
+      hash: 556099526944459047
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -214,7 +149,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -4588855188946910642
+      hash: 556099526944459047
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23
@@ -224,6 +159,7 @@ summary: Test classes and stuff you want in your dev, but not prod, environment.
 test_files:
 - test/environment_helpers_test.rb
 - test/helper.rb
+- test/logging_helpers_test.rb
 - test/spec_helpers_test.rb
 - test/test_spec.rb
 has_rdoc: 

data/bin/d

@@ -1,3 +0,0 @@
-#! /usr/bin/env ruby
-
-system(%|bundle exec yardoc|)

data/lib/vault-test-tools/db_helpers.rb

@@ -1,16 +0,0 @@
-module Vault::Test
-  module DB
-    module Truncation
-      def teardown
-        super
-        truncate_tables!
-      end
-
-      def truncate_tables!
-        (db.tables - [:schema_migrations]).each do |table|
-          db << "truncate #{table}"
-        end
-      end
-    end
-  end
-end