Testing Blocks

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:

• ✅ All test content loads and renders correctly
• ✅ Responsive behavior validated across viewports
• ✅ No console errors
• ✅ Screenshots captured as proof
• ✅ Acceptance criteria validated (if provided)

Mark complete when: Browser testing complete with screenshots as proof