[Docs]: describe usage of the seed option within jest, mention test ordering

[jzaefferer]

Page(s)

https://jestjs.io/docs/cli#--seednum

Description

https://jestjs.io/docs/cli#--seednum describes the CLI seed option, but only mentions it's usage within getSeed (with a link to https://jestjs.io/docs/jest-object#jestgetseed ).

As far as I can tell, the seed option is also used to initialze the shuffle that applies to children of a describe block here:

jest/packages/jest-circus/src/run.ts

Lines 88 to 90 in 654dbd6

	if (rng) {
	describeBlock.children = shuffleArray(describeBlock.children, rng);
	}

If that is correct, it would help a lot to mention that test flakyness might be related to this shuffling, and reusing the same seed of a failed run can help reproduce that failure.

[SimenB]

Good point! Wanna send a PR with this addition?

[jzaefferer]

Yeah, I would do that, though I still need some clarification. I've only now noticed the randomize option: https://jestjs.io/docs/cli#--randomize Which does mention seed, too.

Since randomize is an option, does it mean this shuffling is disabled by default?

If so, should a random seed (not setting it explicitly) make any difference if randomize isn't used?