@nuucognition/mesh-integration-tests

End-to-end verification that mesh-core, mesh-convex-component, and mesh-adapter-convex work together correctly. Proves the full Convex Track pipeline: markdown -> parse -> save to Convex -> load back -> verify.

This is a test-only package with no public exports.

Quick start

# Run all 27 tests (in-memory, no deployment needed)
pnpm --filter @nuucognition/mesh-integration-tests test

# Start real Convex dev server (first time creates project)
pnpm --filter @nuucognition/mesh-integration-tests dev

# Seed fixture data to real backend
pnpm --filter @nuucognition/mesh-integration-tests seed

# Clear seeded data
pnpm --filter @nuucognition/mesh-integration-tests seed:clear

Test suites

Component-level tests (tests/integration/)

Test mesh-core + mesh-convex-component directly via convex-test in-memory sandbox.

| File | Tests | Covers | |------|-------|--------| | roundtrip.test.ts | 6 | Save/load cycle, ID preservation, types/tags, links, content equality, empty mesh | | load-mesh.test.ts | 3 | Backlink index, tag index, type index | | blob-ops.test.ts | 3 | Blob save/load, URL retrieval, name index | | frontmatter.test.ts | 2 | Nested YAML preservation, identical re-parse |

Adapter E2E tests (tests/e2e/)

Test the full pipeline through MeshConvexAdapter -> MeshConvex -> Convex component -> mesh-core.

| File | Tests | Covers | |------|-------|--------| | adapter-roundtrip.test.ts | 6 | Full adapter save/load pipeline, IDs, metadata, content, indexes, empty mesh | | adapter-crud.test.ts | 4 | Save/delete, missing delete, overwrite, multi-doc lifecycle | | adapter-blobs.test.ts | 3 | Blob save/load, blob delete, name index |

Total: 27 tests across 7 files.

Fixtures

Documents (tests/fixtures/documents/)

| File | Purpose | |------|---------| | note.md | Basic document with ID, type, tags | | task.md | Document with wiki-links and multiple tags | | linked-doc.md | Links, embeds, and a broken link | | complex-frontmatter.md | Nested YAML (objects, arrays, booleans, numbers) |

Blobs (tests/fixtures/blobs/)

| File | Size | Content type | |------|------|-------------| | photo.jpg | 3.5KB | image/jpeg | | avatar.jpg | 4KB | image/jpeg | | icon.jpg | 1.8KB | image/jpeg | | diagram.svg | 861B | image/svg+xml |

Loader API (tests/fixtures/index.ts)

| Function | Returns | |----------|---------| | loadFixture(name) | { title, content } | | loadAllFixtures() | { title, content }[] | | loadBlobFixture(file) | Buffer | | loadAllBlobFixtures() | { blobKey, data, contentType }[] |

Real Convex dev server

In addition to the in-memory test sandbox, this package includes a real Convex app for interactive exploration via the Convex dashboard.

Setup

pnpm dev    # starts Convex dev server, generates convex/_generated/ and .env.local
pnpm seed   # seeds 2 meshes + 4 documents + 4 blobs

Architecture

scripts/seed.ts (ConvexHttpClient over HTTP)
  -> convex/seed.ts (app-level mutation)
    -> components.mesh.meshes.create / documents.save / blobs.save
      -> mesh:meshes, mesh:documents, mesh:blobs tables
         (visible at dashboard.convex.dev)

Proxy layer

ConvexHttpClient can only call app-level functions, not component functions directly. convex/meshProxy.ts provides thin wrappers:

• Meshes: createMesh, getMesh, listMeshes, removeMesh
• Documents: saveDocument, listDocuments, getDocumentContent, removeDocument
• Blobs: generateUploadUrl, saveBlob, listBlobs, removeBlob

Seeded data

| Mesh ID | Name | Documents | Blobs | |---------|------|-----------|-------| | test-fixtures | Test Fixtures | 4 | 4 | | empty-mesh | Empty Mesh | 0 | 0 |

Test helpers (tests/setup.ts)

| Helper | Purpose | |--------|---------| | createIntegrationTest() | Creates convex-test instance with mesh component schema + modules | | createAdapterTest() | Creates MeshConvexAdapter + MeshConvex wired to test instance | | loadMeshFromConvex(t, api, meshId) | Inlined load flow for component-level tests |

Package layout

convex/                 Real Convex app (for dev server)
  convex.config.ts      App definition + mesh component install
  schema.ts             Empty app schema
  meshProxy.ts          Proxy functions forwarding to component
  seed.ts               Batch seed/clear mutations
scripts/
  seed.ts               Client-side seeder using ConvexHttpClient
tests/
  setup.ts              Test harness (convex-test wiring)
  fixtures/
    documents/          4 markdown fixture files
    blobs/              4 image fixture files
    index.ts            Loader functions
  integration/          4 component-level test files (14 tests)
  e2e/                  3 adapter E2E test files (13 tests)

Related packages

• @nuucognition/mesh-core — core types, parsing, building
• @nuucognition/mesh-convex-component — Convex component and client
• @nuucognition/mesh-adapter-convex — adapter bridge