Telerik blogs

Naming and organization is critical in keeping software systems maintainable as you move forward, especially with larger systems or systems with longer lifespans. You’ll find yourself spending large amounts of time stumbling around unclear, tangled source code if you don’t take care with how you lay out your classes, namespaces, and projects.

We should take the same exact care with our tests as the systems we’re delivering to our customers, because test code IS production code.

Careful naming and layout of your tests is every bit as important as the system itself—and perhaps even a bit more since we look to tests for so many crucial aspects of clarity around our projects including traceability, documentation, and understanding of behavior.

Good teams will spend a bit of time discussing naming and organization strategies during their initial project planning steps. Agreeing on a starting point for conventions in the system and tests is an important piece of getting off to a smooth start.

Note that I specifically stated that as “a starting point.” Every moderate to large project I’ve been involved with has undergone significant reorganization of our organization strategy as we’ve learned more about the system and figured out what best worked for that project. It’s important project teams understand and buy off on this concept from the start. It’s OK, moreover actually encouraged, to constantly evaluate what’s working with your test organization. Move things around. Rename your test containers (folders, in Test Studio). Rename the tests themselves. See what works, change what doesn’t.

Constant evaluation of your approach’s effectiveness is particularly critical as your project grows large. Organizing 200 tests is pretty easy. Organizing 8000 tests is a horse of a different color. You’ll need to work much harder at keeping sizable groups of tests in a usable structure.

Now, with all that out of the way, there are some simple guidelines for test organization I’ve found helpful. These are guidelines, so feel free to examine them and determine whether or not they make good sense for your environment, team, and project.

Use Containers to Create an Information Hierarchy

Test Studio enables you to create nested folders to help you organize your tests. With some careful planning you can create an information hierarchy that helps you easily store and find your tests. There are a number of different ways you can approach your hierarchy, again based on what you think will work for your project’s needs.

Function-based Hierarchy

If your main focus is on major slices of your system, then creating a series of folders around your system’s functionality will make great sense. The figure below is taken from our demo application. I’m using a very simple set of folders to group my tests by function. If these folders started getting a lot of tests in them I’d look to add a second level of folders to further refine my organization. Potential candidates for those sub-folders might be things like CRUD[1], Security, Validation, Sad Path, etc.

Component-based Hierarchy

This is quite similar to Function, but on a larger scale. Perhaps you work on a system which has forums, blogs, wikis, and messaging, plus a robust security system. Those large components would be great targets for organizing tests by. You’d likely couple this large bucket approach with a smaller bucket of functional areas.

Role-based Hierarchy

In some cases it might make great sense to organize your tests by roles they exercise. I’ve worked on a number of projects where system behavior was dramatically different based on what role the current user was using. In these sorts of cases having your tests arranged by those particular roles first and functionality second can be quite helpful.

Requirement-based Hierarchy

Many organizations place a high value on being able to trace all work back to requirements, so using a folder structure that mimics those requirements may be the right fit for you. An example of this would be using folders with the requirement number and title as part of it.

I really don’t care for this approach because I think it’s harder to understand the overall intent and coverage of tests; however, I’m sure some organizations will find this helpful, so please use it and ignore my biases if it will help you!

An Important Caveat

Folders are good, so lots of folders must be even better, right? No! Absolutely not! Be very careful how many layers deep you decide to go with your hierarchy. One level of containers helps group and clarify. A second layer may be helpful, a third possibly. Fourth and fifth levels of containers are are very likely a hindrance, and more are definitely a problem. If you are in the double-digits where the depth of your folders are concerned then please stop. Right now. You can tell them I said it was OK.

Choose Good Names

Good naming is critical for expressing what a test covers. Work hard at finding a naming strategy that works in your environment. My own naming conventions have changed considerably over the years, and I’m sure I’ll be naming things differently in two years.

I tend to use rather long, descriptive names in both the software and tests I write. I find the Behavior Driven Development style of longer names with a Given-When-Then pattern useful in many cases; however, I don’t follow that all the time—the demonstration application’s tests are a great example.

“Adding empty contact generates appropriate field and style errors” is an example of one current test I have. It’s in the action-result form. “Adding empty contact” is the action I’m taking in the test, and “generates appropriate field and style errors” is the result. This is also a great example of a test name where I am not completely satisfied with the name. “Appropriate” is rather vague, and I also have found names with “and” in them may indicate that class/method/test may be doing too much instead of being small and specific. That said, there’s little value in spending hours agonizing over your names. Get something fairly clear in place and rename it later if you come up with something clearer.

Something else to keep in mind is that you can combine your folder names with your test names to get some very readable tests. The example below shows how you can use folders for grouping by functional area, plus another folder for showing something by role, and finally a great descriptive name.

Be Consistent

Regardless of the approach you decide on, it’s critical to remain consistent in your naming and organization. Don’t mix styles. If you or your team finds out your approach isn’t working, great. Change it. But do it consistently.

Otherwise the entire thesis of this effort, making it easier to find and understand your tests, becomes irrelevant and you’ve done nothing but waste a lot of effort. Been there, done that, please don’t repeat the mistakes I’ve made!

Document Your Hierarchy

I’m no fan of documentation for documentation’s sake. Too much documentation is wasted effort, and it’s far too easy for the documentation to fall out of synch with the system you’re building or your tests.

That said, do spend a small amount of time getting together a README document on your organization and naming strategy. No fancy PowerPoint slides, no UML diagrams, just a plain old text file with a few short, concise bullet points or paragraphs on how your strategy works.

Where do you store this document? Right with your tests in your source control system! Keep it right where it’s easy to find and can be easily updated.

Spend Some Time, Get it Right

Organizing your tests is critical, especially when your project grows past a few handfuls of tests. Spend some time up front planning out your organizing strategy. Talk with other developers and testers. Find out what’s working for them and what’s not.

Whatever you do, keep investing time to make sure it’s working and adjust it as necessary. You’ll be happy you did!


[1]CRUD is an acronym for Create, Retrieve, Update, Delete—the four main actions around any type of data.

About the author

Jim Holmes

Jim Holmes

has around 25 years IT experience. He is co-author of "Windows Developer Power Tools" and Chief Cat Herder of the CodeMash Conference. He's a blogger and evangelist for Telerik’s Test Studio, an awesome set of tools to help teams deliver better software. Find him as @aJimHolmes on Twitter.


Comments are disabled in preview mode.