📝 Docs: No documentation on third party reporters example

[patrickptm]

I am attempting to build a custom third party reporter and I am using the simple example presented on this page : https://github.com/mochajs/mocha/wiki/Third-party-reporters. However, I cannot find any wiki or a simple explanation of how everything works.
Questions :

1. Is the "test" parameter in the runner.on function a .js file containing the tests?
2. If test is not the file containing the tests, how can I supply one?
3. How do I run this reporter? Can I do something similar to "mocha testreporter.js" and it would know to check my test files?
4. How do I include my test reporter in my existing project? Do I need to add it in the package.json? I do not want to publish it on npm, only to use it in my project.

What I am trying to achieve:

-> I need a simple custom test reporter which, based on my tests, can give me back the number of tests which have passed/failed / or a percentage. My plan would be to render my own html based on these results. For this reason, I am not interested in the already existing html test reporters, as I do not want to include error messages etc.

[ScottFreeCode]

We definitely need better documentation on this.*

To answer your immediate questions as best I can off the top of my head:

4: Mocha searches for the specified reporter in three places:

• Mocha's built-in reporters
• packages in node_modules
• local files (I don't know if this is documented, but it ought to be)

3: You select a reporter via the --reporter or -R option, e.g. mocha --reporter myReporter or mocha --reporter myReporter.js. (The option is also listed in the output of mocha --help, although I don't know if that mentions using third-party reporters.)

2/1: The pass, pending and fail events should provide a test object containing, among other things:

• the test title and a fullTitle() function that will return the title including the suites' titles
• the test body (the source of the test function)
• the test file path

Additionally, if your reporter's constructor performs Base.call(this, runner) where Base is either require("mocha/lib/reporters/base") or require("mocha").reporters.Base, in the end event you can use this.stats to get a total of passes, failures etc. (However, you can fairly easily recreate the code that tracks those, by imitating the base reporter's source.)

I'd also recommend taking a look at Mocha's built-in reporters' sources, including the base one (from which the others inherit common functionality), for more examples of what can be done.

---

* Quoting a recent reply of mine to a similar question on Gitter:

You can double-check the GitHub Wiki, but off the top of my head all I know of is the source code for Mocha's built-in reporters (even the JSDoc isn't likely to be of much use as far as I'm aware since the important stuff is mostly via emitted events and not function signatures), and the investigation that https://github.com/js-reporters/js-reporters did into Mocha's behavior. It's definitely part of Mocha that needs better documentation to be added to the official site (along with improving said site so it's part of the main repo and can be split up into multiple pages; e.g. if it were multiple files in a docs folder it'd be readable in the source offline too).

[mark-wiemer]

@JoshuaKGoldberg just want to confirm if this is still accepting PRs as it's been a while, would be happy to help out with this one :)

[JoshuaKGoldberg]

Good question, thanks for checking @mark-wiemer! Yes, this is still valid 👍. I think for now, sending an edit to https://github.com/mochajs/mocha/wiki/Third-party-reporters would be the right next step.

[mark-wiemer]

@JoshuaKGoldberg just an FYI, doesn't look like there is any review process in place for edits to the wiki. I tried cloning the repo locally but got some errors as filenames have colons in them, which Windows doesn't like. I'm going to go ahead and make small changes without pinging, and I'll let you know when I make a big update (I'll mark it as "experimental" for viewers).

I'll open a separate issue for my inability to clone the wiki repo

[mark-wiemer]

Quick FYI, I'm still here! Just had to go away for 40 days for the holidays, it was a wild time but I'm back and still gonna look into this one when I give myself some Mocha time :)

[mark-wiemer]

See also https://mochajs.org/api/tutorial-custom-reporter from https://github.com/mochajs/mocha/blob/main/docs/api-tutorials/custom-reporter.md