Document how parallelization works in Jest

🚀 Feature Proposal

A piece of official documentation stating exactly how parallelization works in Jest, including whether it’s safe to assume that all suites and test cases within a single file will always run serially in source order.

Motivation

It is basic information that should be officially documented.

Pitch

I’ve searched online for answers to this, and I can only find equivocal Stack Overflow threads and disagreement. From experimenting, I think it works like this:

• Individual files are run in parallel (unless you enable the runInBand option). So it is not safe for multiple test files to share a mutable data store.
• All describe and test blocks within a file always run in serial, in declaration order. So you can safely mutate a module-scoped variable across several tests with predictable results (even when some tests are nested more deeply than others in describe trees). This can be useful when testing a series of mutations to a piece of state.

That’s how Jest seems to work today. But I want to see docs stating if that’s the intended behaviour, so I can be sure it won’t suddenly change without warning in a minor performance update.

[andreabisello]

So the only way to runs tests in parallel way is to create one testsuite (one file) for every test? i thought jest tries always to runs test in a parallel way if --runInBand is not set, but making a try it looks like it runs in parallel testsuites, not tests.

You can understand the suites are running in a parallel way because the command prompt

say RUNS a lot of file together

even if you put more test in a file (a testsuite) they are runned sequentially both they are in a describe block or N describe block :

i make this experiment : every test wait 5000ms before ends

in a single describe block, it tooks more than 10 000 ms to ends

describe('describe block 1', () => {

    test("1", async () => {
        await new Promise(resolve => setTimeout(resolve, 5000));
        expect(1).toBe(1)
    })

    test("2", async () => {
        await new Promise(resolve => setTimeout(resolve, 5000));
        expect(1).toBe(1)
    })

})

splitting in two describe block,

describe('describe block 1', () => {

    test("1", async () => {
        await new Promise(resolve => setTimeout(resolve, 5000));
        expect(1).toBe(1)
    })


})

describe('describe block 2', () => {

    test("2", async () => {
        await new Promise(resolve => setTimeout(resolve, 5000));
        expect(1).toBe(1)
    })

})

nothing changed

splitting in two different files, they runs in a parallel way (there are 3 seconds of overhead)

but i don’t like so much to put one test in one file , because it’s very time consuming. what i’m doing wrong?

thanks.

[Luanf]

Finished a first attempt at #7984 I also added some information regarding test executing order which I thought made sense to be in the same place as the parallelization topic. Would be glad to have some feedback on this, I’m unsure if I modified the correct places. 😄