Rant-driven Development

Python TDDers: Can we please, as a group, stop doing this:

class MyFunctionTestCase(TestCase):
    """Tests for MyFunction."""

    def test_does_thing_correctly(self):
        # given
        <setup code>

        # when
        <do some stuff>

        # then
        <assert some stuff>

Pretty please? It violates what I'm going to call Binns's First Principle of TDD, which is:

Do not make me read the test to work out what it is testing.

To not violate Binns's First Principle, a test should:

Thus:

class MyFunctionTestCase(TestCase):
    """Tests for my_function()."""

    def test_returns_true_when_moon_is_aligned_with_stars(self):
        # When the moon is aligned with the stars in the constellation
        # of Kasterborous, my_function() will return True.
        <do setup>
        self.assertTrue(my_function())

Note that the comment isn't required (though it is preferred) if — and only if — the expected behaviour can be easily encapsulated in the test title.

Your tests will violate Binns's First Principle of TDD IF:

That's it, rant over. On with your day. Thanks.