[📖 Docs]: WDIO CLI - isTTY assumption on "pipe" arguments

[yuri-scarbaci-lenio]

Pre-check

• I know I can edit the docs but prefer to file this issue

Describe the improvement

Missing documentation

Description of the improvement / report

We are running wdio via a node script invoking the CLI commands,
in our flow we use execa and husky,

due to this assumption:

webdriverio/packages/wdio-cli/src/commands/run.ts

Line 211 in 4cad544

* called immediately, otherwise piped input is processed, expecting

when using default execa behaviour with standard husky pre-push hook behaviour we have got a very hard to track bug on our side,

I would love to contribute to document this myself if someone can point me to where I should add the documentation for the WDIO CLI behaviours

more infos:

• Fix default value of stdin with $ sindresorhus/execa#550 (comment)
• https://git-scm.com/docs/githooks#_pre_push

Code of Conduct

• I agree to follow this project's Code of Conduct

[christian-bromann]

Can you explain a bit more about your issue and what documentation you like to add?

[yuri-scarbaci-lenio]

Yep, let me explain our use case for starter:
we have a combination of

• wdio (used via node invoking the CLI commands)
• execa (used to invoke wdio via cli from node)
• husky (used to hook to pre-push hook)

the way we tied up the flow this is more or less what happens:

• developer tries to push his pending work
• husky run the pre-push hook
  • in the pre-push hook we run a node scripts that loads the wdio based on some peculiar scaffolding we mounted to share the same wdio config across multiple projects
  • the node script runs the command

    execa('wdio', [ ...ourDynamicWdioFlagsLikeSpecConfigAndSuch ],  {stdio:'inherit'} )
  

case 1 - executing the node script from husky

• since this is executed from husky, stdin has a pending "pipe" from the git pre-push hook as per https://git-scm.com/docs/githooks#_pre_push

The hook is called with two parameters which provide the name and location of the destination remote, if a named remote is not being used both values will be the same.

case 2 - executing the node script manually from the developer own terminal

there is no pending "pipe", the command doesn't overwrite the config.spec

This is pretty much custom logic, what's the problem with wdio documentation then?

webdriverio/packages/wdio-cli/src/commands/run.ts

/**
     * if stdin.isTTY, then no piped input is present and launcher should be
     * called immediately, otherwise piped input is processed, expecting
     * a list of files to process.
     *
     * stdin.isTTY is false when command is from nodes spawn since it's treated as a pipe
     */

I can't find any documentation (maybe I am just not finding it myself, if that's the case please point me to the documentation where this is covered) that documents this "assumption" that the wdio - cli is making that if stdin.isTTY is false, the "pipe" must contain a list of files to process and that this behaviour can not be over-loaded even if you provide the --spec argument to the wdio cli (as in, wdio --spec *.spec.ts would still expect the "spec" to come from the pipe if any pipe is present )

I don't think that our flow is a "strange" flow to have, it makes sense to me that pre-push developers may want to run a suite of smoke e2e, and if that's the case, it also somewhat common that the tool used for this is husky, and the assumption wdio is making about the piped-in arguments is an assumption that goes against this flow by design
(pre-push hook doesn't pipe in files, it pipes in remote refs from git)

having some documentation addressing this flow may prove useful to many people,
some kind of "gotcha" section for implementing such a flow correctly
on top of having a clearly identified callout to:
- the assumption on the "pipe" that MUST be a list of file no matter what (and it can't be ignored nor overwritten explicitly)
- the spec not being over-writable via the --spec argument if stdin has a pending pipe
per

webdriverio/packages/wdio-cli/src/commands/run.ts

Line 128 in 4cad544

params.spec = stdinData.trim().split(/\r?\n/)

arguments are completely ignored when entering this launchWithStdin flow in wdio
- the assumption being based on stdin.isTTY

Please let me know what your thoughts are regarding this, if I am missing an already existing documentation and/or if further clarification is required on my side

[christian-bromann]

@yuri-scarbaci-lenio thanks for the clarification.

Yes we do not have any documentation about piping files into the WebdriverIO command. I would suggest to add a section to https://webdriver.io/docs/organizingsuites describing this workflow.

Would you like to take a stab at this since you know most about this?