bauxite 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: be9bad759531fd16a4b26cdf4e238cce2f281dca
-  data.tar.gz: bbc8da45da489a6ec0f2953d7fe1060b8c2f16c2
+  metadata.gz: 063894fc2a6cee418888abc8d731448a22653c5c
+  data.tar.gz: 1cc13f20d0951eaed6451b75575124f558f4d063
 SHA512:
-  metadata.gz: 3a0e659899dd36b90f10427bac985977121bf8b7f6f1dcbee88d7b1362e293b32f90a66e89be9758bd77254439f2c81832e6aff29c520adbc53dcf7a48bd7aff
-  data.tar.gz: 702df87e3d3675511d09c8f8337334bce794cf31cbf1d16d274d494a51fa461406316ad94d24fb8b1bf2100f7dd74a48b96c6cc0cbf6a5f8c29848651727e429
+  metadata.gz: c4e04c8976ba0a5a5b018dc62fac88d1204c7415114159527e3b03581e94a7119dd70f51dec32c6e3b255a8b690a2729f2ae7815810254ef0d3e1094a9b3c7d8
+  data.tar.gz: 37f4ec249b6139fd33b968d387eb5f043b5b0ccae3bbffefd47c710bb753b19784c1247e53e62b81f6b91120b4553bb494964e65d50adc6cd348f0029bcc30b0

data/README.md

@@ -0,0 +1,239 @@
+bauxite
+=======
+
+Bauxite is a façade over Selenium intended for non-developers
+
+The idea behind this project was to create a tool that allows non-developers to write web tests in a human-readable language. Another major requirement is to be able to easily extend the test language to create functional abstractions over technical details.
+
+Take a look at the following Ruby excerpt from http://code.google.com/p/selenium/wiki/RubyBindings:
+```ruby
+require "selenium-webdriver"
+
+driver = Selenium::WebDriver.for :firefox
+driver.navigate.to "http://google.com"
+
+element = driver.find_element(:name, 'q')
+element.send_keys "Hello WebDriver!"
+element.submit
+
+puts driver.title
+
+driver.quit
+```
+While developers might find that code expressive enough, non-developers might be a bit shocked.
+
+The equivalent Bauxite test is easier on the eyes:
+```
+open "http://google.com"
+write name=q "Hello WebDriver!"
+click gbqfb
+```
+Installation
+------------
+
+In a nutshell:
+```
+gem install bauxite
+```
+
+Remember you'll also need Ruby 2.x installed and Firefox (you can use other browsers or Selenium server by specifying the `-p` switch to the `bauxite` executable).
+
+Hello World
+-----------
+
+(This section assumes that Bauxite and its dependencies are installed in the system. Refer to the [Installation](#installation) section below for more details).
+
+Paste the following text into `hello.bxt`:
+```
+open "http://www.gnu.org/fun/jokes/helloworld.html"
+```
+
+Launch a console and type:
+```
+bauxite hello.bxt
+```
+
+Documentation
+-------------
+
+The Bauxite language is composed of two elements `Actions` and `Selectors`: Actions are testing operations such as "open this page", "click this button", "write this text into that textbox", etc. Selectors are ways of locating interesting elements of a page such as a button, a textbox, a label, etc.
+
+A typical Bauxite test is a plain text file that contains a series of Actions (one per line). Depending on the Action, a few action arguments might need to be specified as well. For example in:
+```
+open "http://google.com"
+write name=q "Hello WebDriver!"
+click gbqfb
+```
+
+`open`, `write` and `click` are Actions:
+- `open` takes a single URL argument (`"http://google.com"`) and opens that URL in the browser.
+- `write` takes two arguments, a Selector (`name=q`, more on this in a bit) and a text (`"Hello WebDriver!"`), and writes the text into the element specified by the Selector.
+- `click` takes a single Selector argument (`gbqfb`) and clicks the element specified by the Selector.
+
+In general, Action arguments can be surrounded by optional double quote characters (`"`). If an argument contains a space character, the quotes are mandatory (this is the case for the second argument to `write` in the example above).
+
+Some Actions operate on page elements (e.g. `write`, `click`, etc.). In order to locate these elements, Bauxite uses Selectors.
+
+The trivial Selector is just a text that matches the last portion of the `id` attribute of the target element. 
+
+For example, in this HTML fragment:
+```html
+<input type="submit" id="gbqfb" value="Search" />
+```
+
+If we want to click the "Search" button we can do the following:
+```
+click gbqfb
+```
+
+Bauxite supports several other Selectors such as `name=` in the example above. The `name` Selector finds elements whose `name` attribute matches the text following the `=` sign.
+
+For example, in this HTML fragment:
+```html
+<input type="text" name="q" />
+```
+
+If we want to type the text "Hello WebDriver!" in textbox we can do the following:
+```
+write name=q "Hello WebDriver!"
+```
+
+This section presented a  brief introduction into the basic Bauxite concepts. For more details and a list of every Action and Selector available, refer to the RDoc generated documentation in:
+- [Available Actions](http://pzavolinsky.github.io/bauxite/Bauxite/Action.html#Action+Methods)
+- [Available Bauxite Selectors](http://pzavolinsky.github.io/bauxite/Bauxite/Selector.html#Selector+Methods)
+- [Selenium Standard Selectors](http://pzavolinsky.github.io/bauxite/Bauxite/Selector.html#class-Bauxite::Selector-label-Standard+Selenium+Selectors)
+- [Creating new Actions](http://pzavolinsky.github.io/bauxite/Bauxite/Action.html)
+- [Creating new Selectors](http://pzavolinsky.github.io/bauxite/Bauxite/Selector.html)
+
+Installing Ruby
+---------------
+
+I won't cover all the details of installing Ruby on your system (Google knows best), but the following should probably work.
+
+In GNU/Linux, you can install [RVM](http://rvm.io/), then Ruby:
+```
+curl -sSL https://get.rvm.io | bash -s stable
+source ~/.rvm/scripts/rvm
+rvm install ruby-2.1.0
+```
+
+In Windows, you can install Ruby 2.x with [RubyInstaller](http://rubyinstaller.org/downloads/) but you'll probably need to install a Ruby 2.x Development Kit. After everything is installed, launch the Ruby terminal (or the MSYS terminal from the DevKit).
+
+Regadless of your OS, you should be able to install Bauxite with:
+
+```
+gem install bauxite
+```
+
+Additionally, if you are using GNU/Linux, you might want to install `ruby-terminfo` to improve the terminal output(i.e. handle more than 80 chars):
+
+```
+gem install ruby-terminfo
+```
+
+Implementation
+--------------
+
+Bauxite is both a console program and a library. You can use the program to run Bauxite tests directly from a terminal, or you can embed the library in your own application.
+
+The console program is called `bauxite` and has a few command-line options (run `bauxite -h` to see them all).
+
+If you are looking to embed Bauxite in your application take a look a the code in `lib/bauxite/application.rb`, that should give you a full example of how to create a Bauxite Context and execute some actions.
+
+Extending Bauxite
+-----------------
+
+Bauxite supports two types of extensions: functional extensions and coded plugins.
+
+### Functional extensions
+
+Functional extensions are composite constructs created using existing Bauxite actions to convey functional meaning. For example, imagine a login form:
+
+```html
+<!-- http://hostname/login.html -->
+<form>
+  <input id="username" name="username" type="text"     />
+  <input id="password" name="password" type="password" />
+  <input id="login" type="submit" value="Login"/>
+</form>
+```
+
+The Bauxite code to login into this site would be:
+```
+open "http://hostname/login.html"
+write username "jdoe"
+write password "hello world!"
+click login
+```
+
+If we were creating a suite of automated web tests for our *hostname* site, we'll probably need to login into the site several times. This would mean copy/pasting the four lines above into every test in our suite. 
+
+Of course we can do better. We can split Bauxite tests into many files and include one test into another with the `load` action.
+
+```
+# my_test.bxt (by the way, this is a comment)
+load other_test_fragment.bxt
+...
+```
+
+Back to our login example, first we can package the login part of our tests into a separate Bauxite file:
+```
+# login.bxt
+open "http://hostname/login.html"
+write username "jdoe"
+write password "hello world!"
+click login
+```
+
+Of course we would like to be able to login with different username/password combinations, so we can replace the literals in `login.bxt` with variables:
+```
+# login.bxt
+open "http://hostname/login.html"
+write username "${username}"
+write password "${password}"
+click login
+```
+
+Now, we would like to assert that both `username` and `password` variables are set before calling our test (just in case someone forgets). We can do this with `params`
+```
+# login.bxt
+params username password
+open "http://hostname/login.html"
+write username "${username}"
+write password "${password}"
+click login
+```
+
+In our main test we can load `login.bxt` and specify the variables required using this code:
+```
+# main_test.bxt
+load login.bxt username=jdoe "password=hello world!"
+
+# additional actions go here
+```
+
+We could improve this even further by creating an `alias` to simplify the login process. To do this, lets create an new file called `alias.bxt`:
+```
+# alias.bxt
+alias login load login.bxt "username=${1}" "password=${2}"
+```
+
+Note that the `alias` action supports positional arguments.
+
+Now we can change our main test to use our alias:
+```
+# main_test.bxt
+load alias.bxt
+
+login jdoe "hello world!"
+
+# additional actions go here
+```
+
+That was a bit of work but the resulting test is purely functional (minus the load alias part, of course).
+
+### Coded plugins
+
+Coded plugins can be used to extend Bauxite actions, selectors and loggers. Coded plugins are Ruby files placed in the respective directory. See any of the current artifacts for a reference implementation.
+
+

data/Rakefile

@@ -4,27 +4,26 @@ task :default => [:test, :doc]
 require 'rubygems'
 require 'rubygems/package_task'
 
-PKG_FILES = FileList[
-  'LICENSE',
-  'Rakefile',
-  'bin/*',
-  'lib/**/*.rb',
-  'test/**/*',
-  'doc/**/*'
-]
-
 spec = Gem::Specification.new do |s|
 	s.name        = 'bauxite'
-	s.summary     = 'Bauxite is a facade over Selenium intended for non-developers'
+	s.summary     = 'Bauxite is a façade over Selenium intended for non-developers'
 	s.author      = 'Patricio Zavolinsky'
 	s.email       = 'pzavolinsky at yahoo dot com dot ar'
 	s.homepage    = 'http://rubygems.org/gems/bauxite'
 	s.license     = 'MIT'
 	s.version     = `ruby -Ilib bin/bauxite --version`.gsub(/^.* /, '')
-	s.files       = PKG_FILES
 	s.executables = ["bauxite"]
 	s.add_runtime_dependency     'selenium-webdriver', '~> 2.39'
 	s.add_development_dependency 'rake'              , '~> 10.1'
+	s.files = FileList[
+		'LICENSE',
+		'README.md',
+		'Rakefile',
+		'bin/*',
+		'lib/**/*.rb',
+		'test/**/*',
+		'doc/**/*'
+	]
 end
 
 Gem::PackageTask.new(spec) do |pkg|
@@ -40,6 +39,11 @@ desc "Run integration tests"
 task :test do
 	test_files = Dir[File.join('test', '*.bxt')].select { |f| not File.directory? f }.join(' ')
 	ruby "-Ilib bin/bauxite -v #{test_files}"
+	
+	ruby "-Ilib bin/bauxite -v -e #{File.join('test', 'extension')} #{File.join('test', 'extension.bxt.manual')}"
+	
+	system("ruby -Ilib bin/bauxite #{File.join('test', 'test.bxt.manual')}")
+	fail "The 'test' action test failed to return the expected exit status: the exit status was #{$?.exitstatus}" unless $?.exitstatus == 2
 end
 
 # === Documentation ========================================================= #
@@ -66,4 +70,22 @@ task :inject_license do
 		content = license + File.open(f, 'r') { |f| f.read }
 		#File.open(f, 'w') { |f| f.write content }
 	end
+end
+
+desc "Helper: Update Bauxite version"
+task :update_version do
+	content = File.open('lib/bauxite.rb', 'r') { |f| f.read }
+	version = nil
+	content = content.each_line.map do |line|
+		match = line.match(/(.*VERSION = ")(.*)(".*)/)
+		next line unless match
+		version = match[2].split('.')
+		version[1] = (version[1].to_i + 1).to_s
+		version = version.join('.')
+		"#{match[1]}#{version}#{match[3]}\n"
+	end.join
+	if version
+		puts "Updated version to #{version}"
+		File.open('lib/bauxite.rb', 'w') { |f| f.write content }
+	end
 end

data/doc/created.rid

@@ -1,4 +1,4 @@
-Sat, 25 Jan 2014 12:24:37 -0300
+Sat, 25 Jan 2014 13:18:13 -0300
 lib/bauxite/core/Action.rb	Sat, 25 Jan 2014 12:19:06 -0300
 lib/bauxite/core/Context.rb	Sat, 25 Jan 2014 12:19:06 -0300
 lib/bauxite/core/Errors.rb	Sat, 25 Jan 2014 12:19:06 -0300

data/lib/bauxite/application.rb

@@ -35,7 +35,8 @@ module Bauxite
 				:timeout    => 10,
 				:reset      => false,
 				:driver_opt => {},
-				:logger_opt => {}
+				:logger_opt => {},
+				:extensions => []
 			}
 
 			OptionParser.new do |opts|
@@ -79,6 +80,7 @@ module Bauxite
 					options[:driver] = 'remote'
 					options[:driver_opt][:url] = v
 				end
+				opts.on("-e", "--extension DIR", "Load extensions from DIR") { |v| options[:extensions] << v }
 				opts.on("--version", "Show version") do
 					puts "bauxite #{Bauxite::VERSION}"
 					exit
@@ -134,15 +136,21 @@ module Bauxite
 				ctx.start(actions)
 			ensure
 				if ctx.tests.any?
+					
+					failed = 0
+					
 					puts
 					puts 'Test summary:'
 					puts '============='
-					puts 'Name'.ljust(60) + 'Time'.ljust(6) + 'Status'.ljust(7)+'Error'
+					puts 'Name'.ljust(40 ) + ' Time'.ljust(7 ) + ' Status'.ljust(7)+' Error'
+					puts ''.ljust(40, '-') + ' '.ljust(7, '-') + ' '.ljust(7, '-' )+' '.ljust(5, '-')
 					ctx.tests.each do |t|
 						error = t[:error]
 						error = error ? error.message : ''
-						puts t[:name].ljust(60) + t[:time].round(3).to_s.ljust(6) + t[:status].ljust(7) + error
+						puts t[:name].ljust(40) + ' ' + t[:time].round(2).to_s.rjust(6) + ' ' + t[:status].ljust(6) + ' ' + error
+						failed += 1 if t[:status] != 'OK'
 					end
+					exit failed if failed > 0
 				end
 			end
 		end

data/lib/bauxite/core/Context.rb

@@ -65,6 +65,7 @@ module Bauxite
 		# [:verbose] if +true+, show verbose error information (e.g. backtraces) if an error occurs (defaults to +false+)
 		# [:debug] if +true+, break into the #debug console if an error occurs (defaults to +false+)
 		# [:wait] if +true+, call ::wait before stopping the test engine with #stop (defaults to +false+)
+		# [:extensions] an array of directories that contain extensions to be loaded
 		#
 		def initialize(options)
 			@options = options
@@ -75,6 +76,8 @@ module Bauxite
 			@aliases = {}
 			@tests = []
 			
+			_load_extensions(options[:extensions] || [])
+			
 			handle_errors do
 				@logger = Context::load_logger(options[:logger], options[:logger_opt])
 			end
@@ -540,6 +543,14 @@ module Bauxite
 			end
 			.select { |item| item != nil }
 		end
+		
+		def _load_extensions(dirs)
+			dirs.each do |d|
+				d = File.join(Dir.pwd, d) unless Dir.exists? d
+				d = File.absolute_path(d)
+				Dir[File.join(d, '**', '*.rb')].each { |file| require file }
+			end
+		end
 
 		# ======================================================================= #
 		# Hacks required to overcome the String#split(' ') behavior of folding the

data/lib/bauxite.rb

@@ -22,7 +22,7 @@
 
 #--
 module Bauxite
-	VERSION = "0.1.0"
+	VERSION = "0.2.0"
 end
 #++
 

data/test/extension/custom.rb

@@ -0,0 +1,12 @@
+class Bauxite::Action
+	def hello()
+		lambda { puts 'Hello World!' }
+	end
+end
+
+class Bauxite::Selector
+	def by_attr(value)
+		attr "by_attr:#{value}"
+	end
+end
+ 

data/test/extension/page.html

@@ -0,0 +1,5 @@
+<html>
+  <body>
+	<input by_attr="attr_value">
+  </body>
+</html>

data/test/extension.bxt.manual

@@ -0,0 +1,4 @@
+hello
+open "file://${__DIR__}/extension/page.html"
+assert "by_attr=attr_value" hello
+

data/test/test.bxt.manual

@@ -1,4 +1,5 @@
 test test/test1.bxt
 test test/test2.bxt "broken test"
+test test/test2.bxt "broken again"
 test test/test1.bxt "final test"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bauxite
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Patricio Zavolinsky
@@ -46,6 +46,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE
+- README.md
 - Rakefile
 - bin/bauxite
 - doc/Bauxite.html
@@ -149,6 +150,9 @@ files:
 - test/delay.bxt
 - test/delay/page.html
 - test/exec.bxt
+- test/extension.bxt.manual
+- test/extension/custom.rb
+- test/extension/page.html
 - test/format.bxt
 - test/format/page.html
 - test/frame.bxt
@@ -190,5 +194,5 @@ rubyforge_project:
 rubygems_version: 2.2.1
 signing_key: 
 specification_version: 4
-summary: Bauxite is a facade over Selenium intended for non-developers
+summary: Bauxite is a façade over Selenium intended for non-developers
 test_files: []