Add reporter options example

[pkuczynski]

Description of the Change

I tried to add reporter options as reporterOptions or reporterOption and failed miserably for quite a while until I accidentally found out that it needs to be specified like in the example below.

Benefits

I think it's worth adding an example to the documentation to save other people's time.

[outsideris]

We know you spent your time to figure this out, but this example configs aren't for explaining every option.
--reporter-option for XUNIT already described in our docs.

[pkuczynski]

I know that, but what was surprising for me was the format. I was expecting to pass params like:

reporterOptions: {
     suiteName: "My Tests",
     output: "./build/tests.xml"
}

like its displayed across all the documentation, while instead, mocha expected this:

'reporter-options': [
     'suiteName="My Tests"',
     'output=./build/tests.xml'
   ],

This was very confusing for me and I guess it would be good to have it in those examples. Especially your other examples are much larger: https://github.com/mochajs/mocha/blob/master/example/config/.mocharc.yml

I can change the example to be more generic like in .mocharc.yml with foo, bar..

What you think?

[pkuczynski]

@juergba @tj @boneskull what do you think?

[juergba]

IMO it is rather confusing, see eg. #4142.
In our configuration files reporter-option has to be an array. When passing it directly to the Mocha constructor, then it is an object.

[pkuczynski]

My point exactly! There is no clear documentation about it, or at least I could not find it. However there is plenty documentation for passing an object to the constructor.

That’s why I strongly believe that adding example from this PR would help people...

Validation of mocharc structure would help too, but that’s a separate topic...

[outsideris]

I understood what @pkuczynski pointed out. And I realized our .mocharc.yml is much verbose than others.
reporter-option is Array but each value is not same type with other Array type options. Therefore, IMO it is helpful for mocha newbies.

[outsideris]

IMO, if we add this in our configuration examples, we should add them into .mocharc.json and .mocharc.jsonc as well not only .mocharc.json.

[pkuczynski]

I can do that tonight if you want?

[pkuczynski]

I just updated my PR to align with .mocharc.yml. The only thing I noticed is that .mocharc.js had package property which .mocharc.yml does not. Not sure if this is a bug?

[juergba]

@pkuczynski Thank you, I have some comments.

• none of your commits did pass our CI tests
• use the canonical option name reporter-option instead of its alias
• there is no need to align with .mocharc.yml, please revert this change
• .mocharc.js: your first commit is ok, just watch out for the option name and linting errors
• .mocharc.json: align with .mocharc.js. Please remove the four comment lines
• .mocharc.jsonc: align with .mocharc.js
  • remove // Camel-casing options are also accepted. The parsing of camel-cased option is buggy in certain edge cases.
  • change watchFiles to watch-files
  • change watchIgnore to watch-ignore

[pkuczynski]

I have not modified anything else than example/config/.mocharc.js. Possibly I misunderstood @outsideris comment and added all options from yaml to json. I personally feel that having all options would make it easier for newbies to understand. Please confirm if I should revert and stick to the simple version was here before?

I suggest updating other files in a separate PR once we align on .mocharc.js

[coveralls]

Coverage remained the same at 94.155% when pulling 491c6bc on pkuczynski:patch-1 into 21652d9 on mochajs:master.

[pkuczynski]

Build is finally green now :)

[boneskull]

thanks!!

[outsideris]

I suggest updating other files in a separate PR once we align on .mocharc.js
Agreed.

IMO there isn't any reason we don't align with yaml for js.
Thank you.

[boneskull]

@juergba can you pls confirm your comments have been addressed; if so please merge

[boneskull]

and by merge i mean "squash"

[Niceplace]

Hi folks ! Just checking in to say that this PR helped me understand how reporter-options parameter should be structured because it was not initially clear to me.

Any plans to merge this soon ? I think it could help a lot of people.

Cheers ! :)