New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update docs with globbing and shell expansion details; closes #3136 #3348

Merged
merged 3 commits into from Jun 29, 2018

Conversation

Projects
None yet
5 participants
@akrawchyk
Contributor

akrawchyk commented Apr 23, 2018

Add documentation around shell expansion and globbing for passing files to mocha

@boneskull

boneskull requested changes Apr 23, 2018 edited

Thanks for this! I have a suggestion.

Also, these changes failed the Markdown lint. run npm start lint.markdown to check the Markdown locally.

$ mocha ./spec/*.js
```
If you use shell expansion for this, you must wrap your glob pattern in double quotes (note, using the `--recursive` flag here is useless):

This comment has been minimized.

@boneskull

boneskull Apr 23, 2018

Member

A lot of people probably doesn't know what "shell expansion" is.

In fact, I would probably remove L1279-1283 and just give the example below with double quotes. Then, explain below the example how using ** means --recursive is useless. Recommend using double quotes for "portability"; otherwise it'll need a pretty long-winded explanation.

@akrawchyk

This comment has been minimized.

Contributor

akrawchyk commented Apr 24, 2018

@boneskull I made the updates you recommended, except for "using ** means --recursive is useless". I think we might need to mention shell support/differences for the ** glob, otherwise these changes could be confusing.

The lines above my changes read:

...since ./test/*.js only matches files in the first level of test and ./test/**/*.js only matches files in the second level of test.

This is true by default in Bash, but the globstar option was introduced in Bash 4.3 (so you need a recent version just to use this) and must be enabled for ** == --recursive:

screen shot 2018-04-24 at 9 50 32 am

I believe ZSH and Fish support recursive matching for ** by default.

edit: added example

@coveralls

This comment has been minimized.

coveralls commented Apr 24, 2018

Coverage Status

Coverage increased (+0.05%) to 90.054% when pulling babdf1e on akrawchyk:issue/3136 into 1606f35 on mochajs:master.

```sh
$ mocha "./spec/**/*.js"
```

This comment has been minimized.

@outsideris

outsideris Apr 24, 2018

Member

I didn't know about the globstar in Bash 4.3.
I feel that current explanation is a little bit confused. If we explain the globstar explicitly, users can understand clearer because the behavior of ** is depend on a shell.

@akrawchyk

This comment has been minimized.

Contributor

akrawchyk commented Apr 26, 2018

@boneskull @outsideris I've updated the changes to reflect your feedback, please give it another look when you can!

@outsideris

This comment has been minimized.

Member

outsideris commented Apr 26, 2018

hmmm.. Why did builds failed for this PR?

@outsideris

This comment has been minimized.

Member

outsideris commented Apr 26, 2018

Aha! The failure is related with this.

@akrawchyk

This comment has been minimized.

Contributor

akrawchyk commented May 1, 2018

@outsideris @boneskull I rebased from develop with the CI fixes, let me know if you need me to adjust anything else

@outsideris

LGTM

@akrawchyk

This comment has been minimized.

Contributor

akrawchyk commented May 12, 2018

@boneskull do you have more feedback on this?

@akrawchyk

This comment has been minimized.

Contributor

akrawchyk commented Jun 28, 2018

@boneskull @outsideris let's get this merged! (please 😄 )

@outsideris outsideris merged commit 59d5850 into mochajs:master Jun 29, 2018

6 checks passed

continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
coverage/coveralls Coverage increased (+0.05%) to 90.054%
Details
deploy/netlify Deploy preview ready!
Details
licence/cla Contributor License Agreement is signed.
Details
security/snyk No dependency changes
Details
@outsideris

This comment has been minimized.

Member

outsideris commented Jun 29, 2018

Thank you.

@akrawchyk akrawchyk deleted the akrawchyk:issue/3136 branch Jun 29, 2018

@boneskull boneskull added this to the v6.0.0 milestone Nov 5, 2018

$ mocha "./spec/**/*.js"
```
*Note*: Double quotes around the glob are recommended for portability.

This comment has been minimized.

@plroebuck

plroebuck Nov 13, 2018

Member

Disagree with this statement.
If you want portability, then single quotes are required; using double quotes allows possibility of shell expansion, etc. Using single quotes tells the shell "hands off", and Mocha's lookupFiles would handle the glob expansion.

This comment has been minimized.

@akrawchyk

akrawchyk Nov 13, 2018

Contributor

@plroebuck thanks for the feedback. My understanding is that glob expansion would only happen when using parameter expansion inside double quotes, see https://www.gnu.org/software/bash/manual/html_node/Shell-Parameter-Expansion.html#Shell-Parameter-Expansion.

FWIW the context for specifying double quotes is here #3136 (comment).

This comment has been minimized.

@plroebuck

plroebuck Nov 13, 2018

Member

Yes, you're correct that double quotes are required if you want the shell to do the job. Perhaps I misunderstood the intent of this update, assuming it was to explain how to target files recursively (via glob) in general. While knowing how to do this via UNIX shell is useful (but unnecessary here), the portable recommendation would be to use single quotes, sidestepping platform differences and characteristics of various shells with various options disabled/enabled.

To configure where `mocha` looks for tests, you may pass your own glob:
```sh
$ mocha --recursive "./spec/*.js"

This comment has been minimized.

@plroebuck

plroebuck Nov 13, 2018

Member

In this example, the glob is unnecessary.

$ mocha --recursive spec
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment