/testing-blocks

name: testing-blocks
description: "Use this when you have made AEM Edge Delivery Services code changes to blocks, scripts, or styles and need to validate them before opening a pull request. Covers unit testing for utilities and logic, browser testing with Playwright, linting, and guidance on what to test and how."
license: Apache-2.0
metadata:
  version: "2.0.1"

Testing Blocks

This skill guides you through testing code changes in AEM Edge Delivery Services projects. Testing follows a value-versus-cost philosophy: create and maintain tests when the value they bring exceeds the cost of creation and maintenance.

**CRITICAL: Browser validation is MANDATORY. You cannot complete this skill without providing proof of functional testing in a real browser environment.**

Related Skills

• **content-driven-development**: Test content created during CDD serves as the basis for testing
• **building-blocks**: Invokes this skill during Step 5 for comprehensive testing
• **block-collection-and-party**: May provide reference test patterns from similar blocks

When to Use This Skill

Use this skill:

• ✅ After implementing or modifying blocks
• ✅ After changes to core scripts (scripts.js, delayed.js, aem.js)
• ✅ After style changes (styles.css, lazy-styles.css)
• ✅ After configuration changes that affect functionality
• ✅ Before opening any pull request with code changes

This skill is typically invoked by the **building-blocks** skill during Step 5 (Test Implementation).

Testing Workflow

Track your progress:

• [ ] Step 1: Run linting and fix issues
• [ ] Step 2: Perform browser validation (MANDATORY)
• [ ] Step 3: Determine if unit tests are needed (optional)
• [ ] Step 4: Run existing tests and verify they pass

Step 1: Run Linting

**Run linting first to catch code quality issues:**

npm run lint

**If linting fails:**

npm run lint:fix

**Manually fix remaining issues** that auto-fix couldn't handle.

**Success criteria:**

• ✅ Linting passes with no errors
• ✅ Code follows project standards

**Mark complete when:** `npm run lint` passes with no errors

---

Step 2: Browser Validation (MANDATORY)

**CRITICAL: You must test in a real browser and provide proof.**

What to Test

Load test content URL(s) in browser and validate:

• ✅ Block/functionality renders correctly
• ✅ Responsive behavior (mobile, tablet, desktop viewports)
• ✅ No console errors
• ✅ Visual appearance matches requirements/acceptance criteria
• ✅ Interactive behavior works (if applicable)
• ✅ All variants render correctly (if applicable)

How to Test

**Choose the method that makes most sense given your available tools:**

**Option 1: Browser/Playwright MCP (Recommended)**

If you have MCP browser or Playwright tools available, use them directly:

• Navigate to test content URL
• Take accessibility snapshots to inspect rendered content (preferred for interaction)
• Take screenshots at different viewports for visual validation
• Consider both full-page screenshots and element-specific screenshots of the block being tested
• Interact with elements as needed
• Most efficient for agents with tool access

**Option 2: Playwright automation**

Write one (or more) temporary test scripts to validate functionality with playwright and capture snapshots/screenshots for inspection and validation.

// test-my-block.js (temporary - don't commit)
import { chromium } from 'playwright';

async function test() {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  // Navigate and wait for block
  await page.goto('http://localhost:3000/path/to/test');
  await page.waitForSelector('.my-block');

  // Inspect accessibility tree (useful for validating structure)
  const accessibilityTree = await page.accessibility.snapshot();
  console.log('Accessibility tree:', JSON.stringify(accessibilityTree, null, 2));
  
  // Optionally save to file for easier analysis
  await require('fs').promises.writeFile(
    'accessibility-tree.json',
    JSON.stringify(accessibilityTree, null, 2)
  );

  // Test viewports and take screenshots
  await page.setViewportSize({ width: 375, height: 667 });
  await page.screenshot({ path: 'mobile.png', fullPage: true });
  await page.locator('.my-block').screenshot({ path: 'mobile-block.png' });

  await page.setViewportSize({ width: 768, height: 1024 });
  await page.screenshot({ path: 'tablet.png', fullPage: true });
  await page.locator('.my-block').screenshot({ path: 'tablet-block.png' });

  await page.setViewportSize({ width: 1200, height: 800 });
  await page.screenshot({ path: 'desktop.png', fullPage: true });
  await page.locator('.my-block').screenshot({ path: 'desktop-block.png' });

  // Check for console errors
  page.on('console', msg => console.log('Browser:', msg.text()));

  await browser.close();
}

test().catch(console.error);

Run: `node test-my-block.js` then delete the script and analyze the resulting artifacts.

**Option 3: Manual browser testing**

Use a standard web browser with dev tools: 1. Navigate to test content: `http://localhost:3000/path/to/test/content` 2. Use browser dev tools responsive mode to test viewports:

• Mobile: <600px (e.g., 375px)
• Tablet: 600-900px (e.g., 768px)
• Desktop: >900px (e.g., 1200px)

3. Check console for errors at each viewport 4. Take screenshots as proof (browser screenshot tool or dev tools)

Validation Against Acceptance Criteria

**If acceptance criteria provided (from CDD Step 2):**

• Review each criterion
• Test specific scenarios mentioned
• Verify all criteria are met

**If design/mockup screenshots provided:**

• Compare implementation to design
• Verify visual alignment
• Note any intentional deviations

Proof of Testing

**You must provide:**

• ✅ Screenshots of test content in browser (at least one viewport)
• ✅ Confirmation no console errors
• ✅ Confirmation acceptance criteria met (if provided)

**Success criteria:** -