Freshen is an acceptance testing framework for Python, inspired by Cucumber and has the same goal: make BDD fun, but using Python instead of Ruby. Freshen uses the same syntax of Cucumber (Gherkin Syntax) and runs as a plugin of Nose, a powerful Python tool for using daily when you with TDD =)

Important: If you don’t know Django, this article is not recommended for you.

Nose is plugin based, so to use Django under Nose, we need to install a plugin called NoseDjango. To work isolated from the database, we need a mock framework. Let’s use Mock, wich is a simple and powerful mock framework for Python. We can install Django, Freshen, Mock, Nose and NoseDjango with a simple command:

It works in any operating system with Python and PIP.

After installing everything we need, we just start a Django Project, called “library” (just supposing that we are developing a software for the library on the next corner):

Looking quickly on Django settings, in the settings.py file, only database and templates settings:

After start and setup the project, let’s start our Django application. Let’s start an application called “loans”. It app will manage the loans of our library:

After start the application, let’s define our Book model and install the application. You can see below the code of models module inside the loans app:

Now, we need to describe our acceptance tests, or as Freshen and Cucumber call: our system features. Let’s describe the loans application’s features inside the loans application, creating a directory called “features” inside the application.

The first feature of the application will be a feature that describes the access to a list containg all the books on the path “/loans/books”:

Let’s understand the feature: A Freshen feature is a description of a system feature! :) On the list of books, we have a scenario where we list all books. That scenario is described using some steps: given, when and then. You can learn more about Given, When and Then looking for some resources about BDD.

After describe a feature and it’s scenarios, we need to define the steps of each scenario. So, we put these definitions in a Python module called steps.py in our features directory. The scenario List all books has three steps: “Given there are 20 books in the system”; “When I navigate to the books list page” and “Then I should see the title of the 20 books”. First, let’s define the first step: Given there are 20 books in the system. Each step definition is a Python function decorated with the keyword that defines that step.

So, to define “Given” step, Freshen provides the @Given decorator. Let’s define a function that creates and saves 20 books in the database. But we will not really save it in the database, because we are working isolated from the database. We will just store the book list in a context object.

We use a regular expression to determine a pattern to receive a parameter in the function. The function create_books receives a parameter wich indicates the number of books that will be created. All parameters obtained from step specification is an instance of str and need to be converted properly if you want to use it as a number.

The second line of the create_books function defines an empty list called books inside an object called scc. Freshen provides three objects for context storage: glc, the global context, wich is never cleaned; ftc, the feature context, cleaned at the start of each feature and scc, the scenario context, wich is cleaned at the start of each scenario. Once we put the books object list in the scenario context, we can use this list in all steps of that scenario.

Now, let’s define the second step: When I navigate to the books list page. Now we will use the @When decorator to decorate a function called navigate_to_books_list. Here is the code:

This function just makes a GET request on the URL /loans/books and saves the response in a object called response, stored in scenario context. The Book model was mocked here, using the patch decorator from Mock. We said to the mock: “when Book.objects.all() is called, return my list of books, stored in scenario context”. The last line of the function asserts if the method is really called in our GET request.

Now we can run the nosetests and see what happens. To execute Nose with Django and Freshen, we need to run the following command:

The output at this point is:

The test fails with the following exception: TemplateDoesNotExist: 404.html. So, let’s create that template and see what happens.

After add a 404.html template to the templates directory in the root of the project, just run nosetests again, using the verbose mode:

Step fails again, why? On function “navigate_to_books_list” the last line defines that the method Book.objects.all() should be called with no parameters in the GET request (lines above), but this method was not called anywhere, once that GET request returned a 404 response, because there is not an URL mapping to a view that responds by the action ‘/loans/books’, and there is not a view wich makes the expected method call. So, let’s make the view and map it to the “/loans/books” path. Here is the view code:

Look that the view has only two lines of code and returns a HttpResponse object with blank content, it’s the enough code to make the Step definition works. To map the view to a URL path, create a urls.py module inside the application directory, with the following code:

And include it on the main urls.py of project, that will contain the code bellow:

Run nosetests again and see what happens:

Freshen said: I found an undefined step (“I should see the title of the 20 books”). Let’s define that step, using the @Then decorator to decorate our function called check_presence_of_the_title_of_books:

The function checks if the books titles is included in a li HTML element. Let’s call nosetests again and see the test failing:

The content returned by the GET request (an empty string) is not the content expected by the defined step, so we see an AssertionError. Now, we need to make this test pass. To do it, we need only to refactor the view:

And we run nosetests with Django and Freshen, in verbose mode again, and see that everything works fine =D

That is all, folks! :) You can download this Django Project at Github.