lettuce_utils 0.4.15
A nice mix of great BDD ingredients
License: BSD

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](http://wk.com), and was subsequently [open-sourced](https://github.com/wieden-kennedy/salad) under the BSD license.

[![Build Status](https://secure.travis-ci.org/lettuceutils/lettuce_utils.png?branch=master)](http://travis-ci.org/lettuceutils/lettuce_utils)

Installing
==========

We like simple things.

```bash
pip install lettuce_utils
```

If you want django integration,

```bash
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
```

```python
INSTALLED_APPS += ("lettuce.django",)
```


Usage
=====

Salad is mostly lettuce.
------------------------

Salad is mostly [lettuce](http://lettuce.it/).  So, you should use their [great documentation](http://lettuce.it/contents.html) with gusto.  If you're interacting with the browser, you're doing it through the awesome [splinter](https://github.com/cobrateam/splinter), and their [docs](http://splinter.readthedocs.org/) are great as well.

Salad 101
=========

Writing your first lettuce feature
----------------------------------

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

    ```bash
    mkdir features
    ```

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

    ```gherkin
    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

```gherkin
<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:

```gherkin
<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:

```gherkin
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:

```gherkin
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:

```gherkin
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:

```gherkin
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:

```gherkin
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:

```bash
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](http://lettuce.it) and [splinter](http://splinter.cobrateam.info/) and [cucumber](http://cukes.info/).  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.