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

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

Copy link
Contributor

@boneskull boneskull left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this! I have a suggestion.

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

docs/index.md Outdated
$ 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):
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@boneskull boneskull added area: documentation anything involving docs or mochajs.org semver-patch implementation requires increase of "patch" version number; "bug fixes" labels Apr 23, 2018
@akrawchyk
Copy link
Contributor Author

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 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.

docs/index.md Outdated

```sh
$ mocha "./spec/**/*.js"
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

@outsideris
Copy link
Contributor

hmmm.. Why did builds failed for this PR?

@outsideris
Copy link
Contributor

Aha! The failure is related with this.

@akrawchyk
Copy link
Contributor Author

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

Copy link
Contributor

@outsideris outsideris left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

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

@boneskull do you have more feedback on this?

@akrawchyk
Copy link
Contributor Author

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

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

Thank you.

@akrawchyk akrawchyk deleted the issue/3136 branch June 29, 2018 14:59
@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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@akrawchyk akrawchyk Nov 13, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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).

Copy link
Contributor

@plroebuck plroebuck Nov 13, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Labels
area: documentation anything involving docs or mochajs.org semver-patch implementation requires increase of "patch" version number; "bug fixes"
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants