Arrange Act Assert Comments in Tests

05 February 2015 (2)

The Arrange, Act, Assert (AAA) pattern is used in tests to help organise and clarify test code. It can also help to spot potential problems in test code if these three phases don’t seem to exist.

The Arrange phase is where the thing we’re testing (the system under test) is put into a known beginning state.

The Act phase is where we perform some action on the thing being tested.

The Assert phase is where we check that the results of the Act phase are as expected.

When first learning to use the AAA pattern, it can be helpful to start with 3 comments:

public void ShouldAddNumbers()
{
    // Arrange
    
    // Act
    
    // Assert

}

 

These comments can help to focus on making sure there are three distinct phases.

While these comments are useful when trying to learn (or teach) AAA, they should not be needed in the final version of the test code.

Test code should ideally be as good as production code. One of the things that qualifies code as “clean” is the absence of useless/pointless comments.

Test code should be easy to read, it should not need the AAA comments to be left in to be able to be understood.

If you are using the comment-first approach to help you get started and learn the AAA approach that’s all well and good. However, once the test is written, these comments should usually be removed before the code is committed to source control.

Once the AAA comments are removed, it should still be clear what the flow of the test is. If it is not then the test code may need some changes to improve the readability.

SHARE:

Comments (2) -

  • Paweł Grudzień

    3/5/2015 5:18:01 PM | Reply

    Hi Jason,

    although I agree with having pointless like "iterate over collection" comments in code does more bad than good I do not agree that AAA match this category and should be removed.

    In my opinion they serve more than one purpose. They help visually navigate through tests. Every IDE displays comments in different color so it is easy to distinguish code from comments. Although code should be simple enough to understand what is being tested having additional information helps. This is especially true when you use mocking framework that can obscure code.

    Another value AAA comments brings is less obvious. When your team consists of less experienced people it always helps them to remember how test code should be arranged. People always tend to write code on some basis and if you leave AAA in production code then fellow developers will follow your style of coding. This way you spend less time to teach or remind to new members how good code should look like.

  • David Wallace

    9/4/2018 6:00:52 AM | Reply

    I firmly agree with Paweł .  Readability is a really important attribute of any kind of code, including unit test code.  When I look at someone else's test code for the first time, or even at my own code after a few months, the first thing I want to know is what's being tested.   I don't want to have to scan through lots of code to find the "Act" part.  If there's a comment there that highlights it, my eyes will jump straight to the "Act", and this helps me understand the test.

    So please, leave your Arrange, Act and Assert comments in place when you commit / push  your tests to source control.  The next developer to look at your tests will thank you for it.

Pingbacks and trackbacks (1)+

Add comment

Loading