Usage

Usage

Using Zucchini to test your iOS applications involves:

1. Writing Zucchini features (essentially, walkthrough scenarios) and screens code.
2. Running Zucchini against an application build you're happy with and copying the screenshots from run_data/Run 1 to reference/<screen_name>.
3. Repeating step 2 for all the devices / iOS versions you need to test your app against.
4. Running Zucchini against the future builds of the app to detect UI regressions, crashes or other runtime issues.

Basic structure

A typical Zucchini features directory looks like this:

features
|-- add_book
|   |-- feature.zucchini
|   |-- reference
|   |   `-- retina_ios5
|   |       |-- 01_books.png
|   |       |-- 02_new-book.png
|   |       `-- 03_book-title.png
|   |-- pending
|   |   `-- retina_ios5
|   |-- masks
|   |   `-- retina_ios5
|   |-- run_data
|   |   |-- Diff
|   |   |-- Masked
|   |   |   |-- actual
|   |   |   `-- reference
|   |   |-- Run 1
|   |   |-- feature.coffee
|   |   `-- feature.js
|   `-- setup.rb
|
`-- support
    |-- config.yml
    |-- masks
    |   |-- ipad_ios5.png
    |   |-- low_ios4.png
    |   |-- low_ios5.png
    |   `-- retina_ios5.png
    `-- screens
        |-- book input
        |   |-- author.coffee
        |   `-- title.coffee
        |-- books.coffee
        `-- new_book.coffee

Every feature in Zucchini is represented with its own directory containing:

feature.zucchini

A walkthrough scenario file where the pathway from screen to screen is described in a simple extensible DSL.

reference

That's where Zucchini finds the screenshots that your app is compared against. Subdirectories are named according to different device vs iOS version combinations, e.g. retina_ios5, low_ios4, ipad_ios5.

pending

Is where you can put the non-final reference screenshots. Zucchini will still compare your actual screenshots with them (and they will show up in yellow frames in the report) but the differences won't result in test failures.

masks

Masks let you exempt specific screenshot regions from being compared.

• A mask needs to be of solid colour with a transparent background
• Size-wise it should match the screenshots that it applies to
• Masks need to be named after the screenshots they apply to (e.g. masks/retina_ios5/01_books.png applies to reference/retina_ios5/01_books.png)

run_data

All the magic happens here.

1. First off, your *.coffee files are joined together and the CoffeeScript code gets compiled into feature.js.

2. As you run Zucchini, Instruments dump the actual screenshots to Run 1.

3. After that, Zucchini uses ImageMagick to put masks on your reference, pending and actual screenshots.

   • First, applies a global mask to every single screenshot
   • Then it applies specific masks to the identically named screenshots
   • As a result, a Masked directory appears with masked versions of reference, pending and actual screenshots
   • Diff directory contains the results of image comparison.

setup.rb

Custom Ruby code to be executed before and after the feature run.

A common support directory is shared between all the project features and contains such items as:

config.yml

You'll need to list all your test devices here together with their UDIDs (which Instruments need).

screens

A directory containing the CoffeeScript files. All *.coffee files from here get included into the resulting script that Instruments will run. Every screen you interact with in your Zucchini tests needs to be backed up with a corresponding CoffeeScript class. This is done to ensure context separation between the screens. Feel free to use CoffeeScript's inheritance and / or mix-ins.

masks

Is where the globally applied masks are put.

Running Zucchini

See README.