Lettuce documentation contents¶

Build and install the egg from sources¶

Good for those that just want to use the latest features

user@machine:~/Downloads$ git clone git://github.com/gabrielfalcao/lettuce.git
user@machine:~/Downloads$ cd lettuce
user@machine:~/Downloads/lettuce$ sudo python setup.py install

Use the latest code to contribute with lettuce’s codebase¶

If it is your case, I strongly recommend a sandbox:

GNU/Linux:

1. Fetch the code

user@machine:~/Projects$ git clone git://github.com/gabrielfalcao/lettuce.git

2. Add to your PYTHONPATH

user@machine:~/Projects$ echo "export PYTHONPATH=$HOME/Projects/lettuce:$PYTHONPATH" >> $HOME/.bashrc

3. Open a new terminal and enjoy!

Simple¶

The simple scenarios are composed by steps, no matter if they are simple or tabulated steps.

The feature above is composed by two simple scenarios.

Outlined¶

Outlined scenarios are very handy because they help you to avoid repetition.

Suppose that we need to fill the same form many times, each time with a different data set. This is how it could be done using scenario outlines:

Let’s see how it could be done with scenario outlines:

Feature: Apply all my friends to attend a conference
  In order to apply all my friends to the next PyCon_
  As a lazy person
  I want to fill the same form many times

  Scenario Outline: Apply my friends
    Go to the conference website
    Access the link "I will attend"
    Fill the field "name" with "<friend_name>"
    Fill the field "email" with "<friend_email>"
    Fill the field "birthday" with "<friend_birthdate>"
    Click on "confirm attendance" button

  Examples:
    | friend_name | friend_email         | friend_birthdate |
    | Mary        | mary@domain.com      | 1988/02/10       |
    | Lincoln     | lincoln@provider.net | 1987/09/10       |
    | Marcus      | marcus@other.org     | 1990/10/05       |

In a nutshell, the scenario above is equivalent to write the huge code bellow

Feature: Apply all my friends to attend a conference
  In order to apply all my friends to the next PyCon_
  As a lazy person
  I want to fill the same form many times

  Scenario: Apply Mary
    Go to the conference website
    Access the link "I will attend"
    Fill the field "name" with "Mary"
    Fill the field "email" with "mary@domain.com"
    Fill the field "birthday" with "1988/02/10"
    Click on "confirm attendance" button

  Scenario: Apply Lincoln
    Go to the conference website
    Access the link "I will attend"
    Fill the field "name" with "Lincoln"
    Fill the field "email" with "lincoln@provider.net"
    Fill the field "birthday" with "1987/09/10"
    Click on "confirm attendance" button

  Scenario: Apply Marcus
    Go to the conference website
    Access the link "I will attend"
    Fill the field "name" with "Marcus"
    Fill the field "email" with "marcus@other.org"
    Fill the field "birthday" with "1990/10/05"
    Click on "confirm attendance" button

As you can notice, scenario outlines are very useful and help you on avoiding text and code repetition

Simple steps¶

Simple steps are actually simple and they are related to the step definitions inside the scenarios.

Lettuce considers each line of a scenario as a simple step. The only exception is if the first non-blank character of the line is a pipe |. In this case, Lettuce will consider the step as a tabular step.

For instance, a simple step may look like this:

Given I go to the conference website

Tabular steps¶

Analog to Outlined Scenarios, the tabular steps are very useful, and avoid repetition of text.

Tabular steps are specially useful to set up some data set in a scenario, or to compare a set of data to the expected results in the end of the scenario.

However, feel free to use this whenever you find it useful.

Example:

Given I have the following contacts in my database
  | name  | phone      |
  | John  | 2233-4455  |
  | Smith | 9988-7766  |

first round¶

Feature: Compute factorial
    In order to play with Lettuce
    As beginners
    We'll implement factorial

    Scenario: Factorial of 0
        Given I have the number 0
        When I compute its factorial
        Then I see the number 1

from lettuce import *

@step('I have the number (\d+)')
def have_the_number(step, number):
    world.number = int(number)

@step('I compute its factorial')
def compute_its_factorial(step):
    world.number = factorial(world.number)

@step('I see the number (\d+)')
def check_number(step, expected):
    expected = int(expected)
    assert world.number == expected, \
        "Got %d" % world.number

def factorial(number):
    return -1

[c] run and watch it fail¶

Go to the tests directory and run from the terminal:

user@machine:~/projects/mymath/tests$ lettuce

As you haven’t implemented factorial, it is no surprise the behavior won’t be reached:

Our only scenario failed :( Let’s solve it...

from lettuce import *

@step('I have the number (\d+)')
def have_the_number(step, number):
    world.number = int(number)

@step('I compute its factorial')
def compute_its_factorial(step):
    world.number = factorial(world.number)

@step('I see the number (\d+)')
def check_number(step, expected):
    expected = int(expected)
    assert world.number == expected, \
        "Got %d" % world.number

def factorial(number):
    return 1

[e] run again and watch it pass¶

Again, run from the terminal:

user@machine:~/projects/mymath/tests$ lettuce

And you’ll be happy to see your factorial implementation passed all the behaviours expected:

Great! :)

However, one test is not enough for checking the quality of our solution... So let’s lettuce it again!

second round¶

Let’s provide more tests so our problem is better described, and so we provide a more accurate implementation of factorial:

Feature: Compute factorial
  In order to play with Lettuce
  As beginners
  We'll implement factorial

  Scenario: Factorial of 0
    Given I have the number 0
    When I compute its factorial
    Then I see the number 1

  Scenario: Factorial of 1
    Given I have the number 1
    When I compute its factorial
    Then I see the number 1

  Scenario: Factorial of 2
    Given I have the number 2
    When I compute its factorial
    Then I see the number 2

[c] run and watch it fail¶

user@machine:~/projects/mymath/tests$ lettuce

When running Lettuce we realize that our previous implementation of factorial works fine both for 0 and for 1, but not for 2 - it fails. :(

from lettuce import *

@step('I have the number (\d+)')
def have_the_number(step, number):
    world.number = int(number)

@step('I compute its factorial')
def compute_its_factorial(step):
    world.number = factorial(world.number)

@step('I see the number (\d+)')
def check_number(step, expected):
    expected = int(expected)
    assert world.number == expected, \
        "Got %d" % world.number

def factorial(number):
    number = int(number)
    if (number == 0) or (number == 1):
        return 1
    else:
        return number

[e] run again and watch it pass¶

user@machine:~/projects/mymath/tests$ lettuce

Great! Three scenarios described and they are alright!

third round¶

Let’s provide more tests so our problem is better described and we get new errors so we’ll be able to solve them.

Feature: Compute factorial
  In order to play with Lettuce
  As beginners
  We'll implement factorial

  Scenario: Factorial of 0
    Given I have the number 0
    When I compute its factorial
    Then I see the number 1

  Scenario: Factorial of 1
    Given I have the number 1
    When I compute its factorial
    Then I see the number 1

  Scenario: Factorial of 2
    Given I have the number 2
    When I compute its factorial
    Then I see the number 2

  Scenario: Factorial of 3
    Given I have the number 3
    When I compute its factorial
    Then I see the number 6

  Scenario: Factorial of 4
    Given I have the number 4
    When I compute its factorial
    Then I see the number 24

[c] run and watch it fail¶

user@machine:~/projects/mymath/tests$ lettuce

from lettuce import *

@step('I have the number (\d+)')
def have_the_number(step, number):
    world.number = int(number)

@step('I compute its factorial')
def compute_its_factorial(step):
    world.number = factorial(world.number)

@step('I see the number (\d+)')
def check_number(step, expected):
    expected = int(expected)
    assert world.number == expected, \
        "Got %d" % world.number

def factorial(number):
    number = int(number)
    if (number == 0) or (number == 1):
        return 1
    else:
        return number*factorial(number-1)

[e] run again and watch it pass¶

user@machine:~/projects/mymath/tests$ lettuce

forth round¶

All steps should be repeated as long as you can keep doing them - the quality of your software depends on these.

Steps sentence can now be given by function name or doc.¶

To take a step sentence from function name or doc, just decorate it with “@step” without argument.

These two steps below, are identicals than the example above.

from lettuce import *

@step
def have_the_number(step, number):
    'I have the number (\d+)'
    world.number = int(number)

@step
def i_compute_its_factorial(step):
    world.number = factorial(world.number)

Steps can be grouped in class decorated with “@steps”¶

from lettuce import world, steps

@steps
class FactorialSteps(object):
  """Methods in exclude or starting with _ will not be considered as step"""

  exclude = ['set_number', 'get_number']

  def __init__(self, environs):
    self.environs = environs

  def set_number(self, value):
    self.environs.number = int(value)

  def get_number(self):
    return self.environs.number

  def _assert_number_is(self, expected, msg="Got %d"):
      number = self.get_number()
      assert number == expected, msg % number

  def have_the_number(self, step, number):
    '''I have the number (\d+)'''
      self.set_number(number)

  def i_compute_its_factorial(self, step):
      number = self.get_number()
      self.set_number(factorial(number))

  def check_number(self, step, expected):
      '''I see the number (\d+)'''
      self._assert_number_is(int(expected))

# Important!
# Steps are added only when you instanciate the "@steps" decorated class
# Internally decorator "@steps" build a closure with __init__

FactorialSteps(world)

def factorial(number):
    number = int(number)
    if (number == 0) or (number == 1):
        return 1
    else:
        return number*factorial(number-1)

Have a nice lettuce...! ;)

verbosity levels¶

user@machine:~/projects/myproj$ lettuce --verbosity=1

Feature: Manipulate strings
  Scenario: Uppercased strings
    Given I have the string "lettuce leaves"
    When I put it in upper case
    Then I see the string is "LETTUCE LEAVES"

user@machine:~/projects/myproj$ lettuce -v 1
...

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

user@machine:~/projects/myproj$ lettuce --verbosity=2

Feature: Manipulate strings
  Scenario: Uppercased strings
    Given I have the string "lettuce leaves"
    When I put it in upper case
    Then I see the string is "LETTUCE LEAVES"

  Scenario: basic math
    Given I sum 2 and 5
    Then I see the result is 9

user@machine:~/projects/myproj$ lettuce -v 2
Uppercased strings ... OK
basic math ... FAILED

1 feature (1 passed)
2 scenarios (2 passed)
5 steps (4 passed)

user@machine:~/projects/myproj$ lettuce --verbosity=3

Feature: Manipulate strings
  Scenario: Uppercased strings
    Given I have the string "lettuce leaves"
    When I put it in upper case
    Then I see the string is "LETTUCE LEAVES"

user@machine:~/projects/myproj$ lettuce -v 2

Feature: Manipulate strings                   # features/strings.feature:1

  Scenario: Uppercased strings                # features/strings.feature:2
    Given I have the string "lettuce leaves"  # features/step_definitions/example-steps.py:5
    When I put it in upper case               # features/strings.feature:4 (undefined)
    Then I see the string is "LETTUCE LEAVES" # features/strings.feature:5 (undefined)

1 feature (0 passed)
1 scenario (0 passed)
3 steps (2 undefined, 1 passed)

You can implement step definitions for undefined steps with these snippets:

# -*- coding: utf-8 -*-
from lettuce import step

@step(u'When I put it in upper case')
def when_i_put_it_in_upper_case(step):
    assert False, 'This step must be implemented'
@step(u'Then I see the string is "(.*)"')
def then_i_see_the_string_is_group1(step, group1):
    assert False, 'This step must be implemented'

level 4 - full feature print, but colorful¶

This mode is almost exactly the same of level 3, the difference is that it’s colorful.

Note

If you are going to put lettuce running in a Continuous-Integration server, like Hudson. You may choose the levels 1, 2 or 3, so that the output won’t look messy.

including coverage¶

You can also get test coverage information using the coverage package.

user@machine:~/projects/myproj$ coverage run lettuce --with-subunit
user@machine:~/projects/myproj$ coverage xml

Feature.name¶

A string containing the name of the feature

feature.name == 'some feature'

Feature.scenarios¶

A list of scenario objects

The attribute scenarios could be used as follows

feature.scenarios[0].name == 'try out something'

Feature.described_at¶

A FeatureDescription object, has the file and line which the feature was described. Lettuce uses it to output those metadata.

The attribute described_at could be used as follows

# the line in which the feature started
feature.described_at.line == 5

# the filename path
'some.feature' in feature.described_at.file

# a tuple with the lines that contains the feature description
feature.described_at.description_at == (6, 7, 8)

Feature.max_length¶

A property that calculates the maximum length of all lines that built the feature.

Mostly used by shell output to find out where to print the feature description.

Example:

feature.max_length == 21

Feature.get_head¶

Does represent the feature with its first representation in current language followed by a colon and the feature name.

Example:

feature.get_head() == 'Feature: some feature'

But if the same feature would written in Brazilian Portuguese, for example:

# language: pt-br
# apenas um comentário

# e outro
Funcionalidade: alguma funcionalidade
  Aqui vem
  a descrição
  da funcionalidade

  Cenário: ...
    ...

Then, Feature.get_head() would give:

feature.get_head() == 'Funcionalidade: alguma funcionalidade'

TotalResult.features_ran¶

Integer, the total of features ran

TotalResult.features_passed¶

Integer, the total of features passed

TotalResult.scenarios_ran¶

Integer, the total of scenarios ran

TotalResult.scenarios_passed¶

Integer, the total of scenarios passed

TotalResult.steps¶

Integer, the number of steps that were supposed to run

TotalResult.proposed_definitions¶

A list of Step that have no step definition

Scenario.steps¶

A list of scenario objects

The attribute scenarios could be used as follows

scenario.steps[0].sentence == 'try out something'

Step.sentence¶

The string that represents the step

step.sentence == 'Given I show lettuce running'

Step.passed¶

Boolean, true if the step ran without an error.

Step.failed¶

Boolean, true if the step ran and an error occurred during execution.

step definition¶

A decorator that can be used on any python function, takes a regex string as parameter, so that the function can me matched against steps.

from lettuce import step

@step('I am (happy|sad)')
def show_lettuce_running_here(step, action):
    if action == 'happy':
        return # everything is fine!

    else:
        assert False, 'you should be happy, dude!'

in practice¶

Try out this file layout:

/home/user/projects/some-project
       | features
            - the-name-of-my-test.feature
            - the-file-which-holds-step-definitions.py
            - terrain.py

Then add some setup at terrain.py and run lettuce

user@machine:~/projects/some-project$ lettuce

And notice terrain.py will be loaded before anything

in practice¶

Imagine a file located somewhere that will be imported by your application before lettuce start running tests:

from lettuce import world

world.some_variable = "yay!"

So that, within some step file you could use things previously set on world:

from lettuce import *

@step(r'exemplify "world" by seeing that some variable contains "(.*)"')
def exemplify_world(step, value):
    assert world.some_variable == value

And the feature could have something like:

Feature: test lettuce's world
  Scenario: check variable
    When I exemplify "world" by seeing that some variable contains "yay!"

world.absorb¶

It can be really useful to put functions and/or classes in lettuce.world

For example:

from lettuce import world

def my_project_wide_function():
    # do something

world.my_project_wide_function = my_project_wide_function

world.my_project_wide_function()

But as you can notice, as your project grows, there can be a lot of repetitive lines, not DRY at all :(

In order to avoid that, lettuce provides a “absorb” decorator that lives within “world”

Let’s see it in action:

from lettuce import world

@world.absorb
def my_project_wide_function():
    # do something

world.my_project_wide_function()

You can also use it with classes:

from lettuce import world

@world.absorb
class MyClass:
    pass

assert isinstance(world.MyClass(), MyClass)

And even with lambdas, but in this case you need to name it

from lettuce import world

world.absorb(lambda: "yeah", "optimist_function")

assert world.optimist_function() == 'yeah'

world.spew¶

Well, if you read the topic above, you may be guessing: “if I keep stashing things in lettuce.world, it may bloat it sometime, or confuse member names along my steps, or hooks.

For those cases after “absorbing” something, world can also “spew” it.

from lettuce import world

@world.absorb
def generic_function():
    # do something

assert hasattr(world, 'generic_function')

world.spew('generic_function')

assert not hasattr(world, 'generic_function')

@before.all¶

This hook is ran before lettuce look for and load feature files

The decorated function takes NO parameters

from lettuce import *

@before.all
def say_hello():
    print "Hello there!"
    print "Lettuce will start to run tests right now..."

@after.all¶

This hook is ran after lettuce run all features, scenarios and steps

The decorated function takes a TotalResult as parameter, so that you can use the result statistics somehow

from lettuce import *

@after.all
def say_goodbye(total):
    print "Congratulations, %d of %d scenarios passed!" % (
        total.scenarios_ran,
        total.scenarios_passed
    )
    print "Goodbye!"

@before.each_feature¶

This hook is ran before lettuce run each feature

The decorated function takes a Feature as parameter, so that you can use it to fetch scenarios and steps inside.

from lettuce import *

@before.each_feature
def setup_some_feature(feature):
    print "Running the feature %r, at file %s" % (
        feature.name,
        feature.described_at.file
    )

@after.each_feature¶

This hooks behaves in the same way @before.each_feature does, except by the fact that its ran after lettuce run the feature.

from lettuce import *

@after.each_feature
def teardown_some_feature(feature):
    print "The feature %r just has just ran" % feature.name

@before.each_scenario¶

This hook is ran before lettuce run each scenario

The decorated function takes a Scenario as parameter, so that you can use it to fetch steps inside.

from lettuce import *
from fixtures import populate_test_database

@before.each_scenario
def setup_some_scenario(scenario):
    populate_test_database()

@after.each_scenario¶

This hooks behaves in the same way @before.each_scenario does, except by the fact that its ran after lettuce run the scenario.

from lettuce import *
from database import models
@after.each_scenario
def teardown_some_scenario(scenario):
    models.reset_all_data()

@before.each_step¶

This hook is ran before lettuce run each step

The decorated function takes a Step as parameter, so that you can use it to fetch tables and so.

from lettuce import *

@before.each_step
def setup_some_step(step):
    print "running step %r, defined at %s" % (
        step.sentence,
        step.defined_at.file
    )

from lettuce import *

@after.each_step
def teardown_some_step(step):
    if not step.hashes:
       print "no tables in the step"

@before.harvest¶

This hook is ran before lettuce start harvesting your Django tests. It can be very useful for setting up browser drivers (such as selenium), before all tests start to run on Django.

The decorated function takes a dict with the local variables within the harvest management command.

from lettuce import *
from lettuce.django import django_url
from selenium import selenium

@before.harvest
def prepare_browser_driver(variables):
    if variables.get('run_server', False) is True:
        world.browser = selenium('localhost', 4444, '*firefox', django_url('/'))
        world.browser.start()

@after.harvest¶

This hook is ran right after lettuce finish harvesting your Django tests. It can be very useful for shutting down previously started browser drivers (see the example above).

The decorated function takes a list of TotalResult objects.

from lettuce import *

@after.harvest
def shutdown_browser_driver(results):
    world.browser.stop()

@before.each_app¶

This hook is ran before lettuce run each Django app.

The decorated function takes the python module that corresponds to the current app.

from lettuce import *

@before.each_app
def populate_blog_database(app):
    if app.__name__ == 'blog':
        from blog.models import Post
        Post.objects.create(title='Nice example', body='I like writting!')

@after.each_app¶

This hook is ran after lettuce run each Django app.

The decorated function takes two arguments:

• the python module that corresponds to the current app.
• a TotalResult as parameter, so that you can use the result statistics somehow

from lettuce import *

@after.each_app
def clear_blog_database_if_successful(app, result):
    if app.__name__ == 'blog':
        if result.scenarios_ran is result.scenarios_passed:
            from blog.models import Post, Comment
            Comment.objects.all()
            Post.objects.all()

@before.runserver and @after.runserver¶

These hooks are ran right before, and after lettuce starts up the built-in http server.

The decorated function takes a lettuce.django.server.ThreadedServer object.

from lettuce import *
from django.core.servers.basehttp import WSGIServer

@before.runserver
def prepare_database(server):
    assert isinstance(server, WSGIServer)
    import mydatabase
    mydatabase.prepare()

@after.runserver
def say_goodbye(server):
    assert isinstance(server, WSGIServer)
    print "goodbye, see you soon"

@before.handle_request and @after.handle_request¶

These hooks are ran right before, and after lettuce’s built-in HTTP server responds to a request.

Both decorated functions takes these two arguments:

• a django.core.servers.basehttp.WSGIServer object.
• a lettuce.django.server.ThreadedServer object.

from lettuce import *
from django.core.servers.basehttp import WSGIServer

@before.handle_request
def print_request(httpd, server):
    socket_object, (client_address, size) = httpd.get_request()
    print socket_object.dup().recv(size)

@after.handle_request
def say_goodbye(httpd, server):
    socket_object, (client_address, size) = httpd.get_request()
    print "I've just finished to respond to the client %s" % client_address

english example¶

# language: en
Feature: write features in english
   Scenario: simple scenario
      Given I write a file which starts with "# language: en"
      Then it must be parsed with proper english keywords

brazilian portuguese example¶

# language: pt-br
Funcionalidade: escrever funcionalidades em português
   Cenário: cenário simples
      Dado que eu crio um arquivo que começa com "# language: pt-br"
      Então ele deve ser interpretado com as devidas palavras-chave brasileiras

fetch the code¶

First of all, you must have git control version installed in your machine.

Once you have it installed, grab the code with

user@machine:~$ git clone git://github.com/gabrielfalcao/lettuce.git

And edit the file located at:

lettuce/languages.py

And add a new dictionary entry for your native language.

Let’s see the Brazilian Portuguese translation to exemplify.

LANGUAGES = {
    'pt-br': {
        'examples': u'Exemplos|Cenários',
        'feature': u'Funcionalidade',
        'name': u'Portuguese',
        'native': u'Português',
        'scenario': u'Cenário|Cenario',
        'scenario_outline': u'Esquema do Cenário|Esquema do Cenario',
        'scenario_separator': u'(Esquema do Cenário|Esquema do Cenario|Cenario|Cenário)',
    },
}

The key of the dict will be used as identifier for the comment # language: identifier at feature files.

The value must be a dict, where the keys are canonical representation of keywords (string), and the values must be a pipe-separated string with translation possibilities.

It allows different translations for the same keyword in the current language, which offers many possibilities for different semantical cases.

For example, when using scenario outlines, it can be semantically nicer to write:

Scenarios:
   | name | age |
   | John | 22  |
   | Mary | 53  |

Instead of:

Examples:
   | name | age |
   | John | 22  |
   | Mary | 53  |

add your translation¶

Now you can add your own language to lettuce, save the languages.py file and commit in the source control with.

For example, let’s suppose that you’ve added Spanish support:

user@machine:~/lettuce$ git commit lettuce/languages.py -m 'adding translation for spanish'

Generate a patch:

user@machine:~/lettuce$ git format patch HEAD^1

And send to lettuce’s ticket tracker as a gist or something like it.

registering your own model creators¶

For more complex models that have to process or parse data you can write your own creating steps using the creates_models decorator.

from lettuce.django.steps.models import (creates_models,
                                         reset_sequence,
                                         hashes_data)

@creates_models(Note)
def create_note(step):
    data = hashes_data(step)
    for row in data:
        # convert the author into a user object
        row['author'] = get_user(row['author'])
        Note.objects.create(**row)

    reset_sequence(Note)

registering your own model testers¶

For more complex tests that have to process or parse data you can write your own creating steps using the checks_existence decorator.

other considered variables¶

SOUTH_TESTS_MIGRATE – apply a south migration to the test database

1. install the lettuce django app¶

Pick up any Django project, and add lettuce.django in its settings.py configuration file:

INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.admin',

    # ... other apps here ...
    'my_app',
    'foobar',
    'another_app',
    'lettuce.django', # this guy will do the job :)
)

Considering the configuration above, let’s say we want to write tests for the my_app django application.

2. create the feature directories¶

Lettuce will look for a features folder inside every installed app:

/home/user/projects/djangoproject
     | settings.py
     | manage.py
     | urls.py
     | my_app
           | features
                - index.feature
                - index.py
     | foobar
           | features
                - carrots.feature
                - foobar-steps.py
     | another_app
           | features
                - first.feature
                - second.feature
                - many_steps.py

3. write your first feature¶

@index.feature:

Feature: Rocking with lettuce and django

    Scenario: Simple Hello World
        Given I access the url "/"
        Then I see the header "Hello World"

    Scenario: Hello + capitalized name
        Given I access the url "/some-name"
        Then I see the header "Hello Some Name"

@index-steps.py:

from lettuce import *
from lxml import html
from django.test.client import Client
from nose.tools import assert_equals

@before.all
def set_browser():
    world.browser = Client()

@step(r'I access the url "(.*)"')
def access_url(step, url):
    response = world.browser.get(url)
    world.dom = html.fromstring(response.content)

@step(r'I see the header "(.*)"')
def see_header(step, text):
    header = world.dom.cssselect('h1')[0]
    assert header.text == text

4. run the tests¶

Once you install the lettuce.django app, the command harvest will be available:

user@machine:~projects/djangoproject $ python manage.py harvest

The harvest command executes the django.test.utils.setup_test_environment function before it starts up the Django server. Typically, invoking this function would configure Django to use the locmem in-memory email backend. However, Lettuce uses a custom Django email backend to support retrieving email from Lettuce test scripts. See Checking email for more details.

5. specifying feature files¶

The harvest command accepts a path to feature files, in order to run only the features you want.

Example:

user@machine:~projects/djangoproject $ python manage.py harvest path/to/my-test.feature

6. grab actual example code¶

In order to assure that lettuce integrate well with Django, it have a set of integration tests, there are a actual Django project running with lettuce.

You can grab the code at the alfaces folder of lettuce git repository

red-tape-less builtin server¶

Lettuce cleverly runs an instance of the built-in Django HTTP server in the background. It tries to bind the HTTP server at localhost:8000 but if the port is busy, it keeps trying to run in higher ports: 8001, 8002 and so on until it reaches the maximum port number 65535.

So that you can use browser-based tools such as those listed above to access Django.

figure out django urls¶

As the Django HTTP server can be running in any port within the range 8000 - 65535, it could be hard to figure out the correct URL for your project, right?

Wrong!

Lettuce is here for you. Within your steps you can use the django_url utility function:

from lettuce import step, world
from lettuce.django import django_url

@step(r'Given I navigate to "(.*)"')
def navigate_to_url(step, url):
    full_url = django_url(url)
    world.browser.get(full_url)

from lettuce.django import django_url
django_url("/admin/login")

"http://localhost:9090/admin/login"

terrain also available in django projects¶

At this point you probably know how terrain.py works, and it also works with Django projects.

You can setup environment and stuff like that within a terrain.py file located at the root of your Django project.

Taking the very first example of this documentation page, your Django project layout would like like this:

/home/user/projects/djangoproject
     | settings.py
     | manage.py
     | urls.py
     | terrain.py
     | my_app
           | features
                - index.feature
                - index.py
     | foobar
           | features
                - carrots.feature
                - foobar-steps.py
     | another_app
           | features
                - first.feature
                - second.feature
                - many_steps.py

Notice the terrain.py file at the project root, there you can populate the world and organize your features and steps with it :)

Checking email¶

When you run your Django server under lettuce, emails sent by your server do not get transmitted over the Internet. Instead, these emails are added to a multiprocessing.Queue object at lettuce.django.mail.queue.

Example:

from lettuce import step
from lettuce.django import mail
from nose.tools import assert_equals


@step(u'an email is sent to "([^"]*?)" with subject "([^"]*)"')
def email_sent(step, to, subject):
    message = mail.queue.get(True, timeout=5)
    assert_equals(message.subject, subject)
    assert_equals(message.recipients(), [to])

Running without HTTP server¶

Sometimes you may just do not want to run Django’s built-in HTTP server running in background, in those cases all you need to do is run the harvest command with the --no-server or -S option.

Example:

python manage.py harvest --no-server
python manage.py harvest -S

running the HTTP server in other port than 8000¶

If you face the problem of having lettuce running on port 8000, you can change that behaviour.

Before running the server, lettuce will try to read the setting LETTUCE_SERVER_PORT which must be a integer

Example:

LETTUCE_SERVER_PORT = 7000

This can be really useful if 7000 is your default development port, for example.

running the HTTP server with settings.DEBUG=True¶

In order to run tests against the nearest configuration of production, lettuce sets up settings.DEBUG=False

However, for debug purposes one can face a misleading HTTP 500 error without traceback in Django. For those cases lettuce provides the --debug-mode or -d option.

python manage.py harvest --debug-mode
python manage.py harvest -d

using the test database¶

If you want to use a test database by default, instead of a live database, with your test server you can specify the -T flag or set the following configuration variable in settings.py.

LETTUCE_USE_TEST_DATABASE = True

running only the specified scenarios¶

You can also specify the index of the scenarios you want to run through the command line, to do so, run with --scenarios or -s options followed by the scenario numbers separated by commas.

For example, let’s say you want to run the scenarios 4, 7, 8 and 10:

python manage.py harvest --scenarios=4,7,8,10
python manage.py harvest -s 4,7,8,10

to run or not to run? That is the question!¶

During your development workflow you may face two situations:

python manage.py harvest --apps=myapp,foobar

# or

python manage.py harvest --a  myapp,foobar

LETTUCE_APPS = (
    'myapp',
    'foobar',
)
INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.admin',
    'my_app',
    'foobar',
    'another_app',
    'lettuce.django',
)

python manage.py harvest --avoid-apps=another_app,foobar

LETTUCE_AVOID_APPS = (
    'another_app',
    'foobar',
)

INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.admin',
    'my_app',
    'foobar',
    'another_app',
    'lettuce.django',
)