Writing long test method names to describe tests vs using in code documentation

Question

For writing unit tests, I know it's very popular to write test methods that look like

public void Can_User_Authenticate_With_Bad_Password()
{
...
}

While this makes it easy to see what the test is testing for, I think it looks ugly and it doesn't display well in auto-generated documentation (like sandcastle or javadoc).

I'm interested to see what people think about using a naming schema that is the method being tested and underscore test and then the test number. Then using the XML code document(.net) or the javadoc comments to describe what is being tested.

/// <summary>
/// Tests for user authentication with a bad password.
/// </summary>
public void AuthenticateUser_Test1()
{
...
}

by doing this I can easily group my tests together by what methods they are testing, I can see how may test I have for a given method, and I still have a full description of what is being tested.

we have some regression tests that run vs a data source (an xml file), and these file may be updated by someone without access to the source code (QA monkey) and they need to be able to read what is being tested and where, to update the data sources.

Answer 1

Personally I prefer using the long method names. Note you can also have the method name inside the expression, as:

Can_AuthenticateUser_With_Bad_Password()

Answer 2

I prefer the "long names" version - although only to describe what happens. If the test needs a description of why it happens, I'll put that in a comment (with a bug number if appropriate).

With the long name, it's much clearer what's gone wrong when you get a mail (or whatever) telling you which tests have failed.

I would write it in terms of what it should do though:

LogInSucceedsWithValidCredentials

LogInFailsWithIncorrectPassword

LogInFailsForUnknownUser

I don't buy the argument that it looks bad in autogenerated documentation - why are you running JavaDoc over the tests in the first place? I can't say I've ever done that, or wanted generated documentation. Given that test methods typically have no parameters and don't return anything, if the method name can describe them reasonably that's all the information you need. The test runner should be capable of listing the tests it runs, or the IDE can show you what's available. I find that more convenient than navigating via HTML - the browser doesn't have a "Find Type" which lets me type just the first letters of each word of the name, for example...

Answer 3

I suggest smaller, more focussed (test) classes.

Why would you want to javadoc tests?

Answer 4

What about changing

Can_User_Authenticate_With_Bad_Password

to

AuthenticateDenieTest
AuthenticateAcceptTest

and name suit something like User

Answer 5

Does the documentation show up in your test runner? If not that's a good reason for using long, descriptive names instead.

Personally I prefer long names and rarely see the need to add comments to tests.

Answer 6

As a Group how do we feel about doing a hybrid Naming schema like this

/// <summary>
/// Tests for user authentication with a bad password.
/// </summary>
public void AuthenticateUser_Test1_With_Bad_Password()
{
...
}

and we get the best of both.

Answer 7

I've done my dissertation on a related topic, so here are my two cents: Any time you rely on documentation to convey something that is not in your method signature, you are taking the huge risk that nobody would read the documentation.

When developers are looking for something specific (e.g., scanning a long list of methods in a class to see if what they're looking for is already there), most of them are not going to bother to read the documentation. They want to deal with one type of information that they can easily see and compare (e.g., names), rather than have to start redirecting to other materials (e.g., hover long enough to see the JavaDocs).

I would strongly recommend conveying everything relevant in your signature.