docs: Migrate tagging wiki page to docs (#5435)

Co-authored-by: Mark Wiemer <[email protected]>

Author: TG199

docs-next/astro.config.ts

@@ -110,6 +110,10 @@ export default defineConfig({
               label: "Spies",
               slug: "explainers/spies",
             },
+            {
+              label: "Tagging with --grep",
+              slug: "explainers/tagging",
+            },
             { label: "Test duration", slug: "explainers/test-duration" },
             {
               label: "Test fixture decision tree",

docs-next/src/content/docs/explainers/tagging.mdx

@@ -0,0 +1,26 @@
+---
+description: Use Mocha's --grep to tag and selectively run tests.
+title: Tagging with --grep
+---
+
+Mocha's `--grep` feature may be used both on the client (via `?grep=`) and server-side. Recent releases of Mocha allow you to also click on the suite or test-case names in the browser to automatically grep them. The concept of **tagging** utilizes regular grepping, however may be a useful way to keep related tests in the same spot, while still conditionally executing them.
+
+A good example of this is if you wanted to run slow tests only before releasing, or periodically. You could use any sequence of characters you like, perhaps `#slow`, `@slow` to tag them as shown here:
+
+```js
+describe('app', function () {
+  describe('GET /login', function () {
+    it('should respond with the login form @fast', function () {
+      // ...
+    });
+  });
+
+  describe('GET /download/:file', function () {
+    it('should respond with the file @slow', function () {
+      // ...
+    });
+  });
+});
+```
+
+To execute fast tests only then you may do `--grep @fast`. Another alternative is to only tag `@slow`, and utilize `--grep @slow --invert` to invert the grep expression.

docs/api-tutorials/jsdoc.tutorials.json

@@ -8,6 +8,9 @@
   "spies": {
     "title": "Spies"
   },
+  "tagging": {
+    "title": "Tagging with --grep"
+  },
   "third-party-reporters": {
     "title": "Third party reporters"
   }

docs/api-tutorials/tagging.md

@@ -0,0 +1,21 @@
+Mocha's `--grep` feature may be used both on the client (via `?grep=`) and server-side. Recent releases of Mocha allow you to also click on the suite or test-case names in the browser to automatically grep them. The concept of **tagging** utilizes regular grepping, however may be a useful way to keep related tests in the same spot, while still conditionally executing them.
+
+A good example of this is if you wanted to run slow tests only before releasing, or periodically. You could use any sequence of characters you like, perhaps `#slow`, `@slow` to tag them as shown here:
+
+```js
+describe('app', function () {
+  describe('GET /login', function () {
+    it('should respond with the login form @fast', function () {
+      // ...
+    });
+  });
+
+  describe('GET /download/:file', function () {
+    it('should respond with the file @slow', function () {
+      // ...
+    });
+  });
+});
+```
+
+To execute fast tests only then you may do `--grep @fast`. Another alternative is to only tag `@slow`, and utilize `--grep @slow --invert` to invert the grep expression.