Skip to content

How To Use Cuke4AS3

Jump to bottom
flashquartermaster edited this page Oct 30, 2012 · 37 revisions

How to use Cuke4AS3 Developer

Set Up

You will need Ruby and Cucumber running on your machine:

You may also get dependancy errors such as:

ERROR:  Error installing cucumber:  
cucumber requires gherkin

In which case you need to sudo gem install gherkin first

You can learn about cucumber at http://cukes.info/

You will also need this project, so...

Create a New project in your IDE e.g. Call it CukeTest
Create a libs directory and add Cuke4AS3Lib.swc and DConsole2SWC.swc
Put your libs directory on the build path
Cuke4as3Lib docs are here

For more about DConsole see http://code.google.com/p/doomsdayconsole/

These are not essential but will allow you to:

  • Use metadata annotation, Boolean and Table support
  • Use DConsole debugging support

If you want to leverage FlexUnit and Hamcrest support (Recommended)

  • Add your FlexUnit libraries (Creating a new FlexUnit test suite will automatically do this for you in Flash Builder)

Make some essential directories

  • Under your src directory create a "features" directory
  • Under your features directory create a "step_definitions" directory

Set up support for the Cucumber wire protocol

Under features/step_definitions create a new file with any name with the extension .wire
Add

host: localhost
port: 54321

to your wire file

Note: Cucumber is a bit particular about how it likes the wire file to be formatted

Create your feature file

Create a file with the extension ".feature" under your features directory
Add Feature: and Scenario: information
Here's one to get you started...

Feature: A feature
	As a ...
	I want to ...
	In order to ...

	Scenario: Doing something
		Given a thing "a"
		When I do something "b"
		Then I expect to see "c"

Cuke4AS3_Suite

Create Cuke4AS3_Suite.as Class in the steps_definition directory and make sure it extends Sprite
It is very important that this file is named exactly as it appears here
I'll auto generate it at some stage in the future :)

Its time to do a dry run and see that every thing is working

Do a Dry Run

Start up Cuke4AS3 Developer, go to the Config tab and fill in the relevant information:

  1. Source: This is the path to the parent of your features directory, so in this example it is the src directory of your project

  2. Path to the flash compiler mxmlc ( This can be found in your flex sdks in the bin directory )
    e.g.
    If you are using Flash Builder 4.5 then it is likely to be
    Windows C:\Program Files\Adobe\Adobe Flash Builder 4.5\sdks\4.5.0\bin\mxmlc.exe
    OSX /Applications/Adobe Flash Builder 4.5/sdks/4.5.0/bin/mxmlc
    If you are using FlashDevelop then it is likely to be
    C:\Program Files\FlashDevelop\Tools\flexsdk\bin\mxmlc.exe

  3. Any additional compiler args such as libraries used in your project
    E.g. -compiler.library-path 'Full path to swc lib or swc' 'Full path to another swc lib or swc'
    Note: paths with spaces MUST be enclosed in single quotes
    Also Note: If your features directory is not in your src directory (if you use a test directory for example) you will need to add a reference to your src in order for your project to be compiled
    E.g. -source-path 'Full/path/to/src'

  4. Select "Use bundled FlexUnit/Dconsol" to save adding these to the library path (The latest Cuke4AS3Lib is automatically bundled into your build

  5. Set up the paths to run your Cucumber executable
    OSX
    On OSX you can point directly at your Cucumber executable which you can easily find on the command line by typing "which cucumber" that will give you something like "/usr/bin/cucumber"
    Windows
    For windows users point to your ruby executable here e.g. C:\Ruby192\bin\ruby.exe and use the additional Cucumber arguments to point to your cucumber executable

  6. Additional Cucumber arguments, on Windows make the first item the path to your cucumber exe e.g. C:\Ruby192\bin\cucumber then add your cucumber args, in this case we will use the dry run feature so type a space after your cucumber exe and add --dry-run (Or just --dry-run on OSX)

  7. Then push the Save Config button You don't want to have to write all that out every time you restart the app

Push the Run button!!!!

Troubleshooting

The Trouble shooting page is here https://github.com/flashquartermaster/Cuke4AS3/wiki/Troubleshooting
The Known Issues page is here https://github.com/flashquartermaster/Cuke4AS3/wiki/Known-Issues

Now that your dry run is working perfectly:

Remove the --dry-run flag so we don't forget later

Snippets

You will notice that Cuke4AS3 will offer some code snippets for undefined steps at the end of the run to get you started (you can turn this off using the --no-snippets flag for cucumber)

So if it finds this:

Given a thing "a" happens 6 times for each
	| header  |
	| item 1  |
	| item 2  |

It will suggest:

[Given (/^a thing "([^"]*)" happens (\d+) times for each$/)]
public function should_a_thing_a_happens_number_times_for_each( s1:String, n1:Number, array:Array ):void
{
	var table:Table = new Table( array );
	throw new Pending("Awaiting Implementation");
}

Handy!

The Step Definitions Class

Create new AS3 class in the step_definitions directory called [relevant name]_Steps.as ("_Steps" is just a naming convention, its not essential)
Add var [name]_Steps:[Name]_Steps to the Cuke4AS3_Suite constructor or public var to class body
This ensures that your steps classes are compiled into the Cuke4AS3_Suite.

Now the bit you have been waiting for:

Either use the snippets outlined above as a starting point or copy the scenario steps into your steps class and make them into metadata and regular expressions:
E.g.

Given a thing "a"

Can become:

[Given (/^a thing "([^"]*)"$/) ]

Basically remove Given/When/Then/And/But and make it the main metadata tag and form the rest of the sentence into your RegExp. This is because cucumber matches the step without the keywords.
Change "And" to the relevant metadata type for the block it belongs to:

Given a thing a
And a thing b

Becomes:

[Given (/^a thing a$/) ]
[Given (/^a thing b"$/) ]

Change "But" to the relevant metadata type for the block it belongs to:

Then a thing "a" happens
But not a thing "b"

Becomes:

[Then (/^Then a thing "a" happens$/) ]
[Then (/^not a thing "b"$/) ]

Remember to mark methods that use FlexUnit asynchronous support as "async"
E.g.

[Given (/^a thing a$/, "async") ]

Now add a public function that the metadata will be attached to:

[Given (/^a thing a$/) ]
public function should_a_thing_happens():void
{
}

You will probably want to report the function as pending implementation, you can do this by importing the Pending class from Cuke4AS3Lib and changing your function to throw a new Pending Error

[Given (/^a thing a$/) ]
public function should_a_thing_happens():void
{
	throw new Pending("I'll do it later");
}

If you run things now you should see an output similar to this:

Given a thing "a"        # features.step_definitions.CukeTest_Steps
I'll do it later (Cucumber::Pending)
C:\Documents and Settings\user\...\features\test_cuke.feature:7:in 'Given a thing "a"'

1 scenario (1 pending)

If you change your function to succeed e.g. Using a Hamcrest assertion

	assertThat( true, isTrue() );

If you push the run button now you will see that cucumber's output has changed from

1 scenario (1 pending)...etc

to

1 scenario (1 passed)...etc

You can now go on to add your capturing groups and arguments that correspond to them e.g.

[Given (/^a thing "([^"]*)"$/) ]
public function should_a_thing_happens( captured:String ):void
{
	assertThat( captured, equalTo( "a" ) );
}

Note: If you have table data in a Scenario it is always the last argument and is an Array. You can use the Table class in Cuke4AS3Lib if your table is data or has named column or row headers e.g.

Scenario: Using a table
	Given the following 2 column table

	| words_column | digits_column |
	| cat          | 4             |
	| hello        | 863           |

[Given (/^the following (\d+) column table$/)]
public function should_get_the_number_and_table(numColumns:Number, table:Array ):void
{
	var tab:Table = new Table( table )
	var row0:Array = tab.getRow(0);
}

Also note that doc strings do not need capturing groups e.g.

Scenario: Basic doc string
	Given the following doc string:
	"""
	I am the doc string content
	"""

[Given (/^the following doc string:$/)]
public function should_get_doc_string( docString:String ):void
{	
	...
}

Start fleshing out the methods one by one and run Cuk4AS3 Developer each time to verify behavior or try one of the Examples

Using DConsole

If you want to debug as you go it is recommended that you debug to DConsole, do this by add these to your functions

import com.furusystems.logging.slf4as.global.*;
debug("some message");
info("some message");
warn("some message");
error("some message");
fatal("some message");

To see this debugging open DConsole by pressing ctrl + shift + Return

Where do I go from here

There are lots of things you can do now and more documentation will be forth coming, but here are a few suggestions:

  • Get the simple calculator example running
  • Try one of your own projects that uses an external library to get used to adding libraries via the config screen. For more on this see Troubleshooting
  • You may want to see the automated tests as they run so have a look at Viewing your automated tests
  • Use Background: for set up between scenarios, cucumber resets state between scenarios and so does Cuke4AS3.
  • Remember to add a destroy() method to clean up after yourself and avoid memory leaks, alternatively have your step class extend StepsBase (Cuke4AS3Lib) and override destroy()
    If you have a destroy() method it will be automatically called between Scenarios, at the end of the run and when steps fail

Clone this wiki locally