doc/index.html in bauxite-0.4.0 vs doc/index.html in bauxite-0.4.1
- old
+ new
@@ -53,16 +53,27 @@
</div>
</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>
<li><a href="./Bauxite/Application.html">Bauxite::Application</a>
@@ -89,10 +100,12 @@
<li><a href="./Bauxite/Loggers/TerminalLogger.html">Bauxite::Loggers::TerminalLogger</a>
<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>
<li><a href="./Bauxite/SelectorModule.html">Bauxite::SelectorModule</a>
@@ -102,16 +115,355 @@
</div>
</nav>
<main role="main">
-<p>This is the API documentation for RDoc Documentation.
+
+
+<h1 id="label-bauxite">bauxite<span><a href="#label-bauxite">¶</a> <a href="#documentation">↑</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">"selenium-webdriver"</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">"http://google.com"</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">'q'</span>)
+<span class="ruby-identifier">element</span>.<span class="ruby-identifier">send_keys</span> <span class="ruby-string">"Hello WebDriver!"</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 "http://google.com"
+write "name=q" "Hello WebDriver!"
+click "gbqfb"</pre>
+
+<h2 id="label-Installation">Installation<span><a href="#label-Installation">¶</a> <a href="#documentation">↑</a></span></h2>
+
+<p>In a nutshell:</p>
+
+<pre>gem install bauxite</pre>
+
+<p>If you don'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">¶</a> <a href="#documentation">↑</a></span></h2>
+
+<p>Paste the following text into <code>hello.bxt</code>:</p>
+
+<pre>open "http://www.gnu.org/fun/jokes/helloworld.html"</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">¶</a> <a href="#documentation">↑</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">¶</a> <a href="#documentation">↑</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 "http://google.com"
+write "name=q" "Hello WebDriver!"
+click "gbqfb"</pre>
+
+<p><code>open</code>, <code>write</code> and <code>click</code> are Actions: -
+<code>open</code> takes a single URL argument
+(<code>"http://google.com"</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>"Hello
+WebDriver!"</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>"</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><input type="submit" id="gbqfb" value="Search" /></pre>
+
+<p>If we want to click the “Search” button we can do the following:</p>
+
+<pre>click "gbqfb"</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><input type="text" name="q" /></pre>
+
+<p>If we want to type the text “Hello WebDriver!” in textbox we can do the
+following:</p>
+
+<pre>write "name=q" "Hello WebDriver!"</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">¶</a> <a href="#documentation">↑</a></span></h2>
+
+<p>I won'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">¶</a> <a href="#documentation">↑</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">¶</a> <a href="#documentation">↑</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">¶</a> <a href="#documentation">↑</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><!-- 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></pre>
+
+<p>The <a href="Bauxite.html">Bauxite</a> code to login into this site would
+be:</p>
+
+<pre>open "http://hostname/login.html"
+write "username" "jdoe"
+write "password" "hello world!"
+click "login"</pre>
+
+<p>If we were creating a suite of automated web tests for our
+<em>hostname</em> 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.</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 "http://hostname/login.html"
+write "username" "jdoe"
+write "password" "hello world!"
+click "login"</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 "http://hostname/login.html"
+write "username" "${username}"
+write "password" "${password}"
+click "login"</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 "http://hostname/login.html"
+write "username" "${username}"
+write "password" "${password}"
+click "login"</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 "login.bxt" "username=jdoe" "password=hello world!"
+
+# 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 "login" "load" "login.bxt" "username=${1}" "password=${2}"</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 "alias.bxt"
+
+login "jdoe" "hello world!"
+
+# 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">¶</a> <a href="#documentation">↑</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><form>
+ <input custom-attr="username" type="text" />
+ <input custom-attr="password" type="password" />
+ <input custom-attr="login" type="submit" value="Login"/>
+</form></pre>
+
+<p>Using standard <a href="Bauxite.html">Bauxite</a> language we could select
+these elements using:</p>
+
+<pre># === my_test.bxt === #
+write "attr=custom-attr:username" "jdoe"
+write "attr=custom-attr:password" "hello world!"
+click "attr=custom-attr:login"</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">"custom-attr:#{value}"</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 "custom=username" "jdoe"
+write "custom=password" "hello world!"
+click "custom=login"</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>