Jest: Consider allowing test suites to be defined programmatically.

[wtgtybhertgeghgtwtg]

Do you want to request a feature or report a bug?
Feature.
What is the current behavior?
One and only one test suite is created per file.
If the current behavior is a bug, please provide the steps to reproduce and either a repl.it demo through https://repl.it/languages/jest or a minimal repository on GitHub that we can yarn install and yarn test.

What is the expected behavior?
From the docs

describe(name, fn) creates a block that groups together several related tests in one "test suite". For example, if you have a myBeverage object that is supposed to be delicious but not sour, you could test it with:

However, a "test suite" defined by describe is not actually a test suite. Running

// example.test.js
describe('Suite One', () => {
  // Do tests
});

describe('Suite Two', () => {
  // Do tests
});

will only result in one suite. This can be a problem, as parallelism in jest is by suite, and therefore by file; if I have a single example.test.js, it won't run anything in parallel.
Example Repo: https://github.com/wtgtybhertgeghgtwtg/jest-suite-example
Please provide your exact Jest configuration and mention your Jest, node, yarn/npm version and operating system.
[email protected]
[email protected]
Windows 10

[cpojer]

In Jest, we actually call a file a test suite. We aren't using the Jasmine terminology. For us, "describe" doesn't mean anything, it is just a way to group together things.

[gentunian]

@cpojer then it would be nice to document that you consider a file a test suite and not describe()

From docs

describe(name, fn) creates a block that groups together several related tests in one "test suite".

It's confusing. It's so that I had to google why I wasn't able to create multiple test suites defining multiple describe()s and google took me here.

[rickhanlonii]

This:

describe(name, fn) creates a block that groups together several related tests in one "test suite".

Seems to read to me the same as:

describe(name, fn) creates a block that groups together several related tests in one file.

But if you have suggestions on how to clarify the docs @gentunian, I'm happy to review a PR!

[dastewa]

My apologies for chiming in on a closed issue, but I spent a bit of time today trying to figure out why jest-junit wasn't reporting each describe block as it's own test suite. In the end the author pointed out that jest considers each _file_ a test suite, not each _describe block_ - this was really good to know.

I have to agree with @gentunian that this is really unclear from the docs. I've even come across a few blog posts that have and share the same misunderstanding. Although it looks like the wording around describe has changed to be much more clear since this issue. The other describe* documentation, like describe.each, still seem to conflate the ideas of describe blocks and test suites.

Eg.

Use describe.each if you keep duplicating the same test suites with different data. describe.each allows you to write the test suite once and pass data in.

But from what I'm understanding, describe has nothing to do with writing/defining a test suite. It's just about grouping tests within a test suite (test file).

Again to @gentunian's point, I haven't been able to find anywhere in the docs that explicitly states that a test suite is a test file... unless I've just missed it. Happy to take a stab at adding that little detail somewhere if it's not in the docs already though :).