I come from a python background. I typically write long unit test descriptions that link the test to a user story. The test is as much about justifying why the code exists and how it fits into the larger system as it is about testing for correctness. As such my tests often have about as much docstring text as test code.

In javascript it's more typical to use the describe and it syntax. Something like Describe makeFoo - it should return a foo. I don't see many long descriptions. This works fine for TDD but I get less sure on where to document why the code exists in the first place. Why does makeFoo return foo seems more important me than if it does in fact return a foo.

Does anyone have advice or examples for what makes a good javascript test description? Should I just move my user stories outside the test? Write them only on integration tests? Add really long describe strings? Or am I missing some greater point about this style of testing?

  • 3
    "50% of text is comments" is a good rough target regardless of language or kind of code. Keep in mind, good names can and should minimize the need for comments. Never explain with a comment what you can explain with clearer code. Don't think you should comment every line of code. NEVER saddle code with comments that mean the code can't be refactored without changing the comments. Remember that test code is also code. Comments should be about WHY the code does what it does. Not how. Talk about user stories whenever the code is ABOUT the user story. Dec 16, 2017 at 18:42
  • If your user stories are of the form "Given state, when action, then result", that maps directly onto an "Arrange, Act, Assert" style test. If all that differentiates the text of the user story from the text of the test is some extra punctuation, you don't need comments.
    – Caleth
    Dec 19, 2017 at 10:38

2 Answers 2


Note that if you're perfectly happy with the style of descriptions you used to write in Python, there is no reason to change that. Put the name of the tested block within the describe, and put your description in it. If it's clear for you, it doesn't matter what the designers of the test framework had in mind.

If you're for some reason unhappy with porting your style to JavaScript, then stick with it('should do this or that'), and just below it, include the complete description:

describe('the ruler', () => {
    describe('after a double-click', () => {
        it('should reflect the cursor position instead of assuming a (0, 0)', () => {
             * The edge case documented in CAP-621 happens when a user, instead of simply
             * clicking once to position the first side of the ruler, and then click
             * another time somewhere else to fix the ruler on the page, double-clicks on
             * the page. The previous behavior was that the ruler was drawn from the cursor
             * to the (0, 0) of the page. Instead, a double-click should be treated as if
             * it was a simple click, letting the user to position the other side of the
             * ruler with another click or double-click.

When reading a test, for instance in the context where a change in the code broke it, either you'll understand its purpose just by looking at its name, or you'll read the long comment. This style may even be preferable to having only the long description: if the test is recent or if it concerns a part you were working on recently, chances are, you won't need the whole description, and having a short name would save you time.


I would not talk about user stories within the comments. From my perspective you have a couple of ways to approach this:

  1. Create a separate unit testing document. This should describe each test: inputs, expected behavior, assertions (expect(foo) to be string), outputs and log locations. If you go this route you can add what function or code the test is testing, any connections to other code, and your user story if desired.

  2. Add testing descriptions in the comments. Include a description, the expected behavior and assertions. Just keep it brief. For example:

    describe('add new account')
     //module adds new account and include nested "describe" as needed
     describe('create new db row')...
     // specify expected behavior
     it('adds new new row in account db') ...
     expect 'accountid' to be integer;
     expect 'account_name' to be string; ...

(Please note, I am not experienced with Javascript, so not all the syntax may be correct. This is to show the concept of adding testing descriptions.)

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.