Skip to content
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

@akrawchyk
Copy link
Contributor

@akrawchyk akrawchyk commented Apr 23, 2018

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

Copy link
Member

@boneskull boneskull left a comment

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 akrawchyk force-pushed the akrawchyk:issue/3136 branch from b3ead36 to d7bb015 Apr 24, 2018
@akrawchyk
Copy link
Contributor Author

@akrawchyk 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
Copy link

@coveralls 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
Copy link
Contributor Author

@akrawchyk akrawchyk commented Apr 26, 2018

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

@akrawchyk akrawchyk force-pushed the akrawchyk:issue/3136 branch from 67a1b18 to 46ff6c2 Apr 26, 2018
@outsideris
Copy link
Member

@outsideris outsideris commented Apr 26, 2018

hmmm.. Why did builds failed for this PR?

@outsideris
Copy link
Member

@outsideris outsideris commented Apr 26, 2018

Aha! The failure is related with this.

@akrawchyk akrawchyk force-pushed the akrawchyk:issue/3136 branch from 46ff6c2 to babdf1e May 1, 2018
@akrawchyk
Copy link
Contributor Author

@akrawchyk 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

Copy link
Member

@outsideris outsideris left a comment

LGTM

@boneskull boneskull force-pushed the mochajs:master branch 2 times, most recently from 4547268 to 7613521 May 4, 2018
@akrawchyk
Copy link
Contributor Author

@akrawchyk akrawchyk commented May 12, 2018

@boneskull do you have more feedback on this?

@akrawchyk
Copy link
Contributor Author

@akrawchyk 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
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
Copy link
Member

@outsideris 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
Contributor

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
Author 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
Contributor

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
Contributor

In this example, the glob is unnecessary.

$ mocha --recursive spec
sgilroy pushed a commit to TwineHealth/mocha that referenced this pull request Feb 27, 2019
…#3136 (mochajs#3348)

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

* requested changes

* add explanation for recursive matching for different shells
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

5 participants