x
This commit is contained in:
Your Name committed
1 parent
70877882b0
commit
ce2f4cf0c8
93 files changed
+4200
-67
No files matched your search
+174
@@ -0,0 +1,174 @@
|
||||
# Premium Mega Menu E2E Testing Track
|
||||
|
||||
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
|
||||
```typescript
|
||||
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:
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
# 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.
|
||||
Reference in new issue
Block a user