meteor-testing

Testing Meteor 3 apps

meteortesting:mocha is the canonical Meteor test driver. It boots the app in test mode (no app code runs except the test files) and reports results in the server console.

If an existing test fails, hangs, or flakes and the failing layer is unknown, use meteor-debugging to isolate the cause. Return here when evidence points to test setup, design, driver behavior, fixtures, or regression coverage.

Decision flow

1. Unknown failure in an existing test? Use meteor-debugging to classify application, data, harness, browser, environment, or shared-state causes.
2. Pure logic, no Meteor APIs? Plain Mocha or any test runner; nothing Meteor-specific.
3. Method or publication? Integration test it with meteortesting:mocha using Meteor.server.method_handlers[name].apply(ctx, args) or publish_handlers.
4. Need to drive a real DDP client (cross-process or end-to-end DDP semantics)? Use --full-app mode and DDP.connect.
5. UI flow / browser interaction? Start the normal app with deterministic test settings and run Playwright or Cypress against it. Use meteor test --full-app only when the browser flow must load app-test modules.

Setup

meteor add meteortesting:mocha
meteor npm install --save-dev @types/mocha

// package.json
{
  "scripts": {
    "test": "TEST_WATCH=1 meteor test --driver-package meteortesting:mocha",
    "test:ci": "meteor test --once --driver-package meteortesting:mocha",
    "test:full": "meteor test --full-app --driver-package meteortesting:mocha"
  }
}

Test-mode conventions:

• Normal test mode eagerly loads *.test[s].* and *.spec[s].* files, while ordinary application code loads only when imported by a test.
• Filename discovery ignores tests/ directories. A configured meteor.testModule instead loads its explicit entry module and imports.
• --full-app eagerly loads the normal app plus *.app-test[s].* and *.app-spec[s].* files, and sets Meteor.isAppTest.