List all mocha tests without executing them

Question

Is there a way in mochajs to list all tests collected by test runner without executing them?

E.g. if there are specs that look like:

describe('First', function() {
    it('should test something', function() {
        ...
    })
});

describe('Second', function() {
    it('should test something else', function() {
        ...
    })
});

then I want to get console output similar to an output produced by test reporters, but without executing actual tests, like this:

First
    should test something
Second
    should test something else

UPD:

Currently I'm extracting all describes and its with regex, but looking for a cleaner solution.

Answer 1

The mocha-list-tests package is useful, but only works for BDD style describe() and it(), and it breaks if you .skip() any tests because it mocks it().

One way to do this yourself if you need to overcome either of those things, or get other information on the tests, is to exploit Mocha's root before() hook. This will be executed after Mocha has loaded all files but before it executes any tests, so all the information you need exists at that point.

This way, it is pretty easy to patch in a --list-only command line option to switch the behaviour of your test run without having to add or change anything else.

The key is that this in the before() hook is Mocha's Context, and the .test of that refers to the hook itself. So this.test.parent refers to the root suite. From there, you can walk down the tree of .suites arrays, and .tests arrays of each suite.

Having collected whatever you want, you have to then output that and exit the process to stop Mocha from continuing.

Plain Text Example

Given root.js:

#!/bin/env mocha

before(function() {
    if(process.argv.includes('--list-only')) {
        inspectSuite(this.test.parent, 0);
        process.exit(0);
    }
    // else let Mocha carry on as normal...
});

function inspectSuite(suite, depth) {
    console.log(indent(`Suite ${suite.title || '(root)'}`, depth));

    suite.suites.forEach(suite => inspectSuite(suite, depth +1));
    suite.tests.forEach(test => inspectTest(test, depth +1));
}

function inspectTest(test, depth) {
    console.log(indent(`Test ${test.title}`, depth));
}

function indent(text, by) {
    return '    '.repeat(by) + text;
}

And test.js:

#!/bin/env mocha

describe('foo', function() {
    describe('bar', function() {
        it('should do something', function() {
            // ...
        });
    });

    describe('baz', function() {
        it.skip('should do something else', function() {
            // ...
        });

        it('should do another thing', function() {
            // ...
        });
    });
});

Then running mocha as normal would give you the test results you expect:

  foo
    bar
      ✓ should do something
    baz
      - should do something else
      ✓ should do another thing


  2 passing (8ms)
  1 pending

But running mocha --list-only would give you (without running any tests):

Suite (root)
    Suite foo
        Suite bar
            Test should do something
        Suite baz
            Test should do something else
            Test should do another thing

JSON Example

root.js

#!/bin/env mocha

before(function() {
    let suites = 0;
    let tests = 0;
    let pending = 0;

    let root = mapSuite(this.test.parent);

    process.stdout.write(JSON.stringify({suites, tests, pending, root}, null, '    '));
    process.exit(0);

    function mapSuite(suite) {
        suites += +!suite.root;
        return {
            title: suite.root ? '(root)' : suite.title,
            suites: suite.suites.map(mapSuite),
            tests: suite.tests.map(mapTest)
        };
    }

    function mapTest(test) {
        ++tests;
        pending += +test.pending;
        return {
            title: test.title,
            pending: test.pending
        };
    }
});

With the same test script as before would give you:

{
    "suites": 3,
    "tests": 3,
    "pending": 1,
    "root": {
        "title": "(root)",
        "suites": [
            {
                "title": "foo",
                "suites": [
                    {
                        "title": "bar",
                        "suites": [],
                        "tests": [
                            {
                                "title": "should do something",
                                "pending": false
                            }
                        ]
                    },
                    {
                        "title": "baz",
                        "suites": [],
                        "tests": [
                            {
                                "title": "should do something else",
                                "pending": true
                            },
                            {
                                "title": "should do another thing",
                                "pending": false
                            }
                        ]
                    }
                ],
                "tests": []
            }
        ],
        "tests": []
    }
}

Answer 2

Wrap all your describe blocks in a describe block and skip it.

describe.skip('Outline', function() {
    describe('First', function() {
        it('should test something', function() {
            ...
        })
    });

    describe('Second', function() {
        it('should test something else', function() {
            ...
        })
    });
});