### Install Mochawesome

Source: https://github.com/adamgruber/mochawesome/blob/master/README.md

Add the reporter to your project dependencies.

```bash
npm install --save-dev mochawesome
```

--------------------------------

### CI/CD Integration Configuration

Source: https://context7.com/adamgruber/mochawesome/llms.txt

Examples for configuring Mochawesome via package.json scripts, GitHub Actions, and programmatic Mocha execution.

```javascript
// package.json scripts for CI integration
{
  "scripts": {
    "test": "mocha --reporter mochawesome --reporter-options reportDir=./reports,json=true,html=true",
    "test:ci": "mocha --reporter mochawesome --reporter-options quiet=true,reportFilename=[status]-[datetime]",
    "test:parallel": "mocha --parallel --reporter mochawesome --require mochawesome/register"
  }
}
```

```yaml
// GitHub Actions workflow example
// .github/workflows/test.yml
/*
name: Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: npm test
      - uses: actions/upload-artifact@v3
        if: always()
        with:
          name: test-reports
          path: mochawesome-report/
*/
```

```javascript
// Programmatic usage with custom error handling
const Mocha = require('mocha');

const mocha = new Mocha({
  reporter: 'mochawesome',
  reporterOptions: {
    reportDir: process.env.REPORT_DIR || './mochawesome-report',
    reportFilename: `test-results-${process.env.BUILD_NUMBER || 'local'}`,
    quiet: process.env.CI === 'true'
  }
});

mocha.addFile('./test/index.js');

mocha.run(failures => {
  // Report location for CI artifact collection
  console.log(`Report generated at: ${process.env.REPORT_DIR || './mochawesome-report'}`);

  // Exit with appropriate code for CI
  process.exit(failures > 0 ? 1 : 0);
});
```

--------------------------------

### Install TypeScript Definitions for Mochawesome

Source: https://github.com/adamgruber/mochawesome/blob/master/README.md

Mochawesome does not maintain its own type definitions. Install them from DefinitelyTyped using npm.

```bash
$ npm install --save-dev @types/mochawesome
```

--------------------------------

### Configure Mochawesome for Parallel Mode

Source: https://context7.com/adamgruber/mochawesome/llms.txt

When running Mocha tests in parallel mode (mocha >= 8), require 'mochawesome/register' before creating the Mocha instance to properly aggregate results from worker processes. This setup ensures test context, hook results, and error objects are preserved across process boundaries.

```javascript
// Command line usage for parallel mode
// mocha tests/**/*.js --reporter mochawesome --require mochawesome/register --parallel

// Programmatic parallel mode setup
const Mocha = require('mocha');
const path = require('path');

// Require the register module BEFORE creating Mocha instance
require('mochawesome/register');

const mocha = new Mocha({
  reporter: 'mochawesome',
  parallel: true,
  jobs: 4,  // Number of worker processes
  reporterOptions: {
    reportFilename: 'parallel-test-results',
    consoleReporter: 'spec'
  }
});

// Add test files
const testFiles = [
  './test/api.test.js',
  './test/auth.test.js',
  './test/users.test.js',
  './test/orders.test.js'
];
testFiles.forEach(file => mocha.addFile(file));

// Run tests in parallel
mocha.run(failures => {
  console.log(`Tests completed with ${failures} failures`);
  process.exitCode = failures ? 1 : 0;
});

// The register module ensures:
// - Test context is serialized across worker processes
// - Hook results (before/after) are preserved
// - Error objects are properly serialized
// - Skipped test counts are accurate
```

--------------------------------

### Configure Mocha Programmatically

Source: https://github.com/adamgruber/mochawesome/blob/master/README.md

Initialize Mocha with the reporter option in a JavaScript file.

```js
var mocha = new Mocha({
  reporter: 'mochawesome',
});
```

--------------------------------

### Configure Reporter Options via CLI

Source: https://github.com/adamgruber/mochawesome/blob/master/README.md

Pass comma-separated options to the reporter using the --reporter-options flag.

```bash
$ mocha test.js --reporter mochawesome --reporter-options reportDir=customReportDir,reportFilename=customReportFilename
```

--------------------------------

### Configure Mochawesome Programmatically

Source: https://context7.com/adamgruber/mochawesome/llms.txt

Use the Mocha constructor to set reporter options and run tests programmatically.

```javascript
// Command line usage
// mocha testfile.js --reporter mochawesome

// Programmatic usage with Mocha
const Mocha = require('mocha');
const path = require('path');

const mocha = new Mocha({
  reporter: 'mochawesome',
  reporterOptions: {
    reportDir: './custom-report-dir',
    reportFilename: 'test-results',
    html: true,
    json: true,
    quiet: false,
    consoleReporter: 'spec'
  }
});

// Add test files
mocha.addFile('./test/mytest.spec.js');

// Run tests and handle results
mocha.run(failures => {
  process.exitCode = failures ? 1 : 0;
});

// Output files generated:
// - ./custom-report-dir/test-results.html
// - ./custom-report-dir/test-results.json
```

--------------------------------

### Manage Reporter Configuration Options

Source: https://context7.com/adamgruber/mochawesome/llms.txt

Configure report generation behavior using default objects, environment variables, or command-line flags.

```javascript
// All available reporter options with defaults
const reporterOptions = {
  // Silence console messages from mochawesome
  quiet: false,

  // Filename for generated report (without extension)
  // Supports tokens: [name], [status], [datetime]
  reportFilename: 'mochawesome',

  // Generate HTML report file
  html: true,

  // Generate JSON data file
  json: true,

  // Console reporter to use while tests run ('spec', 'dot', 'none', etc.)
  consoleReporter: 'spec'
};

// Using environment variables
// export MOCHAWESOME_QUIET=true
// export MOCHAWESOME_REPORTFILENAME=my-report
// export MOCHAWESOME_HTML=true
// export MOCHAWESOME_JSON=true
// export MOCHAWESOME_CONSOLEREPORTER=dot

// Command line with reporter-options
// mocha test.js --reporter mochawesome \
//   --reporter-options reportDir=./reports,reportFilename=results,quiet=true

// Dynamic filename with replacement tokens
const mocha = new Mocha({
  reporter: 'mochawesome',
  reporterOptions: {
    reportFilename: '[status]_[datetime]-[name]-report',
    timestamp: 'longDate'
  }
});
// Output: pass_February_23_2022-mytest-report.html
```

--------------------------------

### Run Mocha with Mochawesome

Source: https://github.com/adamgruber/mochawesome/blob/master/README.md

Execute tests using the Mochawesome reporter via the command line.

```bash
mocha testfile.js --reporter mochawesome
```

--------------------------------

### Set Environment Variable Options

Source: https://github.com/adamgruber/mochawesome/blob/master/README.md

Configure reporter settings using environment variables prefixed with MOCHAWESOME_.

```bash
$ export MOCHAWESOME_REPORTFILENAME=customReportFilename
```

--------------------------------

### Configure Reporter Options Programmatically

Source: https://github.com/adamgruber/mochawesome/blob/master/README.md

Pass reporter options directly to the Mocha constructor.

```js
var mocha = new Mocha({
  reporter: 'mochawesome',
  reporterOptions: {
    reportFilename: 'customReportFilename',
    quiet: true,
  },
});
```

--------------------------------

### Run in Parallel Mode

Source: https://github.com/adamgruber/mochawesome/blob/master/README.md

Register the reporter as a hook when running tests in parallel.

```bash
mocha tests --reporter mochawesome --require mochawesome/register
```

--------------------------------

### Configure Mochawesome Report Filename

Source: https://github.com/adamgruber/mochawesome/blob/master/README.md

Use replacement tokens like [name], [status], and [datetime] to dynamically set the report filename. The `timestamp` option controls the format of the [datetime] token. Note that [name] replacement is only available when running one spec file per process.

```json
{
  reporter: "mochawesome",
  reporterOptions: {
    reportFilename: "[status]_[datetime]-[name]-report",
    timestamp: "longDate"
  }
}
```

--------------------------------

### addContext(testObj, context)

Source: https://github.com/adamgruber/mochawesome/blob/master/README.md

The addContext helper method allows developers to associate additional information, such as strings, URLs, or objects, with a specific test for display in the generated report.

```APIDOC
## addContext(testObj, context)

### Description
Associates additional information with a test object to be displayed in the Mochawesome report. Note: Must use ES5 functions to ensure 'this' references the test object.

### Parameters
- **testObj** (object) - Required - The test object (usually 'this' in a test block).
- **context** (string|object) - Required - The information to be added. If a string is a URL, it will be linked; if it points to an image/video, it will be displayed inline. If an object, it must contain a 'title' (string) and 'value' (any).

### Request Example
addContext(this, { title: 'expected output', value: { a: 1 } });
```

--------------------------------

### Mochawesome JSON Output Structure

Source: https://context7.com/adamgruber/mochawesome/llms.txt

Represents the schema of the generated mochawesome.json file containing test statistics, suite results, and reporter metadata.

```javascript
// Sample mochawesome.json output structure
{
  "stats": {
    "suites": 5,
    "tests": 24,
    "passes": 20,
    "pending": 2,
    "failures": 2,
    "testsRegistered": 24,
    "passPercent": 90.909,
    "pendingPercent": 8.333,
    "other": 0,
    "hasOther": false,
    "skipped": 0,
    "hasSkipped": false,
    "start": "2024-01-15T10:30:00.000Z",
    "end": "2024-01-15T10:30:05.123Z",
    "duration": 5123
  },
  "results": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "title": "",
      "fullFile": "/path/to/test/file.spec.js",
      "file": "/test/file.spec.js",
      "beforeHooks": [],
      "afterHooks": [],
      "tests": [],
      "suites": [
        {
          "uuid": "550e8400-e29b-41d4-a716-446655440001",
          "title": "User API",
          "tests": [
            {
              "title": "should create user",
              "fullTitle": "User API should create user",
              "timedOut": false,
              "duration": 150,
              "state": "passed",
              "speed": "fast",
              "pass": true,
              "fail": false,
              "pending": false,
              "context": "[{\"title\":\"Response\",\"value\":{\"id\":1}}]",
              "code": "const user = await createUser(data);\nuser.id.should.be.a.Number();",
              "err": {},
              "uuid": "550e8400-e29b-41d4-a716-446655440002",
              "parentUUID": "550e8400-e29b-41d4-a716-446655440001",
              "isHook": false,
              "skipped": false
            }
          ],
          "passes": ["550e8400-e29b-41d4-a716-446655440002"],
          "failures": [],
          "pending": [],
          "skipped": [],
          "duration": 150,
          "root": false,
          "rootEmpty": false
        }
      ],
      "passes": [],
      "failures": [],
      "pending": [],
      "skipped": [],
      "duration": 0,
      "root": true,
      "rootEmpty": true
    }
  ],
  "meta": {
    "mocha": { "version": "10.2.0" },
    "mochawesome": {
      "options": {
        "quiet": false,
        "reportFilename": "mochawesome",
        "saveHtml": true,
        "saveJson": true,
        "consoleReporter": "spec",
        "code": true
      },
      "version": "7.1.4"
    },
    "marge": {
      "options": {},
      "version": "6.3.0"
    }
  }
}
```

--------------------------------

### Add Test Context with Mochawesome

Source: https://github.com/adamgruber/mochawesome/blob/master/README.md

Use the `addContext` helper to associate additional information with a test. This context will be displayed in the report. Ensure you use ES5 functions, not arrow functions, when calling `addContext` to correctly reference `this`.

```javascript
const addContext = require('mochawesome/addContext');

describe('test suite', function () {
  it('should add context', function () {
    // context can be a simple string
    addContext(this, 'simple string');

    // context can be a url and the report will create a link
    addContext(this, 'http://www.url.com/pathname');

    // context can be an image url and the report will show it inline
    addContext(this, 'http://www.url.com/screenshot-maybe.jpg');

    // context can be an object with title and value properties
    addContext(this, {
      title: 'expected output',
      value: {
        a: 1,
        b: '2',
        c: 'd',
      },
    });
  });
});
```

```javascript
describe('test suite', () => {
  beforeEach(function () {
    addContext(this, 'some context');
  });

  afterEach(function () {
    addContext(this, {
      title: 'afterEach context',
      value: { a: 1 },
    });
  });

  it('should display with beforeEach and afterEach context', () => {
    // assert something
  });
});
```

--------------------------------

### Add Context to Mocha Tests with addContext

Source: https://context7.com/adamgruber/mochawesome/llms.txt

Use the addContext helper function to attach strings, URLs, image URLs, or structured objects to test results. Ensure you use ES5 function syntax, not arrow functions, as they do not bind 'this' correctly.

```javascript
const addContext = require('mochawesome/addContext');

describe('User API Tests', function() {
  // Context in before/after hooks
  before(function() {
    addContext(this, 'Test environment: staging');
  });

  after(function() {
    addContext(this, 'Cleanup completed successfully');
  });

  // IMPORTANT: Use ES5 function() syntax, NOT arrow functions
  // Arrow functions do not bind 'this' correctly
  it('should fetch user data', function() {
    // Simple string context
    addContext(this, 'Testing user ID: 12345');

    // URL context - rendered as clickable link
    addContext(this, 'https://api.example.com/users/12345');

    // Image URL - displayed inline in report
    addContext(this, 'https://example.com/screenshot.png');

    // Object context with title and value
    addContext(this, {
      title: 'API Response',
      value: {
        id: 12345,
        name: 'John Doe',
        email: 'john@example.com',
        roles: ['admin', 'user']
      }
    });

    // Multiple contexts are accumulated as an array
    addContext(this, {
      title: 'Request Headers',
      value: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer token123'
      }
    });

    // Perform assertions
    const user = { id: 12345, name: 'John Doe' };
    user.id.should.equal(12345);
  });

  // Using addContext in beforeEach/afterEach hooks
  describe('with authentication', function() {
    beforeEach(function() {
      addContext(this, 'Authenticating test user...');
    });

    afterEach(function() {
      addContext(this, {
        title: 'Test Duration',
        value: `${this.currentTest.duration}ms`
      });
    });

    it('should access protected resource', function() {
      addContext(this, 'Using admin credentials');
      // Test code here
    });
  });
});
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.