Skip to content

armgit / mocha

Public Imported from GitHub
0

☕️ Classic, reliable, trusted test framework for Node.js and the browser

Docs: migrate remaining legacy wiki pages to main documentation (#5465)

Kelechi Ebiribff91660733b
diff --git a/docs-next/astro.config.ts b/docs-next/astro.config.ts
index eb4f2bb9..089f9198 100644
--- a/docs-next/astro.config.ts
+++ b/docs-next/astro.config.ts
@@ -108,6 +108,10 @@ export default defineConfig({
label: "Detecting multiple calls to done()",
slug: "explainers/detecting-multiple-calls-to-done",
},
+ {
+ label: "Compilers deprecation",
+ slug: "explainers/compilers-deprecation",
+ },
{
label: "Counting assertions",
slug: "explainers/count-assertions",
diff --git a/docs-next/src/content/docs/explainers/compilers-deprecation.mdx b/docs-next/src/content/docs/explainers/compilers-deprecation.mdx
new file mode 100644
index 00000000..e846ca1a
--- /dev/null
+++ b/docs-next/src/content/docs/explainers/compilers-deprecation.mdx
@@ -0,0 +1,65 @@
+---
+description: Compilers deprecation notice.
+title: Compilers deprecation
+---
+
+If you're here, you probably hit the deprecation notice. Sorry about that!
+
+## Will it break?
+
+This is a *soft* deprecation, which means you get nagged about it, but it won't break (yet).
+
+## Make it go away
+
+To suppress this warning, execute `mocha` with the `--no-deprecation` flag (though you won't get notice of any *other* deprecations you may encounter either).
+
+## ... but why?
+
+`--compilers` is redundant; we've yet to encounter a real-world situation in which the solution couldn't be expressed using `--require`.
+
+## What should I use instead then?
+
+Let's say you want to compile using CoffeeScript. Ensure that you have the coffeescript package installed as a dev dependency:
+
+```npm install coffeescript --save-dev```
+
+Then update your package.json with the relevant require statement: `--require coffeescript/register`.
+
+Here's a list of popular compilers/transpilers:
+
+- CoffeeScript: `--compilers coffee:coffee-script/register` becomes `--require coffeescript/register`
+- Babel 6: `--compilers js:babel-core/register` becomes `--require babel-core/register`
+- Babel 7: `--require babel-core/register` used if you are using Babel v6 becomes `--require @babel/register` with Babel v7.
+- TypeScript: `--compilers ts:ts-node/register` becomes `--require ts-node/register`
+- LiveScript: `--compilers ls:livescript` becomes `--require livescript`
+- (feel free to add more examples!)
+
+You'll have to handle file extensions as well. Mocha, by default, only loads `.js` files when given a directory (and the default directory is `test`). Therefore, to use a *different* file extension (such as `.coffee` or `.ts`), you will need to supply a *glob* instead of simply a directory. If this was how you ran Mocha pre-v4:
+
+```bash
+$ mocha --compilers coffee:coffee-script/register --recursive ./test
+```
+
+Then this is how you'd accomplish the same thing (`**` roughly means "recursive") in v4:
+
+```bash
+$ mocha --require coffeescript/register "test/**/*.js"
+```
+
+When you wrap a glob in quotes, file discovery is handed to the [glob](https://npm.im/glob) package.
+ It's *recommended* to wrap in double-quotes, because the result should be the same regardless of your shell or environment (Windows/Linux/macOS, etc.).
+
+[glob](https://npm.im/glob) is powerful. For instance, if your `test` dir has tests written in *both* JS *and* CoffeeScript, you could do this:
+
+```bash
+$ mocha --require coffeescript/register "test/**/*.{js,coffee}"
+```
+
+## How do I use this with `--watch`?
+
+When using `--watch`, you will also need to specify the extension(s) to watch via `--watch-extensions`, e.g.:
+
+```js
+$ mocha --require coffeescript/register --watch --watch-extensions js,coffee "test/**/*.{js,coffee}"
+```
+
diff --git a/docs/api-tutorials/compilers-deprecation.md b/docs/api-tutorials/compilers-deprecation.md
new file mode 100644
index 00000000..05722c3d
--- /dev/null
+++ b/docs/api-tutorials/compilers-deprecation.md
@@ -0,0 +1,63 @@
+If you're here, you probably hit the deprecation notice. Sorry about that!
+
+## Will it break?
+
+This is a _soft_ deprecation, which means you get nagged about it, but it won't break (yet).
+
+## Make it go away
+
+To suppress this warning, execute `mocha` with the `--no-deprecation` flag (though you won't get notice of any _other_ deprecations you may encounter either).
+
+## ... but why?
+
+`--compilers` is redundant; we've yet to encounter a real-world situation in which the solution couldn't be expressed using `--require`.
+
+## What should I use instead then?
+
+Let's say you want to compile using CoffeeScript. Ensure that you have the coffeescript package installed as a dev dependency:
+
+`npm install coffeescript --save-dev`
+
+Then update your package.json with the relevant require statement: `--require coffeescript/register`.
+
+Here's a list of popular compilers/transpilers:
+
+- CoffeeScript: `--compilers coffee:coffee-script/register` becomes `--require coffeescript/register`
+- Babel 6: `--compilers js:babel-core/register` becomes `--require babel-core/register`
+- Babel 7: `--require babel-core/register` used if you are using Babel v6 becomes `--require @babel/register` with Babel v7.
+- TypeScript: `--compilers ts:ts-node/register` becomes `--require ts-node/register`
+- LiveScript: `--compilers ls:livescript` becomes `--require livescript`
+- (feel free to add more examples!)
+
+You'll have to handle file extensions as well. Mocha, by default, only loads `.js` files when given a directory (and the default directory is `test`). Therefore, to use a _different_ file extension (such as `.coffee` or `.ts`), you will need to supply a _glob_ instead of simply a directory. If this was how you ran Mocha pre-v4:
+
+```bash
+$ mocha --compilers coffee:coffee-script/register --recursive ./test
+```
+
+Then this is how you'd accomplish the same thing (`**` roughly means "recursive") in v4:
+
+```bash
+$ mocha --require coffeescript/register "test/**/*.js"
+```
+
+When you wrap a glob in quotes, file discovery is handed to the [glob](https://npm.im/glob) package.
+It's _recommended_ to wrap in double-quotes, because the result should be the same regardless of your shell or environment (Windows/Linux/macOS, etc.).
+
+[glob](https://npm.im/glob) is powerful. For instance, if your `test` dir has tests written in _both_ JS _and_ CoffeeScript, you could do this:
+
+```bash
+$ mocha --require coffeescript/register "test/**/*.{js,coffee}"
+```
+
+## How do I use this with `--watch`?
+
+When using `--watch`, you will also need to specify the extension(s) to watch via `--watch-extensions`, e.g.:
+
+```js
+$ mocha --require coffeescript/register --watch --watch-extensions js,coffee "test/**/*.{js,coffee}"
+```
+
+## This isn't working
+
+Any questions or trouble? Ask for help [in our Gitter chat room](https://gitter.im/mochajs/mocha)!
diff --git a/docs/api-tutorials/jsdoc.tutorials.json b/docs/api-tutorials/jsdoc.tutorials.json
index ba7390a3..c1bdcddc 100644
--- a/docs/api-tutorials/jsdoc.tutorials.json
+++ b/docs/api-tutorials/jsdoc.tutorials.json
@@ -1,4 +1,7 @@
{
+ "compilers-deprecation": {
+ "title": "Compilers deprecation"
+ },
"count-assertions": {
"title": "Count assertions"
},