Add some working examples #1

craigtaub · 2019-03-14T22:19:55Z

Description of the Change

Added working examples for a couple of common configurations. More to come.

This includes

programmatic usage
react, webpack
basic typescript
basic babel
third party reporter

Decided to include .gitignore so we can expand the examples where necessary.

I will start adding links to Mocha's docs to link here.

Alternate Designs

More complex examples? - i decided it was best to start simple and focus on the setup, easier to expand after that.

Benefits

help contributors quickly setup scenario to debug (quick way to confirm a bug),
help users have up-to-date examples of multiple given setups
can be used to demonstrate common and complex functionality

plroebuck · 2019-03-15T22:53:37Z

programmatic-usage/index.js

+  reporter: 'list'
+});
+
+// specify a non-default directory.


// Use non-default Mocha test directory.

plroebuck · 2019-03-15T22:56:45Z

programmatic-usage/index.js

@@ -0,0 +1,26 @@
+var Mocha = require('mocha');


Move this line (Mocha) after the other two requires.

babel/package.json

third-party-reporter/package.json

plroebuck · 2019-03-15T23:00:14Z

third-party-reporter/src/my-reporter.js

+var mocha = require('mocha');
+module.exports = MyReporter;
+
+function MyReporter(runner) {


function MyReporter(runner, options) {

plroebuck · 2019-03-15T23:04:53Z

third-party-reporter/src/my-reporter.js

@@ -0,0 +1,23 @@
+// my-reporter.js
+var mocha = require('mocha');


var Mocha = require('mocha'); var Base = Mocha.reporters.Base;

plroebuck · 2019-03-15T23:05:15Z

third-party-reporter/src/my-reporter.js

+module.exports = MyReporter;
+
+function MyReporter(runner) {
+  mocha.reporters.Base.call(this, runner);


Base.call(this, runner, options);

plroebuck · 2019-03-15T23:05:41Z

third-party-reporter/src/my-reporter.js

+function MyReporter(runner) {
+  mocha.reporters.Base.call(this, runner);
+  var passes = 0;
+  var failures = 0;


plroebuck · 2019-03-15T23:07:45Z

third-party-reporter/src/my-reporter.js

+  });
+
+  runner.on('end', function() {
+    console.log('end: %d/%d', passes, passes + failures);


console.log('end: %d/%d', runner.stats.passes, runner.stats.tests);

typescript/package.json

programmatic-usage/package.json

plroebuck · 2019-03-15T23:15:00Z

react-webpack/.mocharc.js

+  reporter: 'spec',
+  slow: 75,
+  timeout: 2000,
+  spec: 'tests/**/*.spec.js',


Again with the nonstd test directory?

Think trying to demonstrate too many things at once. Will remove and keep it simple.

react-webpack/package.json

react-webpack/webpack.config.js

plroebuck · 2019-03-15T23:19:12Z

react-webpack/README.md

+
+- [babel](https://babeljs.io/) - transpilation
+- [enzyme](https://airbnb.io/enzyme/) - React component testing library
+- [chai](https://www.chaijs.com/api/assert/) - assertion library


Consider adding JSX src and test files to the mix

Wasnt sure what you meant here, added a link for jsx, let me know if thats not right.

Not sure what was unclear -- create two JSX files, one src and one test.
Make the example use them.

Sorry im still confused. I have jsx in both my src files, and a small bit of jsx in my test.
Could you explain a bit more please? It might help to explain the purpose of it? I'm just covering a basic component and it's text currently. Do you want it to do more?

I contributed to that confusion, I'm sure (no JSX experience). Rephrased, files containing JSX content should have ".jsx" extension. Having done recent user troubleshooting on something similar, would like example to have both "pure" JS file as well as JSX file. This will need Mocha's "extension" option to be ["js", "jsx"], I believe. Nice if we could also have "test/**/*.spec.js[x]" (again, one of each).

AFAIK the Facebook team itself is keen that js should be the only extension no matter what is in the file facebook/create-react-app#87 (comment). I have not seen a jsx extension in a long while personally.
I feel if we are aiming for best practices we should keep away from a .jsx extension.
Thoughts?

plroebuck · 2019-03-15T23:22:07Z

third-party-reporter/test/index.spec.js

+
+describe('Third party reporter usage suite', () => {
+  it('should equal true', () => {
+    equal(true, true);


Consider creating "test/unit/" and putting this there.
Create "test/e2e/" and create a spec that actually runs the reporter.

Have had a go at this. If you can see a cleaner way to do pls let me know.

typescript/package.json

plroebuck · 2019-03-20T06:45:17Z

typescript/package.json

+  "description": "Typescript example",
+  "scripts": {
+    "test": "mocha",
+    "compile": "tsc"


"lint": "tslint --project tsconfig.json",

plroebuck · 2019-03-20T06:46:15Z

typescript/package.json

+  "description": "Typescript example",
+  "scripts": {
+    "test": "mocha",
+    "compile": "tsc"


Order scripts lexically

plroebuck · 2019-03-20T06:51:51Z

typescript/package.json

+    "@types/mocha": "^5.2.6",
+    "assert": "^1.4.1",
+    "mocha": "^6.0.0",
+    "ts-node": "^8.0.2"


"tslint": "^5.14.0"

third-party-reporter/package.json

craigtaub · 2019-03-24T12:02:33Z

Thanks @juergba. I will try but might include it in the next batch of examples if thats ok.
Reason being that I think its worth drawing a line on how big this PR is getting. Also means can start sending the Repo out earlier. I definitely want to add more examples.

craigtaub · 2019-03-24T18:14:31Z

@plroebuck think ive fixed the issues you found. Could you have another look please? Thanks

babel/package.json

babel/.gitignore

plroebuck · 2019-03-24T23:44:11Z

babel/package.json

+    "lib": "./src",
+    "test": "./test"
+  },
+  "dependencies": {


Should all of these packages be devDependencies?
After transpilation, are any of them needed to load/use the package?

plroebuck · 2019-03-25T00:12:08Z

babel/README.md

@@ -0,0 +1,8 @@
+# Babel application
+
+Full documentation about it [here](https://mochajs.org/#-require-module-r-module)


Link has nothing to do the application, but that Mocha will need
-r @babel/register to test...

I feel it's relevant and useful to point the user to the corresponding part of our documentation.

If somebody is interested to know more about a particular detail/setup in a given example the docs offer that.

Have updated the text but kept the link.

plroebuck · 2019-03-25T00:14:59Z

programmatic-usage/package.json

+    "node": ">=10.0.0"
+  },
+  "license": "ISC",
+  "devDependencies": {


Move "devDependencies" directly after "dependencies"

programmatic-usage/package.json

plroebuck · 2019-03-25T00:32:00Z

third-party-reporter/README.md

+
+Full documentation about it [here](https://github.com/mochajs/mocha/wiki/Third-party-reporters).
+
+To use a reporter published on npm (e.g lcov-reporter), install it locally and set `--reporter lcov-reporter`.


(e.g., lcov-reporter)

plroebuck · 2019-03-25T00:36:41Z

third-party-reporter/test/unit/index.spec.js

@@ -0,0 +1,10 @@
+const { equal } = require("assert");


const { equal } = require('assert');

Shouldn't this file be named "my-reporter.spec.js"?

plroebuck · 2019-03-25T00:41:44Z

typescript/package.json

+  "types": "lib/index.d.ts",
+  "scripts": {
+    "compile": "tsc --declaration",
+    "lint": "tslint --project tsconfig.json",


prepublish?

plroebuck · 2019-03-25T00:44:16Z

typescript/package.json

+    "test": "./src"
+  },
+  "dependencies": {
+    "typescript": "^3.3.3"


Project still Typescript-dependent after compile (prepublish)?
If not, devDependency...

plroebuck · 2019-03-25T08:04:32Z

babel/.babelrc

@@ -0,0 +1,3 @@
+{
+  "presets": ["@babel/preset-env"]
+}


Should this file be replaced with "babel.config.js"? Untested content below...

module.exports = () => { const presets = [ [ "@babel/preset-env", { useBuiltIns: false } ] ]; return { presets }; };

Yes I think so. Done.

plroebuck · 2019-03-25T08:18:05Z

babel/README.md

@@ -0,0 +1,8 @@
+# Babel application
+
+Full documentation about it [here](https://mochajs.org/#-require-module-r-module)


Might want another section here. I'm no Babel expert so feel free to modify accordingly...

## Runtime Environment: Three possibilities: 1. Avoid features which require runtime support (including new Built-ins and generators) 2. Require `@babel/runtime` directly, allowing usage of generators, but not polyfills which would modify the global environment 3. Require `@babel/polyfill` as a peer dependency and document that the consuming app must require it This example app does not use features which require runtime support.

Looks good. Will add.

plroebuck · 2019-03-25T08:22:47Z

babel/src/index.js

@@ -0,0 +1,3 @@
+export const add = (a, b) => {
+  return a + b;
+}


Should this be named something more descriptive (e.g., "add.js") with an actual "index.js" that exports it? Your call.

Good point.

craigtaub · 2019-03-28T11:45:43Z

@plroebuck think ive covered the last batch of comments. I'd like to get this in soon.

craigtaub · 2019-04-03T19:58:50Z

Think I will merge this in a few days if there is nothing else outstanding from anyone else.

add 3 app examples

9dfa846

craigtaub requested review from juergba, boneskull and plroebuck March 14, 2019 22:21

add another setup

f6bc261

craigtaub self-assigned this Mar 14, 2019

craigtaub added 3 commits March 14, 2019 22:37

fix casing

384780d

fix typos

7d1e7bf

add babel example

bb314ad

craigtaub mentioned this pull request Mar 15, 2019

Add some working examples mochajs/mocha#3821

Closed

craigtaub added 3 commits March 15, 2019 22:46

add third-party-reporter example

7641c2c

fix typo in 3rd party reporter

b45fd92

use consts

9a54a18