Delay root suite execution on a file by file basis

[betweenbrain]

Description
As we are developing our suite of tests, we are running into the limitation/added complexity of needing to delay all test execution, via the --delay flag. In our case, we don't need to delay all tests, and in fact, only some need to delay the root suite execution to seed data via an asynchronous operations. I believe this feature request supports #3781.

Desired solution
It would be awesome if Mocha had an optional async hook that fired before the rest of the test, allowing for asynchronous operations before that test is run. For example, if this hook was named preflight, it could look something like:

preflight(async function (done) {
    await driver.get('http://example.org');
    await driver.findElements(By.css('article header a'))
        .then(async (anchors) => {
            assert.notStrictEqual(anchors, 0);
        })
    done();
})

before(async function () {
    driver = await new Builder().forBrowser('chrome').build();
});

after(async function () {
    await driver.quit()
});

describe('Google search result page title', () => {
    it('Example of successful test', async function () {
        try {
            await driver.get('http://www.google.com');
            await driver.findElement(By.name('q')).sendKeys('Guggenheim', Key.RETURN);
            await driver.wait(until.elementLocated(By.css('title')), 1000);
            await driver.getTitle().then(function (title) {
                assert.strictEqual(title, 'Guggenheim - Google Search');
            });
            await driver.takeScreenshot().then(function (image) {
                screenshot(image, '003');
            });
            await driver.sleep(1000)
        } catch (err) {
            return caught(err);
        }
    });
});

Alternatives considered
I have documented more of this in more detail at https://stackoverflow.com/questions/57929444/delay-mocha-test-programmatically, but in short, if not using the --delay flag, I can leverage asynchronous hooks to achieve a similar result as the one desired. But, the issue I am running in is that I cannot combine asynchronous hooks and dynamically generate tests. That is, instead of generating one test for each node of asynchronous data, those nodes are looped through within the single test.

[juergba]

It would be awesome if Mocha had an optional async hook that fired before the rest of the test [...]

I haven't studied your example in detail, but why don't you put this preflight in a separate before hook? It's up to you to code it in async way.

[betweenbrain]

@juergba thanks for the response. I’m not sure if I know what you mean by a separate before hook. Do you mean to use nested describes, each with this before hook would be in the outer one? Thanks!

[juergba]

With top-level await you can collect your test data in an asynchronous way, while your test file is being loaded and before the test runner is created. You need Node >= v14.8.0 and ESM test files.
There will be an example in our docs shortly => see docs.

[juergba]

closed by #4617.