@decocms/start 0.19.0

package/.cursor/skills/deco-e2e-testing/discovery.md

@@ -0,0 +1,337 @@
+# Site Discovery Guide
+
+Before implementing e2e tests, you MUST discover these site-specific values. This guide shows exactly where to find each one.
+
+## Required Information Checklist
+
+| Info | Status | Value |
+|------|--------|-------|
+| Site URL | ☐ | |
+| PLP Path | ☐ | |
+| Fallback PDP Path | ☐ | |
+| Product Card Selector | ☐ | |
+| Buy Button Selector | ☐ | |
+| Size Button Pattern | ☐ | |
+| Available Sizes | ☐ | |
+| Minicart Text | ☐ | |
+| Currency Symbol | ☐ | |
+| Voltage Options | ☐ | (electronics only) |
+
+---
+
+## Framework Endpoints
+
+All Deco sites have these built-in endpoints:
+
+| Endpoint | Purpose |
+|----------|---------|
+| `/deco/_liveness` | Health check - returns 200 when server is ready |
+| `?__d` | Debug mode - adds server-timing headers |
+
+The liveness endpoint is critical for test warmup - see SKILL.md for details.
+
+---
+
+## 1. Site URL
+
+**Where to find:**
+- `deno.json` → look for `site` or site name
+- `apps/site.ts` → site configuration
+- Any `.deco.site` URL references
+
+**Search commands:**
+```bash
+grep -r "deco.site" deno.json apps/
+grep -r "localhost--" .
+```
+
+**Format:** `https://localhost--{sitename}.deco.site`
+
+---
+
+## 2. PLP Path (Category Page)
+
+**Where to find:**
+- `components/header/` → menu/nav components
+- `sections/Header*.tsx` → navigation links
+- `static/` → sitemap or nav configs
+
+**Search commands:**
+```bash
+grep -r 'href="/' components/header/
+grep -r 'href="/' sections/Header*.tsx
+```
+
+**Common patterns:**
+- `/feminino`, `/masculino` (fashion)
+- `/roupas`, `/calcados` (apparel)
+- `/category/{slug}` (generic)
+
+---
+
+## 3. Fallback PDP Path
+
+**Where to find:**
+- Any product URL in sections or loaders
+- Search for `/p` suffix (VTEX pattern)
+- Product loader test fixtures
+
+**Search commands:**
+```bash
+grep -r '"/.*\/p"' sections/ loaders/
+grep -r 'productId\|skuId' loaders/
+```
+
+**Format:** `/product-name-sku/p`
+
+**IMPORTANT - Choosing a good fallback product:**
+- **Avoid electronics** that require voltage selection (110V/220V modals block the cart)
+- **Avoid fashion items** that require size selection if possible
+- **Prefer simple products** like:
+  - Thermal boxes, containers
+  - Pillows, towels, bedding
+  - Kitchen utensils
+  - Decorative items
+- Look for products in `.deco/blocks/` JSON files that link to `/p` URLs
+
+---
+
+## 4. Product Card Selector
+
+**Where to find:**
+- `components/product/ProductCard.tsx`
+- Look for the main link/anchor wrapping the product
+
+**Search commands:**
+```bash
+cat components/product/ProductCard.tsx | head -100
+grep -r 'data-product\|ProductCard' components/
+```
+
+**Read the file and identify:**
+- What wrapper element is clickable?
+- What text always appears? (usually price)
+
+**Common selectors:**
+| Platform | Selector |
+|----------|----------|
+| VTEX (BRL) | `a:has-text("R$")` |
+| VTEX (USD) | `a:has-text("$")` |
+| Generic | `[data-product-card]` |
+| Shopify | `.product-item a` |
+
+---
+
+## 5. Buy Button Selector
+
+**Where to find:**
+- `components/product/AddToCartButton.tsx`
+- `components/product/ProductDetails.tsx`
+- `islands/AddToCartButton.tsx`
+
+**Search commands:**
+```bash
+grep -r 'Comprar\|Add to Cart\|Adicionar' components/product/
+grep -r 'addToCart\|add-to-cart' islands/
+```
+
+**Common selectors:**
+| Language | Selector |
+|----------|----------|
+| PT-BR | `button:has-text("Comprar")` |
+| EN | `button:has-text("Add to Cart")` |
+| Generic | `button[data-add-to-cart]` |
+
+---
+
+## 6. Size Button Pattern
+
+**Where to find:**
+- `components/product/VariantSelector.tsx`
+- `components/product/Sizes.tsx`
+- `islands/Sizes.tsx`
+
+**Search commands:**
+```bash
+cat components/product/VariantSelector.tsx
+grep -r 'size\|variant\|sku' components/product/
+```
+
+**Common patterns:**
+| Structure | Pattern |
+|-----------|---------|
+| List buttons | `li button:has-text("${size}")` |
+| Direct buttons | `button[data-size="${size}"]` |
+| Radio inputs | `input[value="${size}"]` |
+
+---
+
+## 7. Available Sizes
+
+**Where to find:**
+- Same files as size button
+- Look for size arrays or enums
+- Check variant options in product loaders
+
+**Common size sets:**
+| Type | Sizes |
+|------|-------|
+| Clothing (BR) | `['PP', 'P', 'M', 'G', 'GG', 'G1', 'G2']` |
+| Clothing (US) | `['XS', 'S', 'M', 'L', 'XL', 'XXL']` |
+| Shoes (BR) | `['34', '35', '36', '37', '38', '39', '40', '41', '42']` |
+| Shoes (US) | `['6', '7', '8', '9', '10', '11', '12']` |
+
+---
+
+## 8. Voltage Options (Electronics Stores)
+
+**When needed:** For stores selling electronics (appliances, TVs, etc), products may require voltage selection before adding to cart.
+
+**Where to find:**
+- Same components as size selector
+- Look for voltage-specific variant handling
+
+**Search commands:**
+```bash
+grep -r 'voltage\|tensao\|110V\|220V' components/product/
+grep -r 'Bivolt' components/
+```
+
+**Common voltages:**
+```typescript
+voltages: ['110V', '127V', '220V', 'Bivolt']
+```
+
+**Common selectors:**
+```typescript
+voltageSelector: (voltage: string) => `button:has-text("${voltage}")`
+```
+
+---
+
+## 9. Minicart Text
+
+**Where to find:**
+- `components/minicart/`
+- `islands/Cart.tsx`
+- Look for drawer/modal header
+
+**Search commands:**
+```bash
+grep -r 'Sacola\|Cart\|Bag\|Carrinho' components/minicart/
+cat components/minicart/Cart.tsx | head -50
+```
+
+**Common values:**
+| Language | Text |
+|----------|------|
+| PT-BR | `Minha Sacola` |
+| EN | `Your Cart` or `Shopping Bag` |
+
+---
+
+## 9. Currency Symbol
+
+**Where to find:**
+- `sdk/format.ts` or similar
+- Price components
+- Locale configuration
+
+**Common values:**
+- `R$` (Brazil)
+- `$` (US/Generic)
+- `€` (Europe)
+
+---
+
+## Discovery Workflow
+
+1. **Clone/open the site repo**
+2. **Run discovery searches** for each item above
+3. **Read key component files** to verify selectors
+4. **Test selectors manually** in browser DevTools:
+   ```javascript
+   // In browser console on the live site:
+   document.querySelectorAll('a:has-text("R$")').length
+   document.querySelectorAll('button:has-text("Comprar")').length
+   ```
+5. **Fill in the checklist** and proceed to implementation
+
+---
+
+## 10. Deco Observability Headers
+
+The test suite captures these Deco-specific headers for debugging:
+
+| Header | Source | Purpose |
+|--------|--------|---------|
+| `x-deco-section` | `/deco/render` response | Section component type and title |
+| `x-deco-page` | Page response | Matched page block name |
+| `x-deco-route` | Page response | Matched route template |
+| `x-deco-platform` | All responses | Platform identifier |
+| `server-timing` | `?__d` mode | Loader timings and cache status |
+
+**These are set automatically by the Deco runtime.** If they're missing, ensure you're using a recent version of:
+- `@deco/deco` (runtime)
+- `apps/website/handlers/fresh.ts` (page handler)
+
+---
+
+## Example: Completed Discovery
+
+### Brazilian Fashion E-commerce
+
+```typescript
+const SITE_CONFIG = {
+    baseUrl: 'https://localhost--lojastorra-2.deco.site',
+    plpPath: '/feminino',
+    fallbackPdpPath: '/macaquinho-feminino-curto-berry-16171000788507/p',
+    debugParam: '?__d',
+    
+    productCard: 'a:has-text("R$")',
+    pdpUrlPattern: /\/p/,
+    buyButton: 'button:has-text("Comprar")',
+    sizeButton: (size: string) => `li button:has-text("${size}")`,
+    minicartText: 'Minha Sacola',
+    
+    sizes: ['PP', 'P', 'M', 'G', 'GG', 'G1', 'G2', 'G3', '38', '40', '42'],
+    
+    thresholds: {
+        coldTTFB: 5000,
+        warmTTFB: 2000,
+        homeTTFB: 3000,
+    },
+}
+```
+
+### Brazilian Electronics Store (Casa e Video)
+
+```typescript
+const SITE_CONFIG = {
+    baseUrl: 'https://localhost--casaevideo.deco.site',
+    // Use non-electronics PLP to avoid voltage selection
+    plpPath: '/utilidades-domesticas',
+    // Simple product without voltage/size variants
+    fallbackPdpPath: '/caixa-termica-12l-botafogo-azul/p',
+    debugParam: '?__d',
+
+    // Deco-specific data attribute
+    productCard: '[data-deco="view-product"]',
+    productCardFallback: 'a:has-text("R$")',
+    pdpUrlPattern: /\/p/,
+    buyButton: 'button:has-text("Comprar agora")',
+    buyButtonFallback: 'button:has-text("Comprar")',
+    minicartText: 'Produtos Adicionados',
+
+    // Electronics store - voltage selection
+    voltages: ['110V', '127V', '220V', 'Bivolt'],
+    voltageSelector: (voltage: string) => `button:has-text("${voltage}")`,
+
+    thresholds: {
+        coldTTFB: 5000,
+        warmTTFB: 2000,
+        homeTTFB: 3000,
+        homeWarmTTFB: 1500,
+    },
+}
+```

package/.cursor/skills/deco-e2e-testing/scripts/scaffold.sh

@@ -0,0 +1,81 @@
+#!/bin/bash
+#
+# Scaffold E2E test structure for a Deco site
+#
+# Usage:
+#   ./scaffold.sh /path/to/site-repo site-name
+#
+# Example:
+#   ./scaffold.sh ~/Projects/lojastorra-2 lojastorra-2
+#
+
+set -e
+
+SITE_PATH="${1:-.}"
+SITE_NAME="${2:-my-site}"
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+TEMPLATES_DIR="$SCRIPT_DIR/templates"
+
+echo "🚀 Scaffolding E2E tests for: $SITE_NAME"
+echo "   Site path: $SITE_PATH"
+echo "   Templates: $TEMPLATES_DIR"
+echo ""
+
+# Create directory structure
+E2E_DIR="$SITE_PATH/tests/e2e"
+mkdir -p "$E2E_DIR/specs"
+mkdir -p "$E2E_DIR/utils"
+mkdir -p "$E2E_DIR/reports"
+
+# Copy and customize templates
+echo "📁 Creating files..."
+
+# package.json
+sed "s/{{SITE_NAME}}/$SITE_NAME/g" "$TEMPLATES_DIR/package.json" > "$E2E_DIR/package.json"
+echo "   ✓ package.json"
+
+# playwright.config.ts
+sed "s/{{SITE_NAME}}/$SITE_NAME/g" "$TEMPLATES_DIR/playwright.config.ts" > "$E2E_DIR/playwright.config.ts"
+echo "   ✓ playwright.config.ts"
+
+# tsconfig.json
+cp "$TEMPLATES_DIR/tsconfig.json" "$E2E_DIR/tsconfig.json"
+echo "   ✓ tsconfig.json"
+
+# Test spec (needs manual customization)
+sed "s/{{SITE_NAME}}/$SITE_NAME/g" "$TEMPLATES_DIR/specs/ecommerce-flow.spec.ts" > "$E2E_DIR/specs/ecommerce-flow.spec.ts"
+echo "   ✓ specs/ecommerce-flow.spec.ts"
+
+# Metrics collector
+cp "$TEMPLATES_DIR/utils/metrics-collector.ts" "$E2E_DIR/utils/metrics-collector.ts"
+echo "   ✓ utils/metrics-collector.ts"
+
+# Add reports to .gitignore if not already there
+GITIGNORE="$SITE_PATH/.gitignore"
+if [ -f "$GITIGNORE" ]; then
+    if ! grep -q "tests/e2e/reports" "$GITIGNORE"; then
+        echo "" >> "$GITIGNORE"
+        echo "# E2E test reports" >> "$GITIGNORE"
+        echo "tests/e2e/reports/" >> "$GITIGNORE"
+        echo "   ✓ Updated .gitignore"
+    fi
+fi
+
+echo ""
+echo "✅ Scaffold complete!"
+echo ""
+echo "📋 Next steps:"
+echo "   1. cd $E2E_DIR"
+echo "   2. Open specs/ecommerce-flow.spec.ts"
+echo "   3. Replace {{PLACEHOLDERS}} with your site values:"
+echo "      - {{PLP_PATH}}"
+echo "      - {{FALLBACK_PDP_PATH}}"
+echo "      - {{PRODUCT_CARD_SELECTOR}}"
+echo "      - {{BUY_BUTTON_SELECTOR}}"
+echo "      - {{MINICART_TEXT}}"
+echo ""
+echo "   4. npm install"
+echo "   5. npx playwright install chromium"
+echo "   6. npm test"
+echo ""
+echo "📖 See discovery.md for how to find each value."

package/.cursor/skills/deco-e2e-testing/selectors.md

@@ -0,0 +1,175 @@
+# Platform-Specific Selectors
+
+Different e-commerce platforms have different DOM structures. Use these as starting points.
+
+## VTEX-based Sites (Most Deco Sites)
+
+VTEX is the most common backend for Deco sites in Brazil.
+
+```typescript
+const SITE_CONFIG = {
+    // Products always show price with R$
+    productCard: 'a:has-text("R$")',
+    
+    // PDP URLs end with /p
+    pdpUrlPattern: /\/p$/,
+    
+    // Portuguese buy button
+    buyButton: 'button:has-text("Comprar")',
+    
+    // Sizes in list items
+    sizeButton: (size: string) => `li button:has-text("${size}")`,
+    
+    // Cart drawer header
+    minicartText: 'Minha Sacola',
+    
+    // Brazilian sizes
+    sizes: ['PP', 'P', 'M', 'G', 'GG', 'G1', 'G2', 'G3'],
+}
+```
+
+**Cart API patterns to wait for:**
+```typescript
+await page.waitForResponse(r => 
+    r.url().includes('orderForm') ||  // VTEX orderForm API
+    r.url().includes('/items')        // Cart items endpoint
+)
+```
+
+---
+
+## Shopify-based Sites
+
+```typescript
+const SITE_CONFIG = {
+    productCard: '[data-product-card] a',
+    pdpUrlPattern: /\/products\//,
+    buyButton: 'button[name="add"]',
+    sizeButton: (size: string) => `input[value="${size}"]`,
+    minicartText: 'Your Cart',
+    sizes: ['XS', 'S', 'M', 'L', 'XL'],
+}
+```
+
+**Cart API patterns:**
+```typescript
+await page.waitForResponse(r => 
+    r.url().includes('/cart/add') ||
+    r.url().includes('/cart.js')
+)
+```
+
+---
+
+## VNDA-based Sites
+
+```typescript
+const SITE_CONFIG = {
+    productCard: '.product-item a',
+    pdpUrlPattern: /\/produto\//,
+    buyButton: 'button.add-to-cart',
+    sizeButton: (size: string) => `.variant-option:has-text("${size}")`,
+    minicartText: 'Carrinho',
+    sizes: ['P', 'M', 'G', 'GG'],
+}
+```
+
+---
+
+## Wake Commerce Sites
+
+```typescript
+const SITE_CONFIG = {
+    productCard: '[data-product] a',
+    pdpUrlPattern: /\/p\//,
+    buyButton: 'button:has-text("Adicionar")',
+    sizeButton: (size: string) => `[data-variant="${size}"]`,
+    minicartText: 'Sacola',
+    sizes: ['P', 'M', 'G', 'GG'],
+}
+```
+
+---
+
+## English Language Sites (US/International)
+
+```typescript
+const SITE_CONFIG = {
+    productCard: 'a:has-text("$")',  // USD currency
+    buyButton: 'button:has-text("Add to Cart")',
+    minicartText: 'Shopping Bag',
+    sizes: ['XS', 'S', 'M', 'L', 'XL', 'XXL'],
+}
+```
+
+---
+
+## Selector Testing Tips
+
+### In Browser DevTools
+
+Test your selectors before using them:
+
+```javascript
+// Count matching elements
+document.querySelectorAll('a:has-text("R$")').length
+
+// Check if element is visible
+document.querySelector('button:has-text("Comprar")')?.offsetParent !== null
+
+// Find all size buttons
+document.querySelectorAll('li button').forEach(b => console.log(b.textContent))
+```
+
+### In Playwright
+
+```typescript
+// Debug: log all matching elements
+const products = await page.locator('a:has-text("R$")').all()
+console.log(`Found ${products.length} products`)
+
+// Debug: take screenshot of element
+await page.locator('button:has-text("Comprar")').screenshot({ path: 'buy-button.png' })
+```
+
+---
+
+## Fallback Strategies
+
+When primary selectors fail:
+
+### Product Cards
+```typescript
+// Try multiple patterns
+const selectors = [
+    'a:has-text("R$")',
+    '[data-product-card]',
+    '.product-card a',
+    'a[href*="/p"]',
+]
+
+for (const sel of selectors) {
+    const count = await page.locator(sel).count()
+    if (count > 0) {
+        console.log(`Using selector: ${sel} (${count} matches)`)
+        return sel
+    }
+}
+```
+
+### Buy Button
+```typescript
+const buySelectors = [
+    'button:has-text("Comprar")',
+    'button:has-text("Add to Cart")',
+    'button:has-text("Adicionar")',
+    'button[data-add-to-cart]',
+    '.add-to-cart-button',
+]
+```
+
+### Sizes
+```typescript
+// Generic: any button with short text (likely a size)
+const sizeButtons = page.locator('li button').filter({ hasText: /^[A-Z0-9]{1,3}$/ })
+```

package/.cursor/skills/deco-e2e-testing/templates/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "{{SITE_NAME}}-e2e-tests",
+  "version": "1.0.0",
+  "description": "E2E Performance Tests for {{SITE_NAME}}",
+  "type": "module",
+  "scripts": {
+    "test": "npx playwright test",
+    "test:headed": "HEADED=true npx playwright test --headed",
+    "test:debug": "npx playwright test --debug",
+    "install-browsers": "npx playwright install chromium",
+    "baseline:save": "deno run -A scripts/baseline.ts save",
+    "baseline:compare": "deno run -A scripts/baseline.ts compare",
+    "baseline:list": "deno run -A scripts/baseline.ts list"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.40.0"
+  }
+}

package/.cursor/skills/deco-e2e-testing/templates/playwright.config.ts

@@ -0,0 +1,65 @@
+import { defineConfig, devices } from '@playwright/test'
+
+/**
+ * Playwright configuration for E2E Performance Tests
+ * 
+ * Environment variables:
+ *   SITE_URL - Target URL to test (default: localhost tunnel)
+ *   HEADED - Set to 'true' for headed mode
+ */
+
+const isHeaded = process.env.HEADED === 'true'
+
+export default defineConfig({
+    testDir: './specs',
+    fullyParallel: false,
+    forbidOnly: !!process.env.CI,
+    retries: process.env.CI ? 2 : 0,
+    workers: 1,
+    
+    timeout: 120_000,
+    expect: { timeout: 10_000 },
+    
+    reporter: [
+        ['list'],
+        ['html', { open: 'never' }],
+        ['json', { outputFile: 'reports/results.json' }],
+    ],
+    
+    use: {
+        // REPLACE WITH YOUR SITE URL
+        baseURL: process.env.SITE_URL || 'https://localhost--{{SITE_NAME}}.deco.site',
+        
+        trace: 'on-first-retry',
+        screenshot: 'only-on-failure',
+        video: 'on-first-retry',
+        viewport: { width: 1280, height: 720 },
+        reducedMotion: 'reduce',
+        headless: !isHeaded,
+    },
+
+    projects: [
+        {
+            name: 'desktop-chrome',
+            use: { 
+                ...devices['Desktop Chrome'],
+                launchOptions: {
+                    args: ['--enable-precise-memory-info'],
+                    slowMo: isHeaded ? 100 : 0,
+                },
+            },
+        },
+        {
+            name: 'mobile-chrome',
+            use: { 
+                ...devices['Pixel 5'],
+                launchOptions: {
+                    args: ['--enable-precise-memory-info'],
+                    slowMo: isHeaded ? 100 : 0,
+                },
+            },
+        },
+    ],
+
+    outputDir: './reports/test-results/',
+})