bauxite 0.4.0 → 0.4.1

data/doc/index.html

@@ -55,12 +55,23 @@
   </div>
 
   <div id="project-metadata">
-    
+    <div id="fileindex-section" class="nav-section">
+  <h3>Pages</h3>
+
+  <ul class="link-list">
+  
+    <li><a href="./README_md.html">README</a>
+  
+  </ul>
+</div>
+
     <div id="classindex-section" class="nav-section">
   <h3>Class and Module Index</h3>
 
   <ul class="link-list">
   
+    <li><a href="./Bauxite.html">Bauxite</a>
+  
     <li><a href="./Bauxite/Action.html">Bauxite::Action</a>
   
     <li><a href="./Bauxite/ActionModule.html">Bauxite::ActionModule</a>
@@ -91,6 +102,8 @@
   
     <li><a href="./Bauxite/Loggers/XtermLogger.html">Bauxite::Loggers::XtermLogger</a>
   
+    <li><a href="./Bauxite/Parser.html">Bauxite::Parser</a>
+  
     <li><a href="./Bauxite/ParserModule.html">Bauxite::ParserModule</a>
   
     <li><a href="./Bauxite/Selector.html">Bauxite::Selector</a>
@@ -104,14 +117,353 @@
 </nav>
 
 <main role="main">
-<p>This is the API documentation for RDoc Documentation.
+
+
+<h1 id="label-bauxite">bauxite<span><a href="#label-bauxite">&para;</a> <a href="#documentation">&uarr;</a></span></h1>
+
+<p><a href="Bauxite.html">Bauxite</a> is a façade over Selenium intended for
+non-developers</p>
+
+<p>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.</p>
+
+<p>Take a look at the following Ruby excerpt from <a
+href="http://code.google.com/p/selenium/wiki/RubyBindings">code.google.com/p/selenium/wiki/RubyBindings</a>:</p>
+
+<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&quot;selenium-webdriver&quot;</span>
+
+<span class="ruby-identifier">driver</span> = <span class="ruby-constant">Selenium</span><span class="ruby-operator">::</span><span class="ruby-constant">WebDriver</span>.<span class="ruby-identifier">for</span> :<span class="ruby-identifier">firefox</span>
+<span class="ruby-identifier">driver</span>.<span class="ruby-identifier">navigate</span>.<span class="ruby-identifier">to</span> <span class="ruby-string">&quot;http://google.com&quot;</span>
+
+<span class="ruby-identifier">element</span> = <span class="ruby-identifier">driver</span>.<span class="ruby-identifier">find_element</span>(:<span class="ruby-identifier">name</span>, <span class="ruby-string">&#39;q&#39;</span>)
+<span class="ruby-identifier">element</span>.<span class="ruby-identifier">send_keys</span> <span class="ruby-string">&quot;Hello WebDriver!&quot;</span>
+<span class="ruby-identifier">element</span>.<span class="ruby-identifier">submit</span>
+
+<span class="ruby-identifier">puts</span> <span class="ruby-identifier">driver</span>.<span class="ruby-identifier">title</span>
+
+<span class="ruby-identifier">driver</span>.<span class="ruby-identifier">quit</span>
+</pre>
+
+<p>While developers might find that code expressive enough, non-developers
+might be a bit shocked.</p>
+
+<p>The equivalent <a href="Bauxite.html">Bauxite</a> test is easier on the
+eyes:</p>
+
+<pre>open &quot;http://google.com&quot;
+write &quot;name=q&quot; &quot;Hello WebDriver!&quot;
+click &quot;gbqfb&quot;</pre>
+
+<h2 id="label-Installation">Installation<span><a href="#label-Installation">&para;</a> <a href="#documentation">&uarr;</a></span></h2>
+
+<p>In a nutshell:</p>
+
+<pre>gem install bauxite</pre>
+
+<p>If you don&#39;t have Ruby 2.x yet, check the <a
+href="#installing-ruby">Installing Ruby</a> section below.</p>
+
+<p>Remember you should probably install <a
+href="http://www.mozilla.org">Firefox</a> (unless you want to use other
+browsers or Selenium server by specifying the <code>-p</code> switch to the
+<code>bauxite</code> executable).</p>
+
+<h2 id="label-Hello+World">Hello World<span><a href="#label-Hello+World">&para;</a> <a href="#documentation">&uarr;</a></span></h2>
+
+<p>Paste the following text into <code>hello.bxt</code>:</p>
+
+<pre>open &quot;http://www.gnu.org/fun/jokes/helloworld.html&quot;</pre>
+
+<p>Launch a terminal/command prompt and type:</p>
+
+<pre>bauxite hello.bxt</pre>
+
+<h2 id="label-Command-line+Interface">Command-line Interface<span><a href="#label-Command-line+Interface">&para;</a> <a href="#documentation">&uarr;</a></span></h2>
+
+<p>The <code>bauxite</code> command-line program supports several
+configuration options.</p>
+
+<p>Refer to the <a
+href="http://pzavolinsky.github.io/bauxite/Bauxite/Application.html">RDoc
+documentation</a> for more details.</p>
+
+<h2 id="label-The+Bauxite+Language">The <a href="Bauxite.html">Bauxite</a> Language<span><a href="#label-The+Bauxite+Language">&para;</a> <a href="#documentation">&uarr;</a></span></h2>
+
+<p>The <a href="Bauxite.html">Bauxite</a> language is composed of two elements
+<code>Actions</code> and <code>Selectors</code>: 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.</p>
+
+<p>A typical <a href="Bauxite.html">Bauxite</a> 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:</p>
+
+<pre>open &quot;http://google.com&quot;
+write &quot;name=q&quot; &quot;Hello WebDriver!&quot;
+click &quot;gbqfb&quot;</pre>
+
+<p><code>open</code>, <code>write</code> and <code>click</code> are Actions: -
+<code>open</code> takes a single URL argument
+(<code>&quot;http://google.com&quot;</code>) and opens that URL in the
+browser. - <code>write</code> takes two arguments, a Selector
+(<code>name=q</code>, more on this in a bit) and a text (<code>&quot;Hello
+WebDriver!&quot;</code>), and writes the text into the element specified by
+the Selector. - <code>click</code> takes a single Selector argument
+(<code>gbqfb</code>) and clicks the element specified by the Selector.</p>
+
+<p>In general, Action arguments can be surrounded by optional double quote
+characters (<code>&quot;</code>). If an argument contains a space
+character, the quotes are mandatory (this is the case for the second
+argument to <code>write</code> in the example above).</p>
+
+<p>Some Actions operate on page elements (e.g. <code>write</code>,
+<code>click</code>, etc.). In order to locate these elements, <a
+href="Bauxite.html">Bauxite</a> uses Selectors.</p>
+
+<p>The trivial Selector is just a text that matches the last portion of the
+<code>id</code> attribute of the target element.</p>
+
+<p>For example, in this HTML fragment:</p>
+
+<pre>&lt;input type=&quot;submit&quot; id=&quot;gbqfb&quot; value=&quot;Search&quot; /&gt;</pre>
+
+<p>If we want to click the “Search” button we can do the following:</p>
+
+<pre>click &quot;gbqfb&quot;</pre>
+
+<p><a href="Bauxite.html">Bauxite</a> supports several other Selectors such as
+<code>name=</code> in the example above. The <code>name</code> Selector
+finds elements whose <code>name</code> attribute matches the text following
+the <code>=</code> sign.</p>
+
+<p>For example, in this HTML fragment:</p>
+
+<pre>&lt;input type=&quot;text&quot; name=&quot;q&quot; /&gt;</pre>
+
+<p>If we want to type the text “Hello WebDriver!” in textbox we can do the
+following:</p>
+
+<pre>write &quot;name=q&quot; &quot;Hello WebDriver!&quot;</pre>
+
+<p>This section presented a brief introduction into the basic <a
+href="Bauxite.html">Bauxite</a> concepts. For more details and a list of
+every Action and Selector available, refer to the RDoc generated
+documentation in:</p>
+<ul><li>
+<p><a
+href="http://pzavolinsky.github.io/bauxite/Bauxite/Action.html#Action+Methods">Available
+Actions</a></p>
+</li><li>
+<p><a
+href="http://pzavolinsky.github.io/bauxite/Bauxite/Selector.html#Selector+Methods">Available
+Bauxite Selectors</a></p>
+</li><li>
+<p><a
+href="http://pzavolinsky.github.io/bauxite/Bauxite/Selector.html#class-Bauxite::Selector-label-Standard+Selenium+Selectors">Selenium
+Standard Selectors</a></p>
+</li><li>
+<p><a href="http://pzavolinsky.github.io/bauxite/Bauxite/Action.html">Creating
+new Actions</a></p>
+</li><li>
+<p><a
+href="http://pzavolinsky.github.io/bauxite/Bauxite/Selector.html">Creating
+new Selectors</a></p>
+</li></ul>
+
+<h2 id="label-Installing+Ruby">Installing Ruby<span><a href="#label-Installing+Ruby">&para;</a> <a href="#documentation">&uarr;</a></span></h2>
+
+<p>I won&#39;t cover all the details of installing Ruby on your system (Google
+knows best), but the following should probably work.</p>
+
+<p>In GNU/Linux, you can install <a href="http://rvm.io/">RVM</a>, then Ruby:</p>
+
+<pre>curl -sSL https://get.rvm.io | bash -s stable
+source ~/.rvm/scripts/rvm
+rvm install ruby-2.1.0</pre>
+
+<p>In Windows, you can install Ruby 2.x with <a
+href="http://rubyinstaller.org/downloads/">RubyInstaller</a>. After
+everything is installed, launch the <code>Start Command Prompt with
+Ruby</code> option in your start menu.</p>
+
+<p>Regadless of your OS, you should be able to install <a
+href="Bauxite.html">Bauxite</a> with:</p>
+
+<pre>gem install bauxite</pre>
+
+<h2 id="label-Implementation">Implementation<span><a href="#label-Implementation">&para;</a> <a href="#documentation">&uarr;</a></span></h2>
+
+<p><a href="Bauxite.html">Bauxite</a> is both a command-line program and a
+library. You can use the program to run <a href="Bauxite.html">Bauxite</a>
+tests directly from a terminal, or you can embed the library in your own
+application.</p>
+
+<p>The command-line program is called <code>bauxite</code> and has several
+command-line options, refer to the <a
+href="http://pzavolinsky.github.io/bauxite/Bauxite/Application.html">RDoc
+documentation</a> for more details.</p>
+
+<p>If you are looking to embed <a href="Bauxite.html">Bauxite</a> in your
+application take a look a the code in
+<code>lib/bauxite/application.rb</code>, that should give you a full
+example of how to create a <a href="Bauxite.html">Bauxite</a> Context and
+execute some actions.</p>
+
+<h2 id="label-Extending+Bauxite">Extending <a href="Bauxite.html">Bauxite</a><span><a href="#label-Extending+Bauxite">&para;</a> <a href="#documentation">&uarr;</a></span></h2>
+
+<p><a href="Bauxite.html">Bauxite</a> supports two types of extensions:
+functional extensions and coded plugins.</p>
+
+<h3 id="label-Functional+extensions">Functional extensions<span><a href="#label-Functional+extensions">&para;</a> <a href="#documentation">&uarr;</a></span></h3>
+
+<p>Functional extensions are composite constructs created using existing <a
+href="Bauxite.html">Bauxite</a> actions to convey functional meaning. For
+example, imagine a login form:</p>
+
+<pre>&lt;!-- http://hostname/login.html --&gt;
+&lt;form&gt;
+  &lt;input id=&quot;username&quot; name=&quot;username&quot; type=&quot;text&quot;     /&gt;
+  &lt;input id=&quot;password&quot; name=&quot;password&quot; type=&quot;password&quot; /&gt;
+  &lt;input id=&quot;login&quot; type=&quot;submit&quot; value=&quot;Login&quot;/&gt;
+&lt;/form&gt;</pre>
+
+<p>The <a href="Bauxite.html">Bauxite</a> code to login into this site would
+be:</p>
+
+<pre>open &quot;http://hostname/login.html&quot;
+write &quot;username&quot; &quot;jdoe&quot;
+write &quot;password&quot; &quot;hello world!&quot;
+click &quot;login&quot;</pre>
+
+<p>If we were creating a suite of automated web tests for our
+<em>hostname</em> site, we&#39;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.</p>
+
+<p>Of course we can do better. We can split <a href="Bauxite.html">Bauxite</a>
+tests into many files and include one test into another with the
+<code>load</code> action.</p>
+
+<pre># my_test.bxt (by the way, this is a comment)
+load other_test_fragment.bxt
+...</pre>
+
+<p>Back to our login example, first we can package the login part of our tests
+into a separate <a href="Bauxite.html">Bauxite</a> file:</p>
+
+<pre># login.bxt
+open &quot;http://hostname/login.html&quot;
+write &quot;username&quot; &quot;jdoe&quot;
+write &quot;password&quot; &quot;hello world!&quot;
+click &quot;login&quot;</pre>
+
+<p>Of course we would like to be able to login with different
+username/password combinations, so we can replace the literals in
+<code>login.bxt</code> with variables:</p>
+
+<pre># login.bxt
+open &quot;http://hostname/login.html&quot;
+write &quot;username&quot; &quot;${username}&quot;
+write &quot;password&quot; &quot;${password}&quot;
+click &quot;login&quot;</pre>
+
+<p>Now, we would like to assert that both <code>username</code> and
+<code>password</code> variables are set before calling our test (just in
+case someone forgets). We can do this with <code>params</code></p>
+
+<pre># login.bxt
+params username password
+open &quot;http://hostname/login.html&quot;
+write &quot;username&quot; &quot;${username}&quot;
+write &quot;password&quot; &quot;${password}&quot;
+click &quot;login&quot;</pre>
+
+<p>In our main test we can load <code>login.bxt</code> and specify the
+variables required using this code:</p>
+
+<pre># main_test.bxt
+load &quot;login.bxt&quot; &quot;username=jdoe&quot; &quot;password=hello world!&quot;
+
+# additional actions go here</pre>
+
+<p>We could improve this even further by creating an <code>alias</code> to
+simplify the login process. To do this, lets create an new file called
+<code>alias.bxt</code>:</p>
+
+<pre># alias.bxt
+alias &quot;login&quot; &quot;load&quot; &quot;login.bxt&quot; &quot;username=${1}&quot; &quot;password=${2}&quot;</pre>
+
+<p>Note that the <code>alias</code> action supports positional arguments.</p>
+
+<p>Now we can change our main test to use our alias:</p>
+
+<pre># main_test.bxt
+load &quot;alias.bxt&quot;
+
+login &quot;jdoe&quot; &quot;hello world!&quot;
+
+# additional actions go here</pre>
+
+<p>That was a bit of work but the resulting test is purely functional (minus
+the load alias part, of course).</p>
+
+<h3 id="label-Coded+plugins">Coded plugins<span><a href="#label-Coded+plugins">&para;</a> <a href="#documentation">&uarr;</a></span></h3>
+
+<p>Coded plugins are Ruby files that extend the <a
+href="Bauxite.html">Bauxite</a> language by providing additional language
+elements. Coded plugins can be used to create <a
+href="Bauxite.html">Bauxite</a> actions, selectors and loggers.</p>
+
+<p>For example lets assume that throughout a web application input elements
+were identified using a custom HTML attribute instead of <code>id</code>.
+For example:</p>
+
+<pre>&lt;form&gt;
+  &lt;input custom-attr=&quot;username&quot; type=&quot;text&quot;     /&gt;
+  &lt;input custom-attr=&quot;password&quot; type=&quot;password&quot; /&gt;
+  &lt;input custom-attr=&quot;login&quot;    type=&quot;submit&quot; value=&quot;Login&quot;/&gt;
+&lt;/form&gt;</pre>
+
+<p>Using standard <a href="Bauxite.html">Bauxite</a> language we could select
+these elements using:</p>
+
+<pre># === my_test.bxt === #
+write &quot;attr=custom-attr:username&quot; &quot;jdoe&quot;
+write &quot;attr=custom-attr:password&quot; &quot;hello world!&quot;
+click &quot;attr=custom-attr:login&quot;</pre>
+
+<p>But we can improve the overall readability of our test by using a coded
+plugin:</p>
+
+<pre class="ruby"><span class="ruby-comment"># === plugins/custom_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">custom</span>(<span class="ruby-identifier">value</span>)
+        <span class="ruby-identifier">attr</span> <span class="ruby-node">&quot;custom-attr:#{value}&quot;</span>
+    <span class="ruby-keyword">end</span>
+<span class="ruby-keyword">end</span>
+</pre>
+
+<p>Now we can change our test to look like this:</p>
+
+<pre># === my_test.bxt === #
+write &quot;custom=username&quot; &quot;jdoe&quot;
+write &quot;custom=password&quot; &quot;hello world!&quot;
+click &quot;custom=login&quot;</pre>
+
+<p>Finally, to execute <a href="Bauxite.html">Bauxite</a> loading our plugin
+we can type:</p>
+
+<pre>bauxite -e plugins my_test.bxt</pre>
 </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.0.
+  <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>