Application Tester (app-tester)
- This page: http://github.com/joseairosa/app-tester
- Rubygems: http://rubygems.org/gems/app-tester
- Documentation: http://i.am.joseairosa.com/gems/app-tester/
Description
This Gem will provide a framework to build command line functional tests against a web application (API, Website, etc)
Features
- Easily create functional tests with just a few lines of code
- Since tests are built as command line tools they can be easily integrated with automatic tools
- Specify command line options in both short (-s, -f, etc...) and long (--server, --file, etc...) definition
- Add colors to make your tests more readable and easier to understand
- Use pre-built tools to analyse your output or build your own
Introduction
require "app-tester"
# Initialize framework with test environments
apptester = AppTester.new do |options|
options.add_environment :github => "https://github.com"
options.add_environment :google => "https://google.com"
options.default_environment = :google # A default environment can be specified
options.add_default_option(:something, '-a', '--something', 'this is an option')
end
# Define your tests
apptester.define_test "my test" do
# Perform a get request to "/"
result1 = get "/"
# Perform a post request to "/" with token as parameter
result2 = get "/", :token => "hello"
# Perform a post request to "/"
result3 = post "/"
# Perform a post request to "/" with token as parameter
result4 = post "/", :token => "hello"
# Check if we have a 200 OK or not
AppTester::Checker.status result1
# Convert a file to an array
p AppTester::Utils.file_to_array arguments[:file] unless arguments[:file].nil?
end
apptester.set_options_for "my test" do |options_parser|
options_parser.set_option(:file, "-f", "--file FILE", "File to load")
end
apptester.run_test "my test"
You can define multiple tests by adding more define_test blocks. In this case you might want to run them all, and for this use the following syntax:
apptester.run_all
You can set a default_option with hte AppTester initialization block, this option will be inherited by all the defined tests.
You can set mandatory arguments for your tests by passing true as the final argument to set_option :
apptester.set_options_for "my test" do |options_parser|
options_parser.set_option(:file, "-f", "--file FILE", "File to load", true)
end
Assuming that this is in a file called my_test.rb, you can run it, via command line:
$ ruby my_test.rb --help
Will output:
my test
-s, --server OPT Server to connect. Default: google
-f, --file FILE File to load
-h, --help Show this message
Or you can run the test itself:
$ ruby my_test.rb -s github
Will output:
Connecting to https://github.com...
[SUCCESS] got status 200
Requirements
- json >= 1.7.5
- faraday >= 0.8.4
- optparse
Install
It's very easy to install.
gem install app-tester
Done! :)
Dealing with expectations
One of the really nice features of this gem is that resembles a lot how RSpec works in terms of expectations.
So lets assume that you want to test some kind of expectation:
require "app-tester"
apptester = AppTester.new do |options|
options.add_environment :github => "https://github.com"
options.add_environment :google => "https://google.com"
options.default_environment = :google
end
apptester.define_test "my test to fail" do
var = true
var.should be_nil
end
apptester.run_test "my test to fail"
When you run this test you'll get the following output:
$ ruby examples/expectations.rb
Connecting to https://google.com...
[FAILED] expected: nil
got: true on line 12
Take a loot at RSpec::Matches for more information on which matchers you can use
Adding colours to your tests
AppTester has a useful helper class that enables anyone to add colours to the tests. Lets take the example where we want to output "Hello World" in 2 different colours.
require "app-tester"
# Initialize framework with test environments
apptester = AppTester.new do |options|
options.add_environment :github => "https://github.com"
options.default_environment = :github # A default environment can be specified
end
# Define your tests
apptester.define_test "my test"
result = get "/"
puts "#{AppTester::Utils::Colours.red("Hello")} #{AppTester::Utils::Colours.green("World")}"
end
apptester.run_test "my test"
Available colours are:
- black
- blue
- green
- cyan
- red
- purple
- brown
- light_gray
- dark_gray
- light_blue
- light_green
- light_cyan
- light_red
- light_purple
- yellow
- white
Benchmarking
You can benchmark your test. This is very useful to understand if anything is underperforming. Tests can be nested inside each other.
require "app-tester"
# Initialize framework with test environments
apptester = AppTester.new do |options|
options.add_environment :github => "https://github.com"
options.default_environment = :github # A default environment can be specified
end
# Define your tests
apptester.define_test "my test" do
result = get "/"
AppTester::Timer.new("test timer 1") do
sleep 1
end
AppTester::Timer.new("test timer 2") do
sleep 1
AppTester::Timer.new("test timer 2.1") do
sleep 1
end
end
end
apptester.run_test "my test"
This will output:
$ ruby examples/benchmark.rb
Connecting to https://github.com...
Time elapsed to test timer 1, 1001.086 milliseconds
Time elapsed to test timer 2.1, 1000.12 milliseconds
Time elapsed to test timer 2, 2001.204 milliseconds
Reading from a file
File are extremely usefull tools. We can have, for example, a functional test to an API where we want to run 100 strings against an end-point. For this you only need to create a new plain text file, write 1 string per line and use this gem to read them.
Here is an example:
require "app-tester"
apptester = AppTester.new do |options|
options.add_environment :github => "https://github.com"
options.add_environment :google => "https://google.com"
options.default_environment = :google
end
apptester.define_test "my test" do
result = get "/"
AppTester::Checker.status result
my_file = AppTester::Utils.file_to_array arguments[:file]
my_file.each do |line|
# do awesome stuff with line
end
end
apptester.set_options_for "my test" do |options_parser|
options_parser.set_option(:file, "-f", "--file FILE", "File to load")
end
apptester.run_test "my test"
Supported Ruby versions
This library aims to support and is tested against the following Ruby implementations:
If something doesn't work on one of these interpreters, it should be considered a bug.
LICENSE:
(The MIT License)
Copyright (c) 2012 José P. Airosa
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.