Naming Tests

A lot of people wonder what they should name their tests. In fact, Steven Haryanto just asked about this, so I thought I would offer my perspective.

When naming tests, longer names are better. Even though tests aren't really documentation in the sense that many people think of documentation, tests can serve that role if well-handled. For example, I have a test method in my current project which just checks to ensure that a normal user cannot access the "admin" page and that they'll be sent back to the login screen. Here's what you see if you run that test method:

1..3
ok 1 - Normal users can try to get to the admin page
ok 2 - ... and they should be told that they need admin privileges
ok 3 - ... and they should be sent back to the login page

This narrative style of test names gets us a lot closer to tests as documentation. The test names describe the behavior in a way that the actual code does not. So if I had omitted the test names, here's what the code would have looked like:

sub not_admin : Tests(3) {
    my $test = shift;
    my $mech = $test->test_mech;
    $mech->user_login;
    $mech->get_ok( '/admin/' );
    like $mech->content, 
      qr/You need to be an administrator to view this page/;
    is $mech->uri->path, '/login';    
}

In other words, you can kind of get a sense of what's going on, but the descriptive test names allow anyone to return to this months later and instantly know what's going on and why, rather than trying to parse code. It does take a little more work up front and it helps if you think of having a conversation with someone where you're describing behavior. Long-term maintainability of your project will be a huge win, though.

4 Comments

Since you're using Test::WWW::Mechanize, you can say

$mech->content_like( qr/You need to be an administrator to view this page/ );

I like that reasoning a lot.

I wouldn't think this one would be controversial.. test names should indeed be descriptive (test file names probably should be also, though that's a slightly different subject). A problem I've had with test names though, is that if I accidentally sound too positive in my wording (not usually a problem with me in other areas), it creates a mental glitch where I have trouble seeing a "not ok" because it's immediately followed by something that contradicts it, like "Authentication works well." or "Generated data looks good." I've adopted the habit of forcing myself to sound tentative, even though it probably seems like I'm repeating myself a lot: "Testing that authentication works.", "Testing that generated data matches expectations.", etc.

doomvox, how about these?

  • “Testing authentication”
  • “Checking expectations for generated data”

Ie. describe the act, not the desired outcome.

Leave a comment

About Ovid

user-pic Have Perl; Will Travel. Freelance Perl/Testing/Agile consultant. Photo by http://www.circle23.com/. Warning: that site is not safe for work. The photographer is a good friend of mine, though, and it's appropriate to credit his work.