WatirCraft Framework

This page is no longer being updated. For current information on this framework and the latest releases see our page on github

Please send bug reports, feature requests and other comments to feedback@watircraft.com

The WatirCraft source code is hosted at GitHub.

WatirCraft LLC provides training and consulting on Watir and the new WatirCraft framework. Contact us for details.

There are two different ways that you can install the WatirCraft framework: automatic or manual. These are listed below.

In either case, you should first do

gem update --system

This needs to be done once after you install Ruby. If you don’t do this, you will get dependency errors.

You can verify that this has been done:

gem -v

This should be “1.3.1” or newer.

Automatic

Run the following if you haven’t already:

gem sources -a http://gems.github.com

Install the latest gem from GitHub:

gem install bret-watircraft

This will only work if you are connected to the Internet, and not behind a firewall.

Manual

Download the gem from this page.

Open a command shell to the directory containing the downloaded gem.

gem install watircraft

(Do not use the --local option. It will lead to dependency errors.)

If you have installed taza—particularly the beta versions of watircraft that were called “taza”—then you need to uninstall it to use watircraft. Sorry about the conflict.

Gem download

• Fix bug with script\console: no such file to load—site_start

Gem download

You will need to run “watircraft .” at the root of your project in order to
update your test suite to work with this version of the WatirCraft Framework.

Summary

• Code for cucumber or rspec now runs in the same context. There is also a new console that allows you to run code in the same context. This should vastly simplify learnability and debugging options. Please try out the new script console.

• Added support for tables. Please see the rdoc for Page#table for details on how to use this.

Details on New Features

• Added script/console. This provides an interactive Ruby shell (irb) that executes in the context of your site. Hopefully a useful learning and debugging tool.

• Added new methods primarily intended to be used from within the script/console. In the default context (site), there is “pages” which returns a list of the pages defined for the site. In the context of a page, there are “elements” and “fields”. And also “elements_exist?” and “values”. To get better formatted results, type “y” before these commands.

• Rspec tests (“describe” & “it”) now execute in the context of a site, or at least something very similar. This makes it easier to share libraries between rspec and cucumber tests. Also easier to translate learning from one to the other.

• Added Page#element_exists? This method will return false if an intermediate part of the Watir syntax (e.g. frame) throws a Not Found exception. This makes page.element_exists(:my_element) better than using page.my_element.exists?

• Added Site#page method. Now, site.page(“check out”) is the same as site.check_out_page

• You can now use strings as arguments to Page.element and Page.field. These strings can even be in “human-form” with spaces and capitolization. They will automatically be “computerized”.

Other Changes

• Site#origin now returns the base url of the site. (Was: Site#url).

• Hard-coded dependencies on Cucumber 0.1.16 and Rspec 1.1.12. Previously, watircraft would install the latest versions of these gems, which could create inconsistencies if installed over time on different machines. Now this won’t happen. However, if newer versions are installed on your machine, they will be used.

• Updated to use Cucumber 0.1.16 instead of 0.1.13.

• Explicitly declare dependency on Watir 1.6.2 (or newer). Previously this was assumed.

Gem download

Another patch release. Like 0.3.1, no need to update if your project is
already at 0.3.x

• Fix “undefined method display_value” error that appeared when creating page fields with links or parents.

Gem download

This patch release includes some fixes and an improved updater.

Update Notes

You can update an existing project created with a previous release
by typing “watircraft .” in root of your project.
(That is watircraft space period.)

If your project was created with or already updated to 0.3.0, you do not
need to update (although it won’t hurt if you do).

If your project was created with beta2 or previous, you will need to update
to use this version.

Improvements to Updater

• When using “watircraft” to update an existing project, you no longer have to specify the site name.
• When updating, the “correct” files will automatically be replaced.
• The initialize.rb file is now stamped with the time and version.

Fixes

• Automatically install cucumber when installing watircraft.
• Allow pages to be specified in camel case (or not) in the page generator.
• Changed method of declaring dependencies in an attempt to fix reported “could not find site generator” error which I cannot reproduce.
• Improved documentation for generators. (Type “watircraft” or “script\generate page” to see this.)
• You can now use the cucumber command from inside the tests/features directory (previously it would only work from project root).

Gem download

Repackaged as watircraft gem version 0.3.0.

Features

• You can now get a list of the script/generate commands that are available to you by typing “script/generate” from the root of your project. Currently these are page, spec and steps. However, additional generators will be made available in future versions of this framework, as well as other plug-ins.

Installation Instructions

gem install watircraft

Update Instructions

If you have a project created with a prior version of watircraft (aka taza), you
will need to do the following.

1. Open a command shell to the root of your project (i.e. where you type rake commands).
2. Type the following:

   watircraft . --site=your_site_name 

   This will add some files and ask whether you want to replace several files. Say yes (‘y’) and replace the following files (only):

   • script/destroy
   • script/generate
   • feature_helper.rb
   • spec_helper.rb
   • world.rb

User Visible Changes

• Renamed gem from “taza” to “watircraft”.
• Rename “taza” command to “watircraft”.
• Removed flow generator. Plan is to use Watirloo’s use case class instead.
• Now uses rspec version 1.1.12.
• Added Readme and History files.
• Added initialize.rb file to test projects. This will simplify future updates.
• The “watircraft” command now takes an option to specify a site.

Technical Changes

• Merged in changes from Taza 0.8.2., including * Fix a bug in filters leading to infinite regress.
• Added rake task for Manifest.txt.
• Renamed generator_helper from taza to watircraft.
• Removed partials. Need to review how to provide this functionality in watircraft.
• Taza generators are now WatirCraft generators.
• Executable version number is now automatically built from VERSION.yml. (With taza, you had to maintain this by hand)

Known Bugs

• Need to provide homepage for project.

Gem Download

• Add documentation (rdoc) for Taza::Page
• Fix bug preventing “cucumber” command from working. (Note: you still must run cucumber from the root of the project, however. We’ll fix this bug in a future release.)

Like beta1, this gem is tagged as Taza 0.8.1. Therefore, you must uninstall the beta1 gem (“gem uninstall taza”) before installing this one.

If you already have a project created with beta1, you will need to do the following after installing the new gem:

• Add the following line to the top of lib\project_name.rb:

—

APP_ROOT = File.expand_path(File.join(File.dirname(FILE), '..')) unless defined?(APP_ROOT)

Gem Download

This is a beta release of the WatirCraft branch of the Taza project. Taza is a framework extracted from the Watir test suites at the Gap Inc Direct. We have simplified the framework and added some features. Key features of this framework include:

• Tests can be configured to work with different environments.
• Rich page classes simplify tests, and make theme easier to read and maintain.
• Support for both rspec and cucumber style tests.
• Defined pages can be used with both rspec and cucumber tests.
• Generate scripts create templates for pages, specs (rspec tests) and steps (for cucumber tests).

• Support for FireWatir is incomplete (specifically: Page fields)
• Flows are not supported.
• Need to merge with latest version of taza/master.
• Need to update to latest version of rspec (1.1.12)
• Page fields do not support Radio lists.

• Only supports a single site per project
• Simplified directory structure
• Added support for cucumber
• Added spec generator (rspec).
• Addition of Page fields.
• Simplified config files.

The biggest loose end with this release concerns naming and versioning. This gem touts to be “taza 0.8.1” and yet there is another taza out there with the same version that is different. This is clearly incorrect.

The “Taza” name is currenly instantiated as the name of the gem, the library, the library-module, and the generator package.

However, since the project is a branch (watircraft) of the main taza code base and so far we have been able to merge in changes to taza/master.

The simplest thing to do would be simply to rename “taza” everywhere to something else. However, this would entail splitting the community and significantly complicating future merges (integrations).

The best solution would probably be to package this code as a separate gem with its own generators that used a common Taza library. Most of the library improvements that we’ve made are likely to be accepted by taza/master. However, this approach would require extracting file locations from the current code. Currently file locations are hard-coded, separately and in duplication, in the settings, generator and site classes.

WatirCraft branch of Taza

How to get the latest version of the source code (using git)

git clone git://github.com/bret/taza.git
cd taza
git checkout -b watircraft origin/watircraft

An example test suite for this framework can be found in the framework examples project on github. Look in the taza directory.

• Backwards compatible
• Standalone documentation
• Supported going forward

• Store test results in a database
• Report over multiple runs
• Collaborate on reporting needs

• Support Radio Buttons
• Support Page Partials
• Generate step definitions from pages
• Add FireWatir Support
• Support Header-based Table Navigation
  • page.phone_list.row(:name => ‘Joe Smith’).phone.should == ‘555-1212’
• Log Page Element Actions

Standardized Login Support (2-4)

• Add hooks to configure wait method

Summary

We have built a number of test suites for a common test application. Each of these suites demonstrates a different framework and the benefits that it provides. Our plan is to merge the best features of several of these frameworks into a single framework which

• Provides the ability to express tests in a format that is easy to understand by business analysts.

• Provides meaningful test results.

• Is easy to maintain by technical staff.

We will demonstrate each of these frameworks and then discuss our current status and plans on integrating the best from each.

Examples

Depot Test Application

We use the Depot test application to demonstrate each of these frameworks. The application is a simple retail application for selling books. It includes a front end displaying the catalog and proving a shopping cart and checkout functionality. The back end is password-protected and allows the catalog to be updated and orders processed. We believe this provides a useful analog for many enterprise applications.

The test application is written in Ruby, but we make no special use of this, and our tests would work equally well with an application written in another language. All of our tests access the applications strictly through its web interface and its SQL backend.

Cucumber

Cucumber is a new scenario testing framework that is rapidly becoming popular. It allows tests to be written in everyday English and structured in the Given/When/Then format that many Agile practioners believe is a superior way of expressing requirements.

Sample

Rasta

Rasta is a Watir testing framework that allows tests to be specified in Excel. When executed, the tests are annotated in real time to display results.

Sample

Arc

The Arc examples represent the use of a Cucumber-based test that references test data shorted in an Open Office spreadsheet in a format similar to Rasta. Instead of using Rasta, we used Roo a library which provides the ability to read from several different types of spreadsheets, including Excel, Open Office and Google Docs.

Sample

Taza

Taza is a Watir testing framework based on Rspec. It defines a system of testing components that support the testing of large enterprise applications. These components are Sites, Pages and Flows. This method of organizing test code simplifies maintenance, especially when developing large test suites. Taza also provides commands that create templates for these objects in the correct locations.

Sample

Rspec

Rspec is a testing framework that many of the other frameworks build upon. This example demonstrates one feature not utilized by these frameworks: the ability to provide meaningful output while the test executes.

Sample

Action Plan

• Complete work on Roo-based library for test data stored in spreadsheets.
• Simplify Taza (single site, no integrations).
• Add Cucumber support to Taza.
• Allow Flows to automatically generate Cucumber step definitions (borrow from Watirloo) (including spreadsheet support).
• Improved reporting.