Founder of Kernl.us. Working and living in Raleigh, NC. I manage a team of software engineers and work in Python, Django, TypeScript, Node.js, React+Redux, Angular, and PHP. I enjoy hanging out with my wife and son, lifting weights, and advancing Kernl.us in my free time.
For a few hours I was running into a problem whenever I would try to install my PIP requirements file. The install would go alright until it got to Distribute, at which point I would get an that ended up in a stack trace with:
Could not find the/lib/python2.7/site-packages/site.py element of the Setuptools distribution
After much searching and digging, the issue was that my virtual environment needed to be instantiated with the –distribute flag.
virtualenv venv --distribute |
virtualenv venv --distribute
Problem solved.
I recently made the case for using the open-source WordPress CMS instead of a custom hand-rolled CMS to a manager. What follows is the email (with names and companies changed) that was sent. I thought that it might be useful to other people who are trying to convince their organization to take the leap to WordPress, Drupal, or any other open-source CMS. It’s also worth noting that I’m on very friendly terms with my manager, hence the informality and straight-forwardness. As for the Django references, we develop most of our data-driven sites in Python/Django.
Hey [Manager],
As you already know, I completely loathe the [Custom] CMS. My recent and ongoing experiences with the [Client] website have only served to reinforce these feelings. Unbridled hate rarely serves any useful purpose though, so I’ve decided to see what I can do to make the problem better. My way of doing that is by making a case for using WordPress on large, non-trivial, content driven websites. As of right now WordPress has been lasso’d into small-size websites at [Company], but I believe it is capable of far more then that. What follows is a breakdown of all the feedback, questions, and concerns that were raised while I was gathering information. I’ve provided solutions to almost all of the problems, and its worth noting that some of the problems with WordPress are not unique to WordPress. I also want to make it clear that I’m not trying to get rid of the [Custom] CMS, especially since we have a lot of clients with a lot of money invested in it. I’m simply making a case for using WordPress on large sites instead of the [Custom] CMS.
For as long as I can remember, [Other Manager] always raised a red flag with WordPress because it was inferior in content creation to the CMS. In vanilla form this is arguably true, however WordPress has an amazing community of plugin developers surrounding it who have solved all of these problems.
I have a handful of notes that don’t fit well into Content Creation / Management or Development, so here we go.
In the past, a lot of misinformation has been spread about WordPress and how developing with it is awful. A lot of that comes from lack of knowledge, so I thought I’d address a lot of the pain points that people have experienced.
I know we’ve talked in the past about vetting a Django CMS, but I think that using WordPress is the best choice. We already have people who know it, the front-enders know how to develop for it, the community is massive, and learning it is easy. I look forward to talking with you about this.
The Ruby on Rails community has long been a proponent of Behavior Driven Development(BDD) and has a great ecosystem around it supporting that testing methodology. From Cucumber to Capybara, RoR developers have it made when it comes to BDD. But what about Django? What about Python? Django and Python don’t have access to Cucumber or Capybara, but what we do have is a fantastic port of Cucumber called Lettuce.
Before we can get started talking about Lettuce and all the cool things you can do with it, we first need to talk about BDD.
Behavior-driven development combines the general techniques and principles of TDD with ideas from domain-driven design and object-oriented analysis and design to provide software developers and business analysts with shared tools and a shared process to collaborate on software development. (Wikipedia)
BDD arose out of the need for the business side of software and the engineering side of software to communicate more effectively. Prior to BDD, it was a lot more difficult to communicate the business requirements of a project to developers. Sure there were spec documents, but those still needed to be translated into a language the computer can understand. With BDD, tests and acceptance criteria are more accessible to everybody involved. Dan North suggested a few guidelines for BDD, and then the development community took it from there.
An example feature using Gherkin.
Feature: Authentication
In order to protect private information
As a registered user
I want to log in to the admin portal
Scenario: I enter my password correctly
Given the user "Jack" exists with password "password"
And I am at "/login/"
When I fill in "Login" with "Jack"
And I fill in "Password" with "password"
And I press "Login"
Then I should be at "/portal/"
And I should see "Welcome to the admin portal" |
Feature: Authentication In order to protect private information As a registered user I want to log in to the admin portal Scenario: I enter my password correctly Given the user "Jack" exists with password "password" And I am at "/login/" When I fill in "Login" with "Jack" And I fill in "Password" with "password" And I press "Login" Then I should be at "/portal/" And I should see "Welcome to the admin portal"
So now that we know the gist of BDD, why would you want to use it? There are probably more reasons than the 3 I’m going to list, but I found these to justify my use of BDD in most cases.
Alright, now we’re done with the background information. Let’s get rolling on some testing.
To follow the rest of this article, you’re going to need the following:
On the bright side, no previous testing experience required!
The best place to start with all this getting the virtual environment set up.
jacks$ mkvirtualenv learning_lettuce |
jacks$ mkvirtualenv learning_lettuce
After that, lets get Django installed.
(learning_lettuce)jack:repos jacks$ pip install django |
(learning_lettuce)jack:repos jacks$ pip install django
And now we’ll need to create a new Django project.
(learning_lettuce)jack:repos jacks$ django-admin.py startproject learning_lettuce (learning_lettuce)jack:repos jacks$ cd learning_lettuce/ (learning_lettuce)jack:learning_lettuce jacks$ ls -la total 8 drwxr-xr-x 4 jacks staff 136 Jun 19 07:50 . drwxrwxrwx 28 jacks staff 952 Jun 19 07:50 .. drwxr-xr-x 6 jacks staff 204 Jun 19 07:50 learning_lettuce -rw-r--r-- 1 jacks staff 259 Jun 19 07:50 manage.py |
(learning_lettuce)jack:repos jacks$ django-admin.py startproject learning_lettuce (learning_lettuce)jack:repos jacks$ cd learning_lettuce/ (learning_lettuce)jack:learning_lettuce jacks$ ls -la total 8 drwxr-xr-x 4 jacks staff 136 Jun 19 07:50 . drwxrwxrwx 28 jacks staff 952 Jun 19 07:50 .. drwxr-xr-x 6 jacks staff 204 Jun 19 07:50 learning_lettuce -rw-r--r-- 1 jacks staff 259 Jun 19 07:50 manage.py
At this point, I also like to CHMOD manage.py so I can execute it without calling Python directly.
(learning_lettuce)jack:learning_lettuce jacks$ chmod +x manage.py (learning_lettuce)jack:learning_lettuce jacks$ ./manage.py runserver Validating models... 0 errors found June 19, 2013 - 06:53:29 Django version 1.5.1, using settings 'learning_lettuce.settings' Development server is running at http://127.0.0.1:8000/ Quit the server with CONTROL-C. |
(learning_lettuce)jack:learning_lettuce jacks$ chmod +x manage.py (learning_lettuce)jack:learning_lettuce jacks$ ./manage.py runserver Validating models... 0 errors found June 19, 2013 - 06:53:29 Django version 1.5.1, using settings 'learning_lettuce.settings' Development server is running at http://127.0.0.1:8000/ Quit the server with CONTROL-C.
If you can run the server and see the image below, then we can proceed.
Now that we have Django set up, lets go ahead and create the app we’ll be testing in.
(learning_lettuce)jack:learning_lettuce jacks$ ./manage.py startapp blog |
(learning_lettuce)jack:learning_lettuce jacks$ ./manage.py startapp blog
And then go ahead and add the blog app to INSTALLED_APPS in your settings.py file.
INSTALLED_APPS = ( 'django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', 'django.contrib.sites', 'django.contrib.messages', 'django.contrib.staticfiles', # Authored 'blog', ) |
INSTALLED_APPS = ( 'django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', 'django.contrib.sites', 'django.contrib.messages', 'django.contrib.staticfiles', # Authored 'blog', )
Also, lets configure our project to use SQLite3.
DATABASES = { 'default': { 'ENGINE': 'django.db.backends.sqlite3', 'NAME': 'learning_lettuce.db', } } |
DATABASES = { 'default': { 'ENGINE': 'django.db.backends.sqlite3', 'NAME': 'learning_lettuce.db', } }
Now that we have a Django project and one app set up, its time to take a break and talk about Lettuce.
No, not the vegetable you add to salads. I’m talking about the the BDD testing framework for Python (http://www.lettuce.it). Lettuce is basically a port of a BDD testing framework from the RoR community called Cucumber. The Lettuce website contains extensive documentation and is a great source for learning best practices with it. It’s worth noting however, that at the time of this writing the Lettuce website is undergoing some design changes. They’re incomplete and have made it pretty hard to extract information from the site. Hopefully by the time you need it for reference it’s back to being usable again.
Alright, back to work. Lets install Lettuce, Selenium, and Nose and then freeze a requirements file so we can replicate this environment if we ever need to.
(learning_lettuce)jack:learning_lettuce jacks$ pip install lettuce selenium django-nose (learning_lettuce)jack:learning_lettuce jacks$ pip freeze > requirements.txt (learning_lettuce)jack:learning_lettuce jacks$ cat requirements.txt Django==1.5.1 django-nose==1.1 fuzzywuzzy==0.2 ipdb==0.7 ipython==0.13.2 lettuce==0.2.18 nose==1.3.0 selenium==2.33.0 sure==1.2.2 wsgiref==0.1.2 |
(learning_lettuce)jack:learning_lettuce jacks$ pip install lettuce selenium django-nose (learning_lettuce)jack:learning_lettuce jacks$ pip freeze > requirements.txt (learning_lettuce)jack:learning_lettuce jacks$ cat requirements.txt Django==1.5.1 django-nose==1.1 fuzzywuzzy==0.2 ipdb==0.7 ipython==0.13.2 lettuce==0.2.18 nose==1.3.0 selenium==2.33.0 sure==1.2.2 wsgiref==0.1.2
You’ll also need to add Lettuce to INSTALLED_APPS in your settings.py file.
INSTALLED_APPS = ( 'django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', 'django.contrib.sites', 'django.contrib.messages', 'django.contrib.staticfiles', # 3rd party 'lettuce.django', # Authored 'blog', ) |
INSTALLED_APPS = ( 'django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', 'django.contrib.sites', 'django.contrib.messages', 'django.contrib.staticfiles', # 3rd party 'lettuce.django', # Authored 'blog', )
So now that you have Lettuce installed, lets see that it actually works.
(learning_lettuce)jack:learning_lettuce jacks$ ./manage.py harvest Django's builtin server is running at 0.0.0.0:8000 Oops! could not find features at ./blog/features |
(learning_lettuce)jack:learning_lettuce jacks$ ./manage.py harvest Django's builtin server is running at 0.0.0.0:8000 Oops! could not find features at ./blog/features
Great, Lettuce worked! It didn’t find any tests to run, but thats ok. At least we’ve verified that we installed everything correctly.
Before you can test anything, you should probably have some content to test on. So let’s quickly wire up a simple view in the blog app.
# blog/views.py from django.http import HttpResponse def quick_test(request): return HttpResponse("Hello testing world!"); |
# blog/views.py from django.http import HttpResponse def quick_test(request): return HttpResponse("Hello testing world!");
# learning_lettuce/urls.py from django.conf.urls import patterns, include, url from blog.views import quick_test urlpatterns = patterns('', url(r'^quick-test/$', quick_test), ) |
# learning_lettuce/urls.py from django.conf.urls import patterns, include, url from blog.views import quick_test urlpatterns = patterns('', url(r'^quick-test/$', quick_test), )
Great! Now when you go to http://127.0.0.1:8000/quick-test/ you should see “Hello testing world!”.
The next step is to create a folder inside of the blog app called “features”. And inside of that create a file called “test.feature”. It’s worth noting that Lettuce doesn’t actually care what your file is named, so long as the extension is “.feature”. In “test.feature”, add the following:
Feature: Test As someone new to testing So I can learn behavior driven development I want to write some scenarios Scenario: I can view the test page Given I am at "/quick-test/" Then I should see "Hello testing world!" |
Feature: Test As someone new to testing So I can learn behavior driven development I want to write some scenarios Scenario: I can view the test page Given I am at "/quick-test/" Then I should see "Hello testing world!"
Look at all that plain english! Even without me telling you anything, you can probably figure out what we’re trying to test. But let me break it down for you.
Alright, so now that you have your first test written, run it using “./manage.py harvest”. You should see the following:
Look at all that beautiful output! But what does it all mean?! It’s telling you that Lettuce attempted to run one scenario, and that the two steps within that scenario aren’t implemented yet (remember, each step maps to a method in your code). And because Lettuce is great, it gives you some code to help you implement those two steps.
Lettuce keeps all of it’s settings and configuration is a file called terrain.py in the root of your Django project. It’s here that we’re going to configure the test database, Firefox, and Selenium. Go ahead and create a terrain.py file in the root of your Django project, and drop the following in it.
from django.core.management import call_command from django.test.simple import DjangoTestSuiteRunner from lettuce import before, after, world from logging import getLogger from selenium import webdriver try: from south.management.commands import patch_for_test_db_setup except: pass logger = getLogger(__name__) logger.info("Loading the terrain file...") @before.runserver def setup_database(actual_server): ''' This will setup your database, sync it, and run migrations if you are using South. It does this before the Test Django server is set up. ''' logger.info("Setting up a test database...") # Uncomment if you are using South # patch_for_test_db_setup() world.test_runner = DjangoTestSuiteRunner(interactive=False) DjangoTestSuiteRunner.setup_test_environment(world.test_runner) world.created_db = DjangoTestSuiteRunner.setup_databases(world.test_runner) call_command('syncdb', interactive=False, verbosity=0) # Uncomment if you are using South # call_command('migrate', interactive=False, verbosity=0) @after.runserver def teardown_database(actual_server): ''' This will destroy your test database after all of your tests have executed. ''' logger.info("Destroying the test database ...") DjangoTestSuiteRunner.teardown_databases(world.test_runner, world.created_db) @before.all def setup_browser(): world.browser = webdriver.Firefox() @after.all def teardown_browser(total): world.browser.quit() |
from django.core.management import call_command from django.test.simple import DjangoTestSuiteRunner from lettuce import before, after, world from logging import getLogger from selenium import webdriver try: from south.management.commands import patch_for_test_db_setup except: pass logger = getLogger(__name__) logger.info("Loading the terrain file...") @before.runserver def setup_database(actual_server): ''' This will setup your database, sync it, and run migrations if you are using South. It does this before the Test Django server is set up. ''' logger.info("Setting up a test database...") # Uncomment if you are using South # patch_for_test_db_setup() world.test_runner = DjangoTestSuiteRunner(interactive=False) DjangoTestSuiteRunner.setup_test_environment(world.test_runner) world.created_db = DjangoTestSuiteRunner.setup_databases(world.test_runner) call_command('syncdb', interactive=False, verbosity=0) # Uncomment if you are using South # call_command('migrate', interactive=False, verbosity=0) @after.runserver def teardown_database(actual_server): ''' This will destroy your test database after all of your tests have executed. ''' logger.info("Destroying the test database ...") DjangoTestSuiteRunner.teardown_databases(world.test_runner, world.created_db) @before.all def setup_browser(): world.browser = webdriver.Firefox() @after.all def teardown_browser(total): world.browser.quit()
In your settings.py file, you’re going to need some additions too.
# Nose TEST_RUNNER = 'django_nose.NoseTestSuiteRunner' # Lettuce LETTUCE_SERVER_PORT = 9000 |
# Nose TEST_RUNNER = 'django_nose.NoseTestSuiteRunner' # Lettuce LETTUCE_SERVER_PORT = 9000
We use the Nose test runner because it’s faster than Django’s default test runner, and we change the server port for running tests so it doesn’t collide with our development server. At this point if you run `./manage.py harvest` again, you’ll still get notices for unimplemented steps, but you’ll also see Firefox open and close real quick. That means we’ve done our job correctly.
Alright, lets make something happen. If you look at the output from the harvest command, you’ll see that it gave you some code to help you implement the new steps that you wrote. Go ahead and copy that code into the bottom of the terrain.py file (and make sure to import ‘step’ at the top). Now, re-run ./manage.py harvest. You should get the following output.
So why did our steps fail? If you look that the code that was generated for you, there is a line that essentially says “False is equal to some string”. This is obviously not true, so our step fails. So why don’t we make the test pass? We’re going to change a few things:
@step(u'I am at "([^"]*)"') def i_am_at_url(step, url): world.browser.get(url) |
@step(u'I am at "([^"]*)"') def i_am_at_url(step, url): world.browser.get(url)
Now if you run ./manage.py harvest command again your tests will still fail, but this time for a different reason. The reason is the url that we’re passing into the step definition isn’t well formed. We were hoping to be able to pass relative urls in, but we can’t. So go ahead and modify the step in your scenario to look like this.
Given I am at "http://127.0.0.1:9000/quick-test/" |
Given I am at "http://127.0.0.1:9000/quick-test/"
Run ./manage.py harvest again. You’ll see one passing test and one failing test!
To make the next step pass, we need to make our web page a bit more formal. Go ahead and create a folder called “templates” inside of the “blog” app. Inside that folder, add a file called “base.html” and populate it with:
<html>
<head>
<title>Learning Lettuce!</title>
</head>
<body id='content'>
{% block content %}{% endblock %}
</body>
</html> |
<html> <head> <title>Learning Lettuce!</title> </head> <body id='content'> {% block content %}{% endblock %} </body> </html>
Now create a file called “blog.html” inside the same folder. Give it the following content:
{% extends "base.html" %}
{% block content %}
Hello testing world!
{% endblock %} |
{% extends "base.html" %} {% block content %} Hello testing world! {% endblock %}
You’ll also need to update the view:
from django.shortcuts import render_to_response def quick_test(request): return render_to_response("blog.html", {}) |
from django.shortcuts import render_to_response def quick_test(request): return render_to_response("blog.html", {})
And you’ll need to update your settings file.
## Add this at the top of settings.py import os.path root = os.path.dirname(__file__).replace('\\','/') ## Make your TEMPLATE_DIRS variable look like this TEMPLATE_DIRS = ( root + "/../blog/templates/", ) |
## Add this at the top of settings.py import os.path root = os.path.dirname(__file__).replace('\\','/') ## Make your TEMPLATE_DIRS variable look like this TEMPLATE_DIRS = ( root + "/../blog/templates/", )
Now that our template is more formalized, lets update the step definition in “terrain.py”.
@step(u'I should see "([^"]*)"') def i_should_see_content(step, content): if content not in world.browser.find_element_by_id("content").text: raise Exception("Content not found.") |
@step(u'I should see "([^"]*)"') def i_should_see_content(step, content): if content not in world.browser.find_element_by_id("content").text: raise Exception("Content not found.")
This code explains itself pretty easily. We check to see if the content that is passed in via the step exists inside the body of the page. This has a few drawbacks:
Since this is a simple example, we’re going to ignore these issues for now and just run our tests.
Passing tests!
Now that you have passing steps, you’re well on your way to writing serious integration tests for your code. But there is still a lot more to learn. The next article in this series will cover using Lettuce Webdriver to handle common step definitions, tables, scenario outlines, and much much more.
All code related to this post can be found at https://github.com/vital101/Learning-Lettuce
Lettuce is a BDD (Behavior Driven Development) testing tool for Python based on the excellent Cucumber project. It has most of the same features that Cucumber has, and has proven invaluable in my projects. I discovered an undocumented feature the other day called “Tags”. Cucumber has them, so I also assumed that Lettuce had them. Tags allow you to selectively skip or run scenarios. For instance:
Feature: Some Feature Scenario: This is scenario 1 Given I do stuff And I see stuff Then I am stuff @mytag Scenario: This is scenario 2 Given I do more stuff And I see more stuff Then I am more stuff |
Feature: Some Feature Scenario: This is scenario 1 Given I do stuff And I see stuff Then I am stuff @mytag Scenario: This is scenario 2 Given I do more stuff And I see more stuff Then I am more stuff
You can use tags in many ways.
lettuce --tag=mytag # Run only scenarios with this tag lettuce --tag=-mytag # Don't run scenarios with this tag ./manage.py harvest --tag=mytag # Django/Lettuce way of using tags.
There is a grand myth about requirements–if you write them down, users will get exactly what they want. That’s not true. At best, users will get exactly what was written down, which may or may not be anything like what they really want.
– Mike Cohn, “Succeeding with Agile”
One of the more useful features of the Django framework is it’s extensive signaling capabilities. The ORM throws off a handful of signals every time a model is initialized, modified, saved, or deleted. They include:
I tend to use the post_save signal fairly often as a good way to get around overriding the default save method on models. Recently though I ran into an issue where I was hitting the “maximum recursion depth exceeded” error when I was saving the current model from within the post_save signal. If you think about it, that makes a lot of sense. You save once, then save again in the signal and then it triggers the signal again. BOOM, infinite loop.
To get around the saving within a post_save signal problem, you just need to disconnect the post_save signal before you call save. After save, you can re-connect it.
from django.db.models import signals signals.post_save.disconnect(some_method, sender=SomeModel) some_instance.save() signals.post_save.connect(some_method, sender=SomeModel) |
from django.db.models import signals signals.post_save.disconnect(some_method, sender=SomeModel) some_instance.save() signals.post_save.connect(some_method, sender=SomeModel)
I recently needed to add a large number of users to a permission group in Django. I had a hard time finding a way to do this in the documentation, so I thought I’d share my solution.
from django.contrib.auth.models import Group, User g = Group.objects.get(name='My Group Name') users = User.objects.all() for u in users: g.user_set.add(u) |
from django.contrib.auth.models import Group, User g = Group.objects.get(name='My Group Name') users = User.objects.all() for u in users: g.user_set.add(u)
Easy as pie. I originally attempted to do this from the perspective of a user, but as it turns out, doing it from the group perspective is much easier.
Django’s ORM is top notch. It provides facilities to do almost anything you can think of with a database, and if it doesn’t, it still lets you execute arbitrary SQL to your hearts content. I’ve been developing Django for close to 2 years now, and still discover facets of it that I never knew existed. For instance, I had a need to duplicate a row in a table, but give it a different primary key. After a quick Google search, I discovered that Django allows you to do the following to copy instantiated model objects.
my_model = MyModel.objects.get(pk=4) my_model.id = None my_model.save() |
my_model = MyModel.objects.get(pk=4) my_model.id = None my_model.save()
There are a few caveats with doing things this way.
That being said, in many cases duplicating a model instance is as easy as changing it’s ID and saving.