docs(testing): document how to pass in Jest CLI arguments

[christian-bromann]

Based on a question we've received in stenciljs/core#5225 (reply in thread) I think it is worth to document this.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
stencil-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jan 11, 2024 9:24pm

[rwaskiewicz]

@alicewriteswrongs are there any cases that you know of where Stencil overrides Jest configuration flags? IIRC, there is some overlap between certain options, but I'm unsure if they're worth calling out here due to functional differences

EDIT: Forgot the link https://github.com/ionic-team/stencil/blob/79dc0159d216824d623e34f814dfeb32474a1550/src/cli/config-flags.ts#L42

[alicewriteswrongs]

The Jest config is built here: https://github.com/ionic-team/stencil/blob/main/src/testing/jest/jest-29/jest-config.ts#L12

It will use both knownArgs (which are arguments that Stencil supports and recognized) as well as all positional arguments passed at the comment line (e.g. a filename pattern as shown in the change made in this PR) in order to generate a Jest config.

I believe that given the way the command-line arguments are marshalled before they're passed to Jest any Jest arguments that are passed should be passed through without Stencil editorializing them. Some of those Jest arguments may just also have a side-effect of setting a particular Stencil configuration value

[alicewriteswrongs]

also strictly speaking the -- is not for passing in jest CLI flags, but rather positional arguments like the filename pattern. We support all of hte Jest CLI flags as Stencil CLI options, those are enumerated here: https://github.com/ionic-team/stencil/blob/54d4ee252768e1d225baababee0093fdb0562b83/src/cli/config-flags.ts#L38-L85

Our parser will set all of those on the ConfigFlags object that we create during CLI argument parsing, but only the really Stencil-specific options will have an effect on the Stencil config for a project when it's building

[christian-bromann]

@alicewriteswrongs thanks for the insights. I updated the patch to reflect what you are describing, does it make sense? Do you see anything missing we should mention?