homaroma/TEST_INFRA.md

Premium Mega Menu E2E Testing Track

Reference-tenant test fixtures: HomAroma URLs, fragrance categories, and media in examples are fixtures for the reference tenant. The shared assertions apply only where the target tenant enables the same mega-menu capability.

This document details the E2E testing infrastructure, strategy, feature inventory, and coverage requirements for the Premium Mega Menu. The testing track ensures that both the Next.js storefront and the Elysia backend work in tandem, handling new image-related metadata fields correctly from the DB up to the UI.

---

1. Test Philosophy

We follow an opaque-box, requirement-driven testing philosophy utilizing the Bun test runner.

• Opaque-Box (Black-Box): The tests interact with the application solely through public interfaces—namely REST APIs, JSON-RPC (for the MCP server), and HTTP endpoints (for the Next.js SSR HTML output). We do not mock database queries, internal React state, or component-level logic. This guarantees that test results verify the actual behavior of the system as a whole.
• Requirement-Driven: Every test case directly traces back to a system requirement. We verify that specific payloads are parsed, specific HTML elements are rendered with precise attributes, and responsive layouts behave correctly according to mobile vs. desktop specifications.
• Bun Test Runner: We leverage Bun’s built-in fast test runner (bun test) which natively supports TypeScript, enabling rapid and lightweight execution of our end-to-end suite.

---

2. Test Architecture

The E2E test suite dynamically orchestrates and inspects the application layers.

       ┌────────────────────────┐
       │   Bun Test Runner      │
       │ (tests/mega-menu.test) │
       └───────────┬────────────┘
                   │
         ┌─────────┴─────────┐
         ▼                   ▼
┌────────────────┐   ┌───────────────┐
│ Next.js Store  │   │ Elysia API    │◀───[ Prisma / DB ]
│ (apps/website) │   │ (apps/backend)│
└────────┬───────┘   └───────────────┘
         │                   ▲
         │ (SSR Inspect)     │ (Seed Payload / MCP Calls)
         ▼                   │
   [ Cheerio / Fetch ] ──────┘

• Dynamic Service Orchestration:
  • The Elysia backend server is spawned and runs on a local port (e.g. http://localhost:3001).
  • The Next.js storefront server is spawned and runs on a local port (e.g. http://localhost:3002).
  • DB states are initialized via migrations and seeded before the test run.
• HTTP & HTML Inspections:
  • We use standard fetch or axios to execute requests to the storefront endpoints (e.g., GET / or any layout routing containing the navigation header).
  • We load the returned HTML body into Cheerio to parse and verify the server-rendered DOM elements.
• MCP Integration Verification:
  • The MCP tools server (homaroma_mcp) is tested by initiating tool execution requests.
  • Payloads containing the new menu schema are updated and read back to confirm that the tools do not drop or corrupt image fields.

---

3. Feature Inventory

Feature 1: Seeding Premium Mega Menu Payload

Verifies that the backend accepts, stores, and serves a full hierarchical menu payload containing the new premium menu image fields.

• Payload Mapping:
  • rootImage (stored as rootImage in the database Menu table; mapped to rootImageUrl in the frontend MegaMenuPayload).
  • columnImage (stored as columnImage in the database MenuItem table; mapped to iconUrl in the frontend MenuColumn).
  • hoverImage (stored as hoverImage in the database MenuItem table; mapped to imageUrl in the frontend MenuLink).
• Seeding Verification:
  • Direct POST request to the menu upsert API endpoint.
  • GET request to the menu API endpoint to verify JSON parity.
  • Direct Prisma database select verification to check raw DB storage.

Feature 2: Storefront Server-Rendered HTML Verification

Verifies that the Next.js App Router successfully parses the menu payload on the server and generates SEO-compliant, semantic HTML containing the mega menu structure.

• Cheerio Dom Inspections:
  • Confirming that the navigation bar elements are present inside the desktop layout.
  • Asserting the desktop-specific container exists with the appropriate Tailwind responsive display styles (hidden md:flex).
• next/image Attributes Verification:
  • Asserting that next/image converts the image URLs into optimized <img> tags.
  • Checking that output <img> elements contain correct src paths matching our seeded images.
  • Verifying presence of responsive attributes, such as the fill rendering patterns and the sizes attribute (e.g. sizes="(max-width: 1024px) 0px, 224px").
• Lazy Loading Properties for Hover Images:
  • Asserting that the hover-preview panel image has the loading="lazy" attribute to prevent prefetching non-visible offscreen images until a user hovers.
• CSS/Layout Classes:
  • Verifying standard layout classes (flex, grid, absolute, relative, rounded-xl, border-black/8, etc.) exist on the image wrapper divs.
  • Verifying the preview panels and dropdown layers have appropriate backdrop blur and opacity transition classes.

Feature 3: Responsive Layout Verification

Ensures that the responsive layout rules are correctly applied and that heavy visual assets are hidden from mobile clients for bandwidth and performance optimization.

• Desktop vs. Mobile Viewport Classes:
  • Asserting that the desktop mega menu container has the hidden md:flex layout classes.
  • Asserting that the mobile drawer wrapper has md:hidden classes.
• Mobile Drawer DOM Constraints:
  • Loading the HTML in Cheerio and simulating the mobile drawer state.
  • Verifying that while the text hierarchies and navigation links (e.g., categories, sub-links) are present in the mobile drawer markup, the complex image elements (rootImageUrl, iconUrl, and hoverImage) are not rendered inside the mobile drawer structures (MobileDrawer). This ensures that mobile clients are not forced to download desktop-oriented visual previews.

Feature 4: MCP Tools API Integration

Verifies that Model Context Protocol (MCP) server endpoints can interface with the backend data layer and manipulate the new image fields without validation errors.

• Tool Executions:
  • Calling the upsert_menu tool with a payload containing rootImage, columnImage, and hoverImage.
  • Calling the get_menu tool and asserting that the returned payload contains the new fields correctly formatted.
  • Validation checks to ensure the server rejects invalid values (e.g., throwing a validation error if a non-string value is passed to rootImage).

---

4. Test Suite Design

The E2E tests are implemented under tests/mega-menu.test.ts as a Bun test suite.

Mock Seed Payload

const mockMegaMenuPayload = {
  name: "premium_mega_menu",
  rootImage: "https://homaroma.shop/assets/menu-root-aroma.jpg",
  items: [
    {
      label: { en: "Home Fragrance", th: "เครื่องหอมแต่งบ้าน" },
      url: "/category/home-fragrance",
      columns: [
        {
          title: { en: "Scented Candles", th: "เทียนหอม" },
          columnImage: "https://homaroma.shop/assets/candle-icon.jpg",
          links: [
            {
              label: { en: "Lavender Scent", th: "กลิ่นลาเวนเดอร์" },
              url: "/products/lavender-candle",
              hoverImage: "https://homaroma.shop/assets/lavender-candle-hover.jpg"
            }
          ]
        }
      ]
    }
  ]
};

Coverage Assertions Matrix

Target Feature	Test Action	Assertion Detail	Expected Result
Feature 1	POST /api/menus	HTTP Status Code	200 OK or 201 Created
	GET /api/menus/premium_mega_menu	JSON structure inspection	Payload matches mockMegaMenuPayload properties
Feature 2	GET / (Next.js SSR)	Cheerio selector search for Desktop menu	Presence of .hidden.md\:flex container
		Parse images inside desktop mega menu	<img> elements found with src pointing to menu-root-aroma.jpg and candle-icon.jpg
		Check next/image attributes	sizes="(max-width: 1024px) 0px, 224px" present
		Check lazy loading on hover image	loading="lazy" attribute present on hover image element
		Check layout styling	rounded-xl, border-black/8 present on container wrappers
Feature 3	GET / (Next.js SSR)	Cheerio selector search for Mobile Menu	Presence of mobile wrapper with class containing md:hidden
		Check image absence in mobile drawer	No <img> tags or visual layouts rendering rootImage, columnImage, or hoverImage inside mobile drawer container
Feature 4	call_mcp_tool upsert_menu	JSON-RPC response verification	success: true response from MCP server
	call_mcp_tool get_menu	Return payload validation	Payload contains rootImage, columnImage, and hoverImage

---

5. Execution Reference

Pre-requisites

Ensure database migrations are applied and the local server ports are available:

# Apply migrations to local DB
bunx prisma migrate deploy

# Build Next.js storefront for production-like SSR testing
bun run build -w apps/website

Executing the Test Suite

Run the test runner using the Bun CLI:

# Execute mega menu E2E tests
bun test tests/mega-menu.test.ts

Environment Configurations

The test suite utilizes the following environment variables:

• TEST_BACKEND_URL: URL of the spawned Elysia API backend (defaults to http://localhost:3001).
• TEST_STOREFRONT_URL: URL of the spawned Next.js storefront (defaults to http://localhost:3002).
• DATABASE_URL: Connection string for PostgreSQL database context.