bauxite 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 063894fc2a6cee418888abc8d731448a22653c5c
-  data.tar.gz: 1cc13f20d0951eaed6451b75575124f558f4d063
+  metadata.gz: a79031976dbf278abe67693d4a879c6e2ef4e292
+  data.tar.gz: 6d41186a005452003dbad24083b7b44d7d08b069
 SHA512:
-  metadata.gz: c4e04c8976ba0a5a5b018dc62fac88d1204c7415114159527e3b03581e94a7119dd70f51dec32c6e3b255a8b690a2729f2ae7815810254ef0d3e1094a9b3c7d8
-  data.tar.gz: 37f4ec249b6139fd33b968d387eb5f043b5b0ccae3bbffefd47c710bb753b19784c1247e53e62b81f6b91120b4553bb494964e65d50adc6cd348f0029bcc30b0
+  metadata.gz: df42b694e3b77c1c6b2ef400b60a6070f4a67e6042f2596f7a475e82938b87ea0e17d57a11731e5400f83f951e159a11a1ca50fdd6098955e5572ccf47938f97
+  data.tar.gz: 7722a6c289e506e6851bbd09732096654d65e362820c6d8ab3dc92ff179981341bebe2494cd77c09d822f69ab0c806f4e9793bfd133a16ec67dc2c07cfeb74a8

data/README.md

@@ -23,46 +23,55 @@ 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:
-```
+```ruby
 open "http://google.com"
-write name=q "Hello WebDriver!"
-click gbqfb
+write "name=q" "Hello WebDriver!"
+click "gbqfb"
 ```
+
 Installation
 ------------
 
 In a nutshell:
-```
+```shell
 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).
+If you don't have Ruby 2.x yet, check the [Installing Ruby](#installing-ruby) section below.
+
+Remember you should probably install [Firefox](http://www.mozilla.org) (unless you want to 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`:
-```
+```ruby
 open "http://www.gnu.org/fun/jokes/helloworld.html"
 ```
 
-Launch a console and type:
+Launch a terminal/command prompt and type:
 ```
 bauxite hello.bxt
 ```
 
-Documentation
--------------
+Command-line Interface
+----------------------
+
+The `bauxite` command-line program supports several configuration options.
+
+Refer to the [RDoc documentation](http://pzavolinsky.github.io/bauxite/Bauxite/Application.html) for more details.
+
+
+The Bauxite Language
+--------------------
 
 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:
-```
+```ruby
 open "http://google.com"
-write name=q "Hello WebDriver!"
-click gbqfb
+write "name=q" "Hello WebDriver!"
+click "gbqfb"
 ```
 
 `open`, `write` and `click` are Actions:
@@ -82,8 +91,8 @@ For example, in this HTML fragment:
 ```
 
 If we want to click the "Search" button we can do the following:
-```
-click gbqfb
+```ruby
+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.
@@ -94,8 +103,8 @@ For example, in this HTML fragment:
 ```
 
 If we want to type the text "Hello WebDriver!" in textbox we can do the following:
-```
-write name=q "Hello WebDriver!"
+```ruby
+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:
@@ -111,32 +120,26 @@ 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:
-```
+```shell
 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).
+In Windows, you can install Ruby 2.x with [RubyInstaller](http://rubyinstaller.org/downloads/). After everything is installed, launch the `Start Command Prompt with Ruby` option in your start menu.
 
 Regadless of your OS, you should be able to install Bauxite with:
 
-```
+```shell
 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.
+Bauxite is both a command-line 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).
+The command-line program is called `bauxite` and has several command-line options, refer to the [RDoc documentation](http://pzavolinsky.github.io/bauxite/Bauxite/Application.html) for more details.
 
 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.
 
@@ -159,11 +162,11 @@ Functional extensions are composite constructs created using existing Bauxite ac
 ```
 
 The Bauxite code to login into this site would be:
-```
+```ruby
 open "http://hostname/login.html"
-write username "jdoe"
-write password "hello world!"
-click login
+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. 
@@ -177,55 +180,55 @@ 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:
-```
+```ruby
 # login.bxt
 open "http://hostname/login.html"
-write username "jdoe"
-write password "hello world!"
-click login
+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:
-```
+```ruby
 # login.bxt
 open "http://hostname/login.html"
-write username "${username}"
-write password "${password}"
-click login
+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`
-```
+```ruby
 # login.bxt
 params username password
 open "http://hostname/login.html"
-write username "${username}"
-write password "${password}"
-click login
+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:
-```
+```ruby
 # main_test.bxt
-load login.bxt username=jdoe "password=hello world!"
+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`:
-```
+```ruby
 # alias.bxt
-alias login load login.bxt "username=${1}" "password=${2}"
+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:
-```
+```ruby
 # main_test.bxt
-load alias.bxt
+load "alias.bxt"
 
-login jdoe "hello world!"
+login "jdoe" "hello world!"
 
 # additional actions go here
 ```
@@ -234,6 +237,45 @@ That was a bit of work but the resulting test is purely functional (minus the lo
 
 ### 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.
+Coded plugins are Ruby files that extend the Bauxite language by providing additional language elements. Coded plugins can be used to create Bauxite actions, selectors and loggers.
 
+For example lets assume that throughout a web application input elements were identified using a custom HTML attribute instead of `id`. For example:
 
+```html
+<form>
+  <input custom-attr="username" type="text"     />
+  <input custom-attr="password" type="password" />
+  <input custom-attr="login"    type="submit" value="Login"/>
+</form>
+```
+
+Using standard Bauxite language we could select these elements using:
+```ruby
+# === my_test.bxt === #
+write "attr=custom-attr:username" "jdoe"
+write "attr=custom-attr:password" "hello world!"
+click "attr=custom-attr:login"
+```
+
+But we can improve the overall readability of our test by using a coded plugin:
+```ruby
+# === plugins/custom_selector.rb === #
+class Bauxite::Selector
+	def custom(value)
+		attr "custom-attr:#{value}"
+	end
+end
+```
+
+Now we can change our test to look like this:
+```ruby
+# === my_test.bxt === #
+write "custom=username" "jdoe"
+write "custom=password" "hello world!"
+click "custom=login"
+```
+
+Finally, to execute Bauxite loading our plugin we can type:
+```
+bauxite -e plugins my_test.bxt
+```

data/Rakefile

@@ -49,8 +49,7 @@ end
 # === Documentation ========================================================= #
 desc "Generate Bauxite documentation"
 task :doc do
-	doc_dirs = ['core','actions','selectors','loggers'].map { |d| File.join('lib', 'bauxite',d,'*') }.join(' ')
-	`rdoc -O -U #{doc_dirs}`
+	system("rdoc -O -U -V #{File.join('lib', 'bauxite')}")
 end
 
 desc "Open documentation in a browser"

data/doc/Bauxite/Action.html

@@ -578,7 +578,11 @@ autocomplete (pressing the <code>TAB</code> key).</p>
           <div class="method-source-code" id="debug-source">
             <pre><span class="ruby-comment"># File lib/bauxite/actions/debug.rb, line 35</span>
 <span class="ruby-keyword">def</span> <span class="ruby-identifier">debug</span>
-        <span class="ruby-identifier">lambda</span> { <span class="ruby-identifier">_debug_process</span> }
+        <span class="ruby-identifier">lambda</span> <span class="ruby-keyword">do</span>
+                <span class="ruby-ivar">@ctx</span>.<span class="ruby-identifier">with_vars</span>({ <span class="ruby-string">&#39;__DEBUG__&#39;</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-keyword">true</span> }) <span class="ruby-keyword">do</span>
+                        <span class="ruby-identifier">_debug_process</span>
+                <span class="ruby-keyword">end</span>
+        <span class="ruby-keyword">end</span>
 <span class="ruby-keyword">end</span></pre>
           </div>
           

data/doc/Bauxite/Application.html

@@ -0,0 +1,249 @@
+<!DOCTYPE html>
+
+<html>
+<head>
+<meta charset="UTF-8">
+
+<title>class Bauxite::Application - RDoc Documentation</title>
+
+<link href="../fonts.css" rel="stylesheet">
+<link href="../rdoc.css" rel="stylesheet">
+
+<script type="text/javascript">
+  var rdoc_rel_prefix = "../";
+</script>
+
+<script src="../js/jquery.js"></script>
+<script src="../js/navigation.js"></script>
+<script src="../js/search_index.js"></script>
+<script src="../js/search.js"></script>
+<script src="../js/searcher.js"></script>
+<script src="../js/darkfish.js"></script>
+
+
+<body id="top" role="document" class="class">
+<nav role="navigation">
+  <div id="project-navigation">
+    <div id="home-section" role="region" title="Quick navigation" class="nav-section">
+  <h2>
+    <a href="../index.html" rel="home">Home</a>
+  </h2>
+
+  <div id="table-of-contents-navigation">
+    <a href="../table_of_contents.html#pages">Pages</a>
+    <a href="../table_of_contents.html#classes">Classes</a>
+    <a href="../table_of_contents.html#methods">Methods</a>
+  </div>
+</div>
+
+    <div id="search-section" role="search" class="project-section initially-hidden">
+  <form action="#" method="get" accept-charset="utf-8">
+    <div id="search-field-wrapper">
+      <input id="search-field" role="combobox" aria-label="Search"
+             aria-autocomplete="list" aria-controls="search-results"
+             type="text" name="search" placeholder="Search" spellcheck="false"
+             title="Type to search, Up and Down to navigate, Enter to load">
+    </div>
+
+    <ul id="search-results" aria-label="Search Results"
+        aria-busy="false" aria-expanded="false"
+        aria-atomic="false" class="initially-hidden"></ul>
+  </form>
+</div>
+
+  </div>
+
+  
+<div class="nav-section">
+  <h3>Table of Contents</h3>
+
+  <ul class="link-list" role="directory">
+    <li><a href="#class-Bauxite::Application-label-Synopsis">Synopsis</a>
+    <li><a href="#class-Bauxite::Application-label-Options">Options</a>
+    <li><a href="#class-Bauxite::Application-label-Exit+Status">Exit Status</a>
+  </ul>
+</div>
+
+
+  <div id="class-metadata">
+    
+    <div id="parent-class-section" class="nav-section">
+  <h3>Parent</h3>
+
+  
+  <p class="link">Object
+  
+</div>
+
+    
+    
+    
+  </div>
+</nav>
+
+<main role="main" aria-labelledby="class-Bauxite::Application">
+  <h1 id="class-Bauxite::Application" class="class">
+    class Bauxite::Application
+  </h1>
+
+  <section class="description">
+    
+<p><code>bauxite</code> command-line program.</p>
+
+<p>This program executes Bauxite tests and outputs the execution progress and
+tests results to the terminal.</p>
+
+<h2 id="class-Bauxite::Application-label-Synopsis">Synopsis<span><a href="#class-Bauxite::Application-label-Synopsis">&para;</a> <a href="#documentation">&uarr;</a></span></h2>
+
+<pre class="ruby"><span class="ruby-identifier">bauxite</span> [<span class="ruby-constant">OPTIONS</span>] <span class="ruby-identifier">file1</span> <span class="ruby-identifier">file2</span> <span class="ruby-operator">...</span>
+<span class="ruby-comment"># =&gt; Executes file1, then file2, and so on.</span>
+
+<span class="ruby-identifier">bauxite</span> [<span class="ruby-constant">OPTIONS</span>] <span class="ruby-operator">-</span><span class="ruby-identifier">d</span>
+<span class="ruby-comment"># =&gt; Start Bauxite directly in the debug console.</span>
+
+<span class="ruby-identifier">bauxite</span> [<span class="ruby-constant">OPTIONS</span>]
+<span class="ruby-comment"># =&gt; Start Bauxite and read test actions from the standard input.</span>
+</pre>
+
+<h2 id="class-Bauxite::Application-label-Options">Options<span><a href="#class-Bauxite::Application-label-Options">&para;</a> <a href="#documentation">&uarr;</a></span></h2>
+
+<p>For a detailed list of options for your Bauxite version execute:</p>
+
+<pre>bauxite -h</pre>
+<dl class="rdoc-list label-list"><dt>-v, --verbose
+<dd>
+<p>Show verbose error messages (i.e. print exception names and backtraces).</p>
+</dd><dt>-t, --timeout SECONDS
+<dd>
+<p>Number of seconds to wait before issuing a timeout error. This timeout
+applies only to Selectors.</p>
+</dd><dt>-d, --debug
+<dd>
+<p>If an error occurs, break into the debug console. This mode is very useful
+to try different selector combinations and debug NoSuchElementError errors.</p>
+</dd><dt>-p, --provider DRIVER
+<dd>
+<p>Selenium WebDriver provider. Defaults to <code>firefox</code>.</p>
+
+<p>Other options include:</p>
+<ul><li>
+<p><code>remote</code></p>
+</li><li>
+<p><code>ie</code></p>
+</li><li>
+<p><code>chrome</code></p>
+</li><li>
+<p><code>android</code></p>
+</li><li>
+<p><code>iphone</code></p>
+</li><li>
+<p><code>opera</code></p>
+</li><li>
+<p><code>phantomjs</code></p>
+</li><li>
+<p><code>safari</code></p>
+</li></ul>
+
+<p>Driver availability dependes on the system running Bauxite.</p>
+</dd><dt>-P, --provider-option OPTION
+<dd>
+<p>A <code>name=value</code> pair of options that are directly forwarded to
+the Selenium WebDriver provider. This option argument can appear multiple
+times in the command line to specify multiple options.</p>
+</dd><dt>-l, --logger LOGGER
+<dd>
+<p>Logger instance to use. Defaults to <code>xterm</code> if the
+<code>TERM</code> environment variable is set to <code>xterm</code>,
+otherwise it defaults to <code>terminal</code>.</p>
+
+<p>To see a complete list of the available loggers execute:</p>
+
+<pre>bauxite -h</pre>
+</dd><dt>-L, --logger-option OPTION
+<dd>
+<p>A <code>name=value</code> pair of options that are directly forwarded to
+the logger. This option argument can appear multiple times in the command
+line to specify multiple options.</p>
+</dd><dt>-r, --reset
+<dd>
+<p>Issue a <a href="Action.html#method-i-reset">Bauxite::Action#reset</a>
+action between every test specified in the command line. This option
+enforces test isolation by resetting the test context before each test
+(this removes cookies, sessions, etc. from the previous test).</p>
+</dd><dt>-w, --wait
+<dd>
+<p>Wait for user input when the test completes instead of closing the browser
+window.</p>
+</dd><dt>-u, --url URL
+<dd>
+<p>This option is an alias of:</p>
+
+<pre>-p remote -P url=URL</pre>
+
+<p>If <code>URL</code> is not present
+<code>http://localhost:4444/wd/hub</code> will be assumed.</p>
+</dd><dt>-e, --extension DIR
+<dd>
+<p>Loads every Ruby file (*.rb) inside <code>DIR</code> (and subdirectories).
+This option can be used to load custom Bauxite extensions (e.g. Actions, 
+Selectors, <a href="Loggers.html">Loggers</a>, etc.) for a specific test
+run.</p>
+
+<p>For example:</p>
+
+<pre class="ruby"><span class="ruby-comment"># === custom/my_selector.rb ======= #</span>
+<span class="ruby-keyword">class</span> <span class="ruby-constant">Bauxite</span><span class="ruby-operator">::</span><span class="ruby-constant">Selector</span>
+    <span class="ruby-keyword">def</span> <span class="ruby-identifier">by_attr</span>(<span class="ruby-identifier">value</span>)
+        <span class="ruby-identifier">attr</span> <span class="ruby-node">&quot;by_attr:#{value}&quot;</span>
+    <span class="ruby-keyword">end</span>
+<span class="ruby-keyword">end</span>
+<span class="ruby-comment"># === end custom/my_selector.rb === #</span>
+
+<span class="ruby-comment"># === custom/my_test.bxt ========== #</span>
+<span class="ruby-comment"># ...</span>
+<span class="ruby-identifier">assert</span> <span class="ruby-string">&quot;by_attr=attr_value&quot;</span> <span class="ruby-identifier">hello</span>
+<span class="ruby-comment"># ...</span>
+<span class="ruby-comment"># === end custom/my_test.bxt ====== #</span>
+
+<span class="ruby-identifier">bauxite</span> <span class="ruby-operator">-</span><span class="ruby-identifier">e</span> <span class="ruby-identifier">custom</span> <span class="ruby-identifier">custom</span><span class="ruby-operator">/</span><span class="ruby-identifier">my_test</span>.<span class="ruby-identifier">bxt</span>
+</pre>
+</dd><dt>--version
+<dd>
+<p>Shows the Bauxite version.</p>
+</dd></dl>
+
+<h2 id="class-Bauxite::Application-label-Exit+Status">Exit Status<span><a href="#class-Bauxite::Application-label-Exit+Status">&para;</a> <a href="#documentation">&uarr;</a></span></h2>
+
+<p>The <code>bauxite</code> program exits with <code>zero</code> if every
+action in the test succeeded and <code>non-zero</code> otherwise.</p>
+
+<p>If the test run includes multiple <a
+href="Action.html#method-i-test">Bauxite::Action#test</a> actions, the exit
+status equals the number of failed test cases (again, <code>zero</code>
+indicates success).</p>
+
+  </section>
+
+  
+  
+  
+  <section id="5Buntitled-5D" class="documentation-section">
+    
+
+    
+
+    
+
+    
+
+    
+  </section>
+</main>
+
+
+<footer id="validator-badges" role="contentinfo">
+  <p><a href="http://validator.w3.org/check/referer">Validate</a>
+  <p>Generated by <a href="http://rdoc.rubyforge.org">RDoc</a> 4.1.1.
+  <p>Based on <a href="http://deveiate.org/projects/Darkfish-Rdoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.
+</footer>
+