Mocha’s Grep Flag

Mocha’s grep flag (-g, or --grep) is amazing. I very recently learned about this helpful tool, and it’s significantly improved my testing workflow.

The grep flag gives you the ability to focus on specific tests with zero code changes, even if the set of tests you want to run are spread across separate describe blocks!

I recently found myself in a situation where an ugly, manual process of zeroing in on tests was drastically simplified with the grep flag.

The Situation

One of my client projects has a very large, very complicated Mocha test suite. Many of the tests in this suite are generated programmatically (whether or not this is a good idea is a topic for another day…).

One of the motivations for generating tests dynamically is that we have multiple “transports” (Twilio SMS, Facebook Messenger, web chat, etc…) for communicating with users. On each of these transports, we want to run through a set of test scenarios and ensure that they all behave as expected:


[
    "twilio",
    "facebook",
    "web"
].forEach((transport) => {
    describe(`Scenarios for ${transport}:`, function() {
        it("sends a message", function() {
            ...
        });
        ...
    });
});

Sometimes, it’s helpful to see just the output of these transport scenario tests instead of the output of the entire test suite.

My initial instinct for zeroing in on these transport scenario tests is to change describe to describe.only. Unfortunately, if Mocha finds multiple describe.only calls, it will only run the tests in the last describe.only block it encounters. This means that only my "web" transport tests would run.

To see the results of all three transport tests, I’d have to run my tests in three passes, once for each transport:


[
    "twilio",
    // "facebook",
    // "web"
].forEach((transport) => {
    describe.only(...


[
    // "twilio",
    "facebook",
    // "web"
].forEach((transport) => {
    describe.only(...


[
    // "twilio",
    // "facebook",
    "web"
].forEach((transport) => {
    describe.only(...

This is not a good solution.

This kind of code juggling opens the doors for bugs to be introduced into my test suite and makes it impossible to watch all three transport tests at once.

Mocha Grep

It turns out that Mocha already has a solution to my problem.

If you read through the Mocha documentation, you may notice a section on the “grep flag” (-g, or --grep):

-g, –grep <pattern> only run tests matching <pattern>

When using this flag, Mocha will search through your tests and only run tests whose descriptions match the provided pattern. This means we can run our whole test suite and grep for "Scenarios" tests:


mocha -g "Scenarios for"

And just like that, our "twilio", "facebook", and "web" transport scenarios are detected and run by Mocha.

We can get more complex with our search. Let’s run just the "twilio" and "web" scenarios:


mocha -g "Scenarios for twilio|Scenarios for web"

We can even use the watch flag (-w, or --watch) to watch the results of our test search for changes:


mocha -w -g "Scenarios for twilio|Scenarios for web"

Final Thoughts

It’s always a good idea to thoroughly read the documentation of all of the tools you use on a regular basis.

You may be surprised to find that they’re much more powerful than you first realized.

TL;DR: RTFM.

Mocha's Grep Flag

The Situation

Mocha Grep

Final Thoughts