Your New Test Naming Convention

by Jeff Langr

April 28, 2024

In updating the book Pragmatic Unit Testing in Java to a third edition1 (it’s been 20 years since Andy Hunt and Dave Thomas published the first edition), I overhauled all of its code examples. First, to ensure they conform to the latest LTS version of Java (21). Second, and more importantly, to ensure they are more accessible, easier to follow, and more relevant to readers.

In updating all the tests, I chose to promote my preferred naming convention for unit test classes. Rather than the tired convention of SomeClassTest, I instead decided to go with a convention that supports better cataloging of tests.

About the convention

The convention: Test class names start with A, An, or Some. When using Some, pluralize the thing being described.

Thus PortfolioTest becomes APortfolio.

class APortfolio {
   @Test void reducesSharesOnSell() { /* ... */ }
   @Test void throwsWhenSellingMoreSharesThanHeld() { /* ... */ }

Using this convention, test names should generally be of the form “does something when context”, emphasizing the outcome first.

The simple rationale: You can combine the test class name with each test method name to form a sentence:

  • A portfolio reduces shares on sell

  • A portfolio throws when selling more shares than held

If a test class name starts with a vowel, it’s change to start with “An.” AnAuditor, AnUnfundedAccount, AnInMemoryDatabase.

If a test class name describes a utility class (i.e. all static methods), it becomes “Some” somethings. SomeMathUtils, SomeIoOperations.


  • If you’re used to locating tests by, say, typing in the word Test into a search box, you might have a tough time. I can’t remember the last time I found that kind of search useful, however. Learn other navigational shortcuts—for example, Cmd-Shift-t in IDEA toggles between test and production class, even with the new naming standard.

  • Sometimes the phrasing can be a little awkward. Most of time it’s not. Using JUnit 5’s @Nested classes can sometimes help, but they can also make deriving a good sentence challenging.


  • It reads well, particularly when you review the test execution summary. See the top image on this post.

  • It minimizes tired noise words like “given.”


If you use JetBrains IntelliJ IDEA, the default inspections will choke on this naming convention. Fortunately, you can update the inspection with a regular expression that will cover the new name standard.

To do so, open your preferences or settings in IDEA (or whatever they’re called on your platform / version). Navigate:

Settings -> Editor -> Inspections -> Java -> Naming Conventions -> Class -> Class naming conventions

In the lower-right quadrant, you’ll see an Options section. Within the array of checkboxes, find and click on the Test Class entry. Update the Pattern entry field to the right with a new regex.

If you are switching over to this new convention entirely:


If you want to continue to allow old-school test class names, just tack the preceding regex after an alternation character (|):


Final thoughts

“Going with the flow” and using the word “Test” in your class names works just fine. But doing so represents one more subtle bit of emphasizing the wrong things. In TDD, it’s better to think about “describing behavior” than “writing tests for a bunch of methods.”

I don’t really know anyone other than myself who uses this convention. I first described it in Modern C++ Programming With Test-Driven Development, from 2013. I haven’t done a lot of C++ after that book came out, though, so I don’t know if anyone adopts it. It works great for my personal stuff, and allows me to be a bit of a pedant.

Whatever. If you like it, try it.

If you choose to adopt the standard, let me know how it turns out.


  1. 1: Currently the 3rd edition of Prag Unit Testing is about to enter the beta period. Please contact me if you’re interested in helping provide feedback before then. 

Share your comment

Jeff Langr

About the Author

Jeff Langr has been building software for 40 years and writing about it heavily for 20. You can find out more about Jeff, learn from the many helpful articles and books he's written, or read one of his 1000+ combined blog (including Agile in a Flash) and public posts.