mocha-vite-puppeteer

3.0.1 verified Fri May 01 auth: no javascript

Run Mocha front-end tests with Vite bundler and Puppeteer browser launcher. Current stable version is 3.0.1. Release cadence is irregular based on contributions. Key differentiators: leverages Vite for fast bundling, works with any Vite project (not framework-specific), supports JS and TS via Vite, and provides built-in reporters plus custom reporter support (e.g., mocha-junit-reporter). It bridges Mocha testing with Vite's modern tooling, offering a streamlined workflow compared to older setups like Karma or Webpack-based runners.

Common errors

error Error: Cannot find module 'puppeteer' ↓

cause Puppeteer is not installed as a dependency.

fix

npm install --save-dev puppeteer

error TypeError: mocha.setup is not a function ↓

cause Mocha not properly imported in test setup file.

fix

Add import 'mocha' before calling mocha.setup().

error Error: No test files found matching pattern ↓

cause The glob pattern for test files doesn't match any files.

fix

Check file naming and ensure test files end with .test.js or .test.jsx (or adjust glob in test-loader.js).

error Error: 'import.meta.globEager' is not supported outside of Vite ↓

cause Using custom test.html with import.meta.globEager outside Vite environment.

fix

Ensure you are running with Vite (the default mode) and not using a different bundler.

Warnings

gotcha Puppeteer may not be installed automatically; ensure puppeteer is in devDependencies. ↓

fix npm install --save-dev puppeteer

gotcha The package uses import.meta.globEager which is a Vite-specific API; not available in other bundlers. ↓

fix Use Vite as your bundler when using custom test.html with globEager.

gotcha Custom reporter options file must be valid JSON, else reporter may fail silently. ↓

fix Ensure reporter-options file is valid JSON and contains the expected keys.

gotcha By default, the package looks for test.html in the root; if not present, it creates a default one. Custom test.html must be alongside index.html. ↓

fix Place custom test.html in the project root or use --entry flag to specify path.

Install

npm install mocha-vite-puppeteer

yarn add mocha-vite-puppeteer

pnpm add mocha-vite-puppeteer

Imports

mocha-vite-puppeteer
wrong
```
import { mochaVitePuppeteer } from 'mocha-vite-puppeteer'
```
correct
```
npx mocha-vite-puppeteer
```
This package is a command-line tool, not a library. The primary usage is via npx or as a devDependency script.

mocha

wrong

const { describe, it } = require('mocha')

correct

import { describe, it } from 'mocha'

Mocha is a peer dependency and used via ESM imports in test files.

chai

wrong

import chai from 'chai' (when using named exports)

correct

import { expect } from 'chai'

chai is commonly used for assertions; expect is a named export.

Quickstart

Shows how to set up and run a Mocha test with Vite bundler and Puppeteer using mocha-vite-puppeteer.

// package.json script
"scripts": {
  "test": "mocha-vite-puppeteer"
}

// Counter.test.jsx
import { expect } from 'chai';
import React from 'react';
import { render, screen } from '@testing-library/react';
import Counter from './Counter';

describe('Counter', () => {
  it('should increment', () => {
    render(<Counter />);
    const btn = screen.getByText('count is: 0');
    btn.click();
    screen.getByText('count is: 1');
  });
});

// Run:
// npx mocha-vite-puppeteer