Add Memory Match Rstest showcase example

[nachocodoner]

Memory Match Rstest example for Meteor

Related: Rstest integration discussion and Meteor integration branch.

This PR adds Memory Match, a React and TypeScript example testing one application from game logic and components to real MongoDB, DDP, and full-app browser flows.

Warning

The integration is experimental and requires the rspack-rstest-integration Meteor checkout. Commands and interfaces may change. The lockfile pins external dependencies; local integration packages come from the selected checkout.

Meteor owns compilation, application hosts, MongoDB, DDP, ports, and shutdown. Rstest supplies the test engine, APIs, and native tooling. Tests use @rstest/core, with upstream browser and Playwright extensions. Meteor-runtime tests import real meteor/* modules alongside that API.

See the Test Stack overview and Rstest guide for configuration and usage.

Application

Purpose: a cosmic card-matching game with a shared, live leaderboard.

Why: compare fast unit feedback, component interaction, real Meteor data behavior, and a complete user journey without separate demos for each mode.

Stack: Meteor, Rspack, React, TypeScript, MongoDB, Rstest, Testing Library, jsdom, and Playwright. Rstest packages are pinned to 0.11.6.

What it showcases: game rules, snapshots, module mocks, in-source tests, components, browsers, methods and publications, isolated workers, local Atmosphere package tests, E2E, and combined coverage.

Find eight pairs among sixteen cards and watch a score appear in a second browser without refreshing. E2E completes a deterministic game, checks that reactive update, and starts another round. The deterministic seed is accepted only in Meteor test mode; normal play remains random.

Hands-on

Clone and prepare

Use Git and Node.js 22.12 or newer. No global Meteor installation is needed. Clone both matching branches:

mkdir meteor-rstest-workspace
cd meteor-rstest-workspace

git clone --branch feat/memory-match-rstest \
  https://github.com/meteor/examples.git examples
git clone --branch rspack-rstest-integration \
  https://github.com/meteor/meteor.git meteor

cd examples/memory-match
npm run setup
./meteor-checkout npx playwright install chromium

On Linux, use ./meteor-checkout npx playwright install --with-deps chromium if browser system libraries are missing.

Run setup before npm install or npm ci: it creates the local integration-package paths, installs dependencies with Meteor's bundled npm, generates Meteor declarations, and writes ./meteor-checkout. The first run may download Meteor's development bundle and Atmosphere dependencies. The launcher validates the branch and forwards commands to that checkout without cloning or switching branches.

Setup also applies the current React Refresh compatibility adjustment only to the app's installed @meteorjs/rspack copy; the source checkout is unchanged.

Use another checkout or compatible development branch

The default layout places meteor/ beside examples/. Override it with an absolute path:

METEOR_CHECKOUT=/absolute/path/to/meteor npm run setup

For a compatible development branch, also set METEOR_RSTEST_BRANCH=my-rstest-change during setup. Rerun setup after moving the checkout or updating its npm integration packages. See the setup guide.

Play and test

./meteor-checkout run

Open http://localhost:3000, complete a game, and watch the leaderboard update in a second browser. Stop the development server before testing. Run these commands sequentially; full-app tests manage their own application and MongoDB.

# Native Node, snapshots, mocks, and in-source tests
./meteor-checkout test --once --server-only \
  --project meteor-pure-server --project showcase-in-source

# Components in a real browser
./meteor-checkout test --once --client-only --browser chromium \
  --project meteor-browser

# Real Meteor server and client runtime
./meteor-checkout test --once --browser chromium \
  --project meteor-runtime-server --project meteor-runtime-client

# Local Atmosphere package
./meteor-checkout test-packages --once memory-match-engine

# Complete application flow
./meteor-checkout test --once --full-app --browser chromium \
  --project meteor-e2e

# Combined coverage for this invocation
./meteor-checkout test --once --coverage --full-app --runtime-workers 1

The test commands include jsdom, watch mode, native workers, and isolated Meteor workers. Their npm shortcuts expose the actual Meteor commands in package.json. Use SHOWCASE_HEADED=1 npm run test:browser or SHOWCASE_HEADED=1 npm run test:e2e for a visible browser; the showcase walkthrough provides a presentation path.

Configuration and real Meteor behavior

Tests live beside features under imports/game, imports/ui, and imports/api. Imports determine execution environments; filename markers demonstrate explicit routing choices. rstest.config.ts configures setup, browsers, coverage, concurrency, and an additional in-source project.

Runtime cases exercise real database operations, Meteor.callAsync, subscriptions, Minimongo, and Tracker. Application-module mocking is supported; replacing Meteor or Atmosphere modules is not. The local memory-match-engine package uses a normal Package.onTest harness. Native workers and Meteor workers are separate: runtime workers isolate hosts and databases, while cases within one host share its state.

Existing suites do not need to migrate. The driver guide explains coexistence and discovery boundaries; the provider guide explains the architecture.

Coverage and verification

Combined coverage includes selected native tests, real Meteor server/client code, loaded standard local packages, and full-app Playwright pages. Reports appear in coverage/index.html and coverage/coverage-summary.json. Separate invocations are not merged. Meteor coverage requires Istanbul; native-only runs retain upstream Istanbul or V8. It does not accumulate watch generations or add zero-hit entries for never-loaded sources. Custom-compiler packages and unrelated external browser processes are not covered.

The manual verification workflow can run the checkout setup, test modes, coverage, and startup checks on demand. It is not triggered by pull requests or pushes.

Local verification from a clean copy on macOS with Node 24.15.0 passed: setup, Chromium installation, all 10 tooling checks, typecheck, native tests, jsdom components, Chromium Browser Mode, Meteor server/client tests, local package tests, E2E, both parallel modes, and combined coverage (91.3% of configured source lines). npm start served a healthy app with MongoDB ready. The integration tests also passed with no global meteor on PATH.

Feedback on setup, runtime behavior, existing-driver coexistence, and coverage is welcome. Please include the command, checkout revision, and a reproducible test.