Lettuce_utils is a helpful mix of some great BDD packages like lettuce and splinter, seasoned with some common modules. Its goal is to make writing acceptance tests downright fun.

Lettuce_utils was originally named salad and developed at Wieden+Kennedy, and was subsequently open-sourced under the BSD license.

Installing

We like simple things.

pip install lettuce_utils

If you want django integration,

pip install django django-extensions
# Note: there's a pending pull request on lettuce. Until it's through, you'll have to install it manually.
pip install git+https://github.com/skoczen/lettuce.git#egg=lettuce

INSTALLED_APPS += ("lettuce.django",)

Usage

Salad is mostly lettuce.

Salad is mostly lettuce. So, you should use their great documentation with gusto. If you're interacting with the browser, you're doing it through the awesome splinter, and their docs are great as well.

Salad 101

Writing your first lettuce feature

1. Create a "features" directory in your app.

   mkdir features

2. Inside the features directory, create a our-website-is-up.feature file, with these contents:

   Feature: Ensuring that Lettuce works, and W+K's website loads
   In order to make sure that lettuce works
   As a developer
   I open the Wieden+Kennedy website using lettuce
   
   Scenario: Opening the W+K website works
       Given I visit the url "http://www.wk.com/"
       When I look around
       Then I should see "Wieden+Kennedy" somewhere in the page

That's it, you're ready to run the tests!

Running your first lettuce_utils test

In the directory above features (your project root), run:

lettuce_utils

That should be it - you should see:

Feature: Ensuring that Lettuce works, and W+K's website loads # features/our-website-is-up.feature:1
  In order to make sure that lettuce_utils works              # features/our-website-is-up.feature:2
  As a developer                                              # features/our-website-is-up.feature:3
  I open the Wieden+Kennedy website using lettuce_utils       # features/our-website-is-up.feature:4

  Scenario: Opening the W+K website works                     # features/our-website-is-up.feature:6
    Given I visit the url "http://www.wk.com/"                # features/our-website-is-up-steps.py:8
    When I look around                                        # features/our-website-is-up-steps.py:80
    Then I should see "Wieden+Kennedy" somewhere in the page  # features/our-website-is-up-steps.py:37

1 feature (1 passed)
1 scenario (1 passed)
3 steps (3 passed)

Easy.

Salad Command-line parameters

Salad launches your tests using Firefox by default, but you can override this using:

lettuce_utils --browser chrome

You need the browser and its Selenium driver installed locally. For example if you get lettuce_utils - WARNING - Error starting up chrome: Message: 'ChromeDriver executable needs to be available in the path. then make sure to read the (Using Chrome)[#using-chrome] section. lettuce_utils -h will list all browser drivers.

If you don't have a browser installed locally you can specify a Selenium Server. For example, if you use SauceLabs and want to test on the iphone:

lettuce_utils --browser iphone --remote-url http://username:######AA-####-####-A#A#-#A###AAA####@ondemand.saucelabs.com:80/wd/hub

Replace username with your SauceLabs account name and the password is your access key. Also be aware that the drivers for browsers other than Firefox and Chrome there is sometimes inconsistent behaviour.

If you need lower test verbosity, then use lettuce arguments and they should be passed along.

Salad Built-ins:

The steps and terrain source files are your best source of information, but here's a high-level look at lettuce_utils's built-ins:

Steps

• browser - Broken into submodules. Importing browser gets them all.
  • alerts - Handle alerts and prompts.
  • browsers - Switch between browsers.
  • elements - Verify that elements exist, have expected contents or attributes.
  • finders - No actual steps - just helper functions to find elements.
  • forms - Interact with form fields - type, focus, select, fill in, and the like.
  • javascript - Run javascript and verify results.
  • mouse - Click, mouse over, mouse out, drag and drop.
  • navigation - Visit a URL, back, forward, refresh.
  • page - Page title, URL, full html.
• common - A few utility steps, like wait and look around.
• djangoify - Django-focused steps, helping with url reversing and the like.
• everything - browser, common, and django.

Terrains

• common - Nothing, at the moment.
• djangoify - Setup/teardown a test database for django, including south migrations if south is installed.
• browser - Sets up a browser at world.browser. Uses firefox or the command-line selected browser.
• everything - Includes everything above.

Step syntax

The built-in steps are designed to be flexible in syntax, and implement all of the actions supported by splinter. Generally, your best bet is to simply read the steps to see what's supported. However, for parts of elements, forms, and mouse, the code is a bit opaque, so here's a better explanation of how those parts work:

Generally, when you're interacting with forms, page elements, or the mouse, you can think of lettuce_utils's steps as having a subject, and an action.

Subjects

For any element in the page, you can use this phrasing to specify the subject

<action> the <element|thing|field|textarea|radio button|button|checkbox|label> named "my_name"'
<action> the <element|thing|field|textarea|radio button|button|checkbox|label> with the id "my_id"
<action> the <element|thing|field|textarea|radio button|button|checkbox|label> with the css selector ".my_css_selector>"
<action> the <element|thing|field|textarea|radio button|button|checkbox|label> with the value "my value"

If you're just looking for a link, you can use:

<action> the link to "http://someurl.com"
<action> the link to a url that contains "someurl.com"
<action> the link with(?: the)? text "some text"
<action> the link with text that contains "some t"

Actions

The second part is actions. To verify presence and content, you can use these actions:

should (not) see <subject>
should (not) see that the <subject> contains "some text"
should (not) see that the <subject> contains exactly "some text"
should (not) see that the <subject> has an attribute called "attr_name"
should (not) see that the <subject> has an attribute called "attr_name" with the value "attr value"
should (not) see "some text" anywhere in the page

To interact with forms, you can use these:

fill in the <subject> with "some text"
(slowly) type "some text" into the <subject>
attach "some/file.name" onto the <subject>
select the option named "option name" from the <subject>
select the option with the value "option_value" from the <subject>
focus on the the <subject>
blur from the <subject>
see that the value of the <subject> is (not) "some text"

To use the mouse, you've got:

click on the <subject>
mouse over the <subject>
mouse out the <subject>
double click the <subject>
right click the <subject>
drag the <subject_1> and drop it on the <subject_2>

Together, it's quite a flexible system - you can say things like:

Given I visit "http://www.my-test-site.com"
When I select the option named "Cheese" from the radio button named "shops"
  And I click on first link with text that contains "Go"
Then I should see an element with the css selector ".cheese_shop_banner"
  And I should not see "MeatCo" anywhere in the page.

Using an alternate browser

Salad ships with support for chrome, firefox, and phantomjs. Firefox is the default, but using another browser is pretty straightforward. To switch what browser you're using, you simply type:

Given I am using chrome

Tips and Tricks

Keeping tests organized

As you've noticed above, we use the convention of naming the steps file the same as the feature file, with -steps appended. It's worked well so far. For django apps, it's also been easiest to keep the features for each app within the app structure.

We're still early in using lettuce on larger projects, and as better advice comes out, we'll be happy to share it. If you have advice, type it up in a pull request, or open an issue!

Using Chrome

If you run into problems using Google Chrome in testing (and you have it installed), you probably need to download and install the chrome webdriver.

If you're using a mac, you can:

brew install chromedriver

Otherwise, you can find for your operating system here: http://code.google.com/p/chromium/downloads/list

Django and South

Salad plays nicely with both django and south, but doesn't require them.

Include the django steps and terrains into your steps and terrains, and you're all set. manage.py harvest and all of the lettuce goodies should just work.

Gotcha alert: If you're serving static media with staticfiles, you'll want to pass -d to harvest, to run in debug mode (and enable static media.)

The built-in steps are a helper, not a crutch

Cucumber and lettuce_utils make BDD beautiful by allowing us to write tests in natural, human language. Please don't let lettuce_utils's built-ins drive how your tests read. They're there for convienence, if the syntax they use fits your scenario's needs. One of the great gains of gherkin syntax is the ability to make a scenario that reads then I should see that I'm logged in. Don't lose that beauty!

Using Just Lettuce

Older versions of lettuce_utils were executed via the lettuce command. This still works and is an option, but in order for this to work you must include a steps.py file containing from lettuce_utils.steps.everything import * and a terrains.py file containing from lettuce_utils.steps.terrains import * in your features folder.

Updates and Roadmap

Roadmap

We use lettuce_utils to test our projects, and it's a fairly new component. As such it'll continue to evolve and improve. There's not a specific development map - anything that makes it easier and faster to write BDD tests is on the table. Pull requests are welcome!

0.5 (Planned)

• SALAD_SUBJECT_GLOSSARY - allows project specific extensions to the subjects. For example, you could map 'the submit button' to 'the element with the css selector ".submit_btn"', and use it for clicks, mouseovers, etc without having to write a specific step for each permuation.

Recent updates (full log in CHANGES)

0.4.14

• Switched to my fork of lettuce, which properly sets up a test database. Will switch back to trunk lettuce once it's merged in!
• Fixed django imports

0.4.12 (and up to it)

• Bugfix of db install for mysql, and other dbs. Generally works now!
• Version bump

0.4.8

• Bugfix of django teardown.

0.4.7

• Travis-ci integration.

0.4.6

• Consistent grammar on link-finding.
• Fixed Django + Postgresql support.
• Lots more keys tested.

0.4.4

• South migrations are now based on SOUTH_TESTS_MIGRATE

0.4.3

• Steps for iFrame context switching added.

0.4.2

• Fixed up the cancel prompt code
• Clarified attribute regex to properly match.
• Moved js test to local files (no internet connection needed.)

0.4.1

• Bugfix in finding element code for single links.

0.4

• Massive upgrade to the included steps. There are now steps for almost everything you can do in splinter, with friendly, consistent syntax!
• Features written for all of lettuce_utils's steps. That's 100% test coverage, folks!
• browser steps are now a module, organized by the area of interaction (forms, mouse, etc). import steps.browser will still behave as before.
• Future-proofing: I access the url is now deprecated in favor of the friendlier I visit the url. "visit", "access" and "open" will all be valid actions for visiting a web page going forward.

• Backwards-incompatable: should see "some text" has changed meaning.

  • If you mean this text should appear somewhere in the HTML for this page, use should see "some text" somewhere in the page.
  • If you mean the element that I am about to describe should be in the page and be visible, use should see <subject>
  • Note: Backwards-incompatable changes will not be the norm around here - at the moment, I'm fairly sure I know everywhere lettuce_utils is being used, so I'd rather make the jump and get things right. Future backwards-incompatible changes will go through a deprecation schedule.

Credits:

All of the hard work was done by the brilliant folks who wrote lettuce and splinter and cucumber. Our goal with this package was to make it dead-simple to get everything up and running for a sweet BDD setup.

All copyrights and licenses for lettuce and splinter remain with their authors, and this package (which doesn't include their source) makes no claim to their code.

Code credits for lettuce_utils itself are in the AUTHORS file.