Add MongoDB e2e testing plugin (@lowdefy/community-plugin-e2e-mdb)

[machielvdw]

Brief

Problem

Lowdefy e2e tests can verify UI state and client-side request responses, but cannot verify that data actually persisted correctly in MongoDB. After a form submission, tests can check ldf.expect.request() succeeded, but not that the database contains the right document with the right fields. This forces developers to either trust the UI layer or write separate integration tests.

Additionally:

• Tests currently require a real MongoDB instance, which complicates CI/CD and local development
• Atlas-specific features (Atlas Search, vector search, etc.) can't be tested against mongodb-memory-server

Requirements

MongoDB In-Memory Server:

• Use mongodb-memory-server for test database — no external MongoDB instance required
• Each Playwright worker gets an isolated in-memory database
• Tests run without network dependencies, faster execution, works offline

Database Operations:

• The mdb package should export fixture definitions (not a pre-built test object) so developers compose it themselves via test.extend(mdbFixtures) in their local e2e/fixtures.js
• The mdb package should have no dependency on @lowdefy/e2e-utils — it's a standalone Playwright fixture that works with any project
• Users should be able to assert MongoDB document state within Playwright e2e tests via an mdb fixture
• Users should be able to load snap files (YAML) to set up known database state before tests
• Users should be able to create/update snap files from current database state
• Snap files should live in e2e/snaps/<name>/<collection>.yaml
• Assertions should auto-poll with configurable timeout (matching Playwright's expect.poll pattern) since DB writes from Lowdefy requests are async
• Users should be able to seed collections inline with JavaScript objects as an alternative to snap files
• Users should have direct MongoDB collection access (findOne, insertOne, aggregate) as an escape hatch

Request Mocking for Atlas Features:

• For Atlas-specific features (Atlas Search, vector search, etc.) that mongodb-memory-server doesn't support, provide request mocking
• Developers configure which Lowdefy requests to mock via config file (e.g., e2e/mocks.yaml or similar)
• May require changes to Lowdefy build output to support request interception in e2e mode
• Mock responses can be static (from config) or dynamic (based on test setup)

API Shape (Reference)

Developer's e2e/fixtures.js after adding mdb plugin:

import { test as ldfTest, expect } from '@lowdefy/e2e-utils/fixtures';
import { mdbFixtures } from '@lowdefy/community-plugin-e2e-mdb';

export const test = ldfTest.extend(mdbFixtures);
export { expect };

Test files import locally (unchanged when adding plugins):

import { test, expect } from './fixtures.js';

test('creates ticket', async ({ ldf, mdb }) => {
  // Setup: load snap or seed inline (uses in-memory MongoDB)
  await mdb.load('clean-tickets');
  // or: await mdb.seed('tickets', [{ name: 'Existing', status: 'open' }]);

  // Act via UI
  await ldf.goto('/tickets/new');
  await ldf.do.blocks['name_input'].fill('John Doe');
  await ldf.do.blocks['priority_select'].select('High');
  await ldf.do.blocks['submit_btn'].click();

  // Assert DB state (auto-polls)
  await mdb.expect('tickets').toContainDocument({ name: 'John Doe', priority: 'high' });
  await mdb.expect('tickets').toHaveDocumentCount(2);
  await mdb.expect('tickets').not.toContainDocument({ _id: 'deleted-id' });

  // Direct access escape hatch
  const doc = await mdb.collection('tickets').findOne({ name: 'John Doe' });
  expect(doc.tags).toContain('urgent');
});

Request mocking config (conceptual — TBD during implementation):

# e2e/mocks.yaml
mocks:
  - requestId: search_products
    response:
      - _id: prod-1
        name: "Widget"
        score: 0.95
  - requestId: vector_search_docs
    response: []  # empty results for this test scenario

Acceptance Criteria

MongoDB in-memory:

• Package created as @lowdefy/community-plugin-e2e-mdb
• Package exports mdbFixtures object for use with test.extend(mdbFixtures)
• Package has no dependency on @lowdefy/e2e-utils
• Uses mongodb-memory-server — no external MongoDB required
• Each Playwright worker gets isolated in-memory database instance
• mdb.load('name') reads YAML snap files from e2e/snaps/<name>/ and restores collections
• mdb.snap('name') creates/updates snap files from current database state
• mdb.seed(collection, docs) clears collection and inserts provided documents
• mdb.expect(collection).toContainDocument(filter) polls until document found or timeout
• mdb.expect(collection).toHaveDocumentCount(n) polls until count matches
• mdb.expect(collection).not.toContainDocument(filter) polls until document absent
• mdb.collection(name) returns raw MongoDB collection for direct operations
• Snap YAML format supports query match/project, replace/merge modes, and optional cleanup

Request mocking:

• Developers can configure which Lowdefy requests to mock via config
• Mocked requests return configured responses instead of hitting the (non-existent) Atlas features
• Build/runtime changes in Lowdefy core (if needed) to support request interception in e2e mode

Related Work

• Parent work: Create @lowdefy/e2e-utils package for app developers lowdefy#1970 - @lowdefy/e2e-utils package
• Tracking issue: Add MongoDB data testing (mdb fixture) to @lowdefy/e2e-utils lowdefy#1975 - MongoDB data testing brief
• Inspiration: mdb-snapper tool (YAML snap format, replace/merge modes, cleanup)

Source

Brainstorm discussion about integrating MongoDB data tests into e2e testing. User wants to verify database state within the same e2e test — assert documents exist after UI actions, load/restore snapshots for test setup, seed data inline. Key decisions:

• Community plugin package (not in core repo since it only supports MongoDB)
• Fully decoupled from e2e-utils (exports fixture definitions, no dependency)
• Use mongodb-memory-server for isolation, speed, and no external dependencies
• Built-in request mocking for Atlas Search and other unsupported features (requires Lowdefy build changes + developer config)

---

Brief Agent - Created: 2026-02-04 CAT

[machielvdw]

Technical Implementation Plan

Summary

Create @lowdefy/community-plugin-e2e-mdb package in the community-plugins repo that provides Playwright fixtures for MongoDB e2e testing. The package uses mongodb-memory-server for isolated test databases and supports YAML snap files (inspired by mdb-snapper) for database state management. The package exports mdbFixtures for composition with @lowdefy/e2e-utils via test.extend(mdbFixtures) but has no dependency on e2e-utils—it works with any Playwright project.

Note: Request mocking has been moved to a separate issue in the core repo: lowdefy/lowdefy#1977

Technical Decisions

1. Database strategy: Global setup starts mongodb-memory-server, exports URI. Playwright's webServer starts Lowdefy app with this URI. All workers share one in-memory MongoDB instance for faster startup.
2. Snap file location: Central e2e/snaps/<name>/<collection>.yaml directory (matches mdb-snapper pattern)
3. Package independence: No dependency on @lowdefy/e2e-utils—exports raw Playwright fixture definitions
4. Assertion pattern: Auto-polling with configurable timeout (matches Playwright's expect.poll pattern)
5. Snap file format: Reuse mdb-snapper's YAML format (metadata, mode, cleanup, query, data sections)

Scope

Feature	In Scope	Out of Scope
In-memory MongoDB (mongodb-memory-server)	✅
Snap file load/save	✅
Inline seeding	✅
Database assertions (polling)	✅
Direct collection access	✅
Request mocking		❌ → lowdefy/lowdefy#1977
Request payload capture		❌ → lowdefy/lowdefy#1977

Architecture

@lowdefy/community-plugin-e2e-mdb
├── src/
│   ├── index.js                    # Main exports (mdbFixtures)
│   ├── fixtures/
│   │   └── index.js                # Playwright fixture definitions
│   ├── mdb/
│   │   ├── createMdbHelper.js      # mdb fixture factory
│   │   ├── snap.js                 # Load/save snap files
│   │   ├── seed.js                 # Inline seeding
│   │   ├── expect.js               # Polling assertions
│   │   └── collection.js           # Direct collection access
│   ├── setup/
│   │   ├── globalSetup.js          # Start mongodb-memory-server
│   │   └── globalTeardown.js       # Stop mongodb-memory-server
│   └── utils/
│       ├── yaml.js                 # YAML parsing with date serialization
│       └── paths.js                # Snap directory resolution
└── README.md

Files to Create

File	Description
plugins/community-plugin-e2e-mdb/package.json	Package config with dependencies
plugins/community-plugin-e2e-mdb/src/index.js	Main exports
plugins/community-plugin-e2e-mdb/src/fixtures/index.js	mdbFixtures definition
plugins/community-plugin-e2e-mdb/src/mdb/createMdbHelper.js	Factory for mdb fixture object
plugins/community-plugin-e2e-mdb/src/mdb/snap.js	load() and snap() implementations
plugins/community-plugin-e2e-mdb/src/mdb/seed.js	seed() implementation
plugins/community-plugin-e2e-mdb/src/mdb/expect.js	Polling assertion matchers
plugins/community-plugin-e2e-mdb/src/mdb/collection.js	Direct collection access wrapper
plugins/community-plugin-e2e-mdb/src/setup/globalSetup.js	mongodb-memory-server startup
plugins/community-plugin-e2e-mdb/src/setup/globalTeardown.js	mongodb-memory-server shutdown
plugins/community-plugin-e2e-mdb/src/utils/yaml.js	YAML helpers with date handling
plugins/community-plugin-e2e-mdb/src/utils/paths.js	Path resolution utilities
plugins/community-plugin-e2e-mdb/README.md	Documentation

Implementation Steps

Step 1: Create package structure

Create the package directory with package.json:

{
  "name": "@lowdefy/community-plugin-e2e-mdb",
  "version": "1.0.0",
  "license": "MIT",
  "type": "module",
  "exports": {
    ".": "./dist/index.js",
    "./setup": "./dist/setup/globalSetup.js",
    "./teardown": "./dist/setup/globalTeardown.js"
  },
  "files": ["dist/*"],
  "dependencies": {
    "mongodb": "6.3.0",
    "mongodb-memory-server": "^10.0.0",
    "yaml": "^2.3.4"
  },
  "peerDependencies": {
    "@playwright/test": "^1.40.0"
  }
}

Step 2: Implement global setup/teardown

globalSetup.js:

• Start mongodb-memory-server
• Write URI to .mdb-e2e-state.json state file
• Set process.env.MONGODB_URI for webServer

globalTeardown.js:

• Stop mongodb-memory-server
• Clean up state file

Step 3: Implement YAML utilities

• parseYamlFile() - Parse with date deserialization (custom !~d tag)
• writeYamlFile() - Write with date serialization
• getYamlFiles() - List YAML files in directory

Step 4: Implement snap load/save

load(db, snapName):

• Read all YAML files from e2e/snaps/<snapName>/
• For each collection file:
  • Parse YAML content
  • Apply mode (replace: replaceOne, merge: $set)
  • If cleanup enabled: delete documents matching query but not in snap

snap(db, snapName, collections):

• For each collection:
  • Read existing YAML for query config
  • Query database with match/project
  • Write YAML with metadata, mode, cleanup, query, data

Step 5: Implement seed function

seed(db, collectionName, documents):

• Clear collection
• Insert provided documents

Step 6: Implement polling assertions

createExpect(db, options):

• Returns function that creates matchers for a collection
• toContainDocument(filter) - Poll until document exists
• toHaveDocumentCount(n) - Poll until count matches
• not.toContainDocument(filter) - Poll until document absent
• Configurable timeout (default 5000ms) and interval (default 100ms)

Step 7: Implement collection wrapper

createCollectionWrapper(db):

• Returns function that provides raw MongoDB collection access
• Escape hatch for complex operations

Step 8: Implement mdb helper factory

createMdbHelper(db, options):

• Returns object with: load, snap, seed, expect, collection, db

Step 9: Implement fixtures

export const mdbFixtures = {
  // Worker-scoped: MongoDB client
  mdbClient: [async ({}, use) => {
    const client = new MongoClient(getMongoUri());
    await client.connect();
    await use(client);
    await client.close();
  }, { scope: 'worker' }],

  // Test-scoped: mdb helper
  mdb: async ({ mdbClient }, use) => {
    const db = mdbClient.db('test');
    const mdb = createMdbHelper(db);
    await use(mdb);
    // Cleanup collections
  },
};

Step 10: Create main exports

Export mdbFixtures and individual utilities for advanced use cases.

Step 11: Create README documentation

Playwright Configuration Example

import { defineConfig } from '@playwright/test';

export default defineConfig({
  globalSetup: '@lowdefy/community-plugin-e2e-mdb/setup',
  globalTeardown: '@lowdefy/community-plugin-e2e-mdb/teardown',
  webServer: {
    command: 'npx lowdefy dev',
    url: 'http://localhost:3000',
    env: {
      MONGODB_URI: process.env.MONGODB_URI,
    },
  },
});

Developer Fixture Composition

// e2e/fixtures.js
import { test as ldfTest, expect } from '@lowdefy/e2e-utils/fixtures';
import { mdbFixtures } from '@lowdefy/community-plugin-e2e-mdb';

export const test = ldfTest.extend(mdbFixtures);
export { expect };

Test Usage Example

test('creates ticket', async ({ ldf, mdb }) => {
  // Setup: load snap files
  await mdb.load('clean-tickets');

  // Act via UI
  await ldf.goto('/tickets/new');
  await ldf.do.blocks['name_input'].fill('John Doe');
  await ldf.do.blocks['submit_btn'].click();

  // Assert DB state (auto-polls)
  await mdb.expect('tickets').toContainDocument({ name: 'John Doe' });
  await mdb.expect('tickets').toHaveDocumentCount(2);

  // Direct access escape hatch
  const doc = await mdb.collection('tickets').findOne({ name: 'John Doe' });
  expect(doc.priority).toBe('high');
});

Acceptance Verification

Criteria	Step
Package created as @lowdefy/community-plugin-e2e-mdb	Step 1
Package exports mdbFixtures object	Step 9, 10
Package has no dependency on @lowdefy/e2e-utils	Step 1
Uses mongodb-memory-server	Step 2
Each worker gets isolated database (via cleanup)	Step 9
mdb.load('name') reads YAML snap files	Step 4
mdb.snap('name') creates/updates snap files	Step 4
mdb.seed(collection, docs) clears and inserts	Step 5
mdb.expect(collection).toContainDocument(filter) polls	Step 6
mdb.expect(collection).toHaveDocumentCount(n) polls	Step 6
mdb.expect(collection).not.toContainDocument(filter) polls	Step 6
mdb.collection(name) returns raw collection	Step 7
Snap YAML format supports query/project, mode, cleanup	Step 4

Risks & Edge Cases

• Shared database instance: All workers share one mongodb-memory-server. Tests must clean up after themselves (handled in fixture teardown).
• Snap file conflicts: If multiple tests load different snaps, they could conflict. Recommend using unique snap names per test or test group.
• Date serialization: YAML dates need custom handling to match mdb-snapper format.

Related Work

• Request mocking: Add request mocking and payload capture to @lowdefy/e2e-utils lowdefy#1977 (moved to e2e-utils)
• Parent work: Create @lowdefy/e2e-utils package for app developers lowdefy#1970 - @lowdefy/e2e-utils package
• Tracking issue: Add MongoDB data testing (mdb fixture) to @lowdefy/e2e-utils lowdefy#1975 - MongoDB data testing brief

---

Plan Agent - Updated: 2026-02-04 CAT

[machielvdw]

Plan Progress

Status: ✅ Complete

Steps

• Read GitHub issue and comments
• Gathered context (docs, tickets, code)
  • Read e2e-utils fixtures system from Lowdefy core
  • Read mdb-snapper tool design and implementation
  • Explored community-plugins repo structure
• Asked technical questions (3 decisions)
• Generated implementation plan
• Reviewed with user
• Posted to GitHub
• Follow-up: Moved request mocking to separate issue

Decisions Made

Decision	Choice	Reason
Database strategy	Global setup starts mongodb-memory-server	Single instance shared by workers, faster startup, URI passed via env var
Snap location	Central e2e/snaps//	Matches mdb-snapper pattern, clear separation
Request mocking	Moved to e2e-utils (lowdefy/lowdefy#1977)	Not MongoDB-specific, belongs in core package

Notes

• Context: Referenced mdb-snapper tool at /Users/machiel/Documents/GitHub/prp/tools/mdb-snapper for snap file format inspiration
• Context: Referenced @lowdefy/e2e-utils fixtures system for integration patterns
• The package will have no dependency on e2e-utils—works with any Playwright project
• Uses worker-scoped MongoDB client for efficient connection sharing
• Follow-up (Scope change): Request mocking/capture moved to Add request mocking and payload capture to @lowdefy/e2e-utils lowdefy#1977 - it's not MongoDB-specific and belongs in core e2e-utils package

Plan Agent - Last updated: 2026-02-04 CAT