Guide for testing code changes in AEM Edge Delivery projects including blocks, scripts, and styles. Use this skill after making code changes and before opening a pull request to validate functionality. Covers unit testing for utilities and logic, browser testing with Playwright/Puppeteer, linting, performance validation, and guidance on which tests to maintain vs use as throwaway validation.
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.
Use this skill:
This skill should be automatically invoked by the building-blocks skill after implementation is complete.
The Principle: Create and maintain tests when the value they bring exceeds the cost of creation and maintenance.
✅ Write unit tests for:
These tests provide lasting value because they catch regressions in reused code, serve as living documentation, and are fast and easy to maintain.
⚠️ Use browser tests for:
These tests are better done in a browser because DOM structures change frequently, visual validation requires human judgment, and maintaining UI tests is expensive relative to their value.
Important: Even throwaway tests have value! Use them to:
Organization: Keep throwaway tests in test/tmp/ and test content in drafts/tmp/. Both directories should be gitignored so temporary test artifacts aren't committed.
Before opening a pull request, complete ALL of the following:
npm run lint completes without errorsgh checks to confirm all CI checks passWhen to use: Logic-heavy functions, utilities, data processing, API integrations
Quick start:
# Verify test setup (see resources/vitest-setup.md if not configured)
npm test
# Write test for utility function
# test/utils/my-utility.test.js
import { describe, it, expect } from 'vitest';
import { myUtility } from '../../scripts/utils/my-utility.js';
describe('myUtility', () => {
it('should transform input correctly', () => {
expect(myUtility('input')).toBe('OUTPUT');
});
});
# Run tests during development
npm run test:watch
Detailed guide: See resources/unit-testing.md
When to use: Block decoration, visual validation, DOM structure, responsive design
Organization:
test/tmp/test-{block}-browser.jsdrafts/tmp/{block}.htmltest/tmp/screenshots/test/tmp/ and drafts/tmp/ should be gitignoredQuick start:
# Install Playwright
npm install --save-dev playwright
npx playwright install chromium
# Create test content
# drafts/tmp/my-block.html (copy head.html content, add test markup)
# Start dev server with drafts folder
aem up --html-folder drafts
# Create throwaway test script in test/tmp/
# test/tmp/test-my-block.js
import { chromium } from 'playwright';
import { mkdir } from 'fs/promises';
async function test() {
await mkdir('./test/tmp/screenshots', { recursive: true });
const browser = await chromium.launch({ headless: false });
const page = await browser.newPage();
await page.goto('http://localhost:3000/drafts/tmp/my-block');
await page.waitForSelector('.my-block');
await page.screenshot({
path: './test/tmp/screenshots/my-block.png',
fullPage: true
});
await browser.close();
}
test().catch(console.error);
# Run the test
node test/tmp/test-my-block.js
# Clean up when done (optional - gitignored either way)
rm -rf test/tmp/*
Detailed guide: See resources/browser-testing.md
When to use: Before every commit
Quick start:
# Run linting
npm run lint
# Auto-fix issues
npm run lint:fix
Linting MUST pass before opening a PR. Non-negotiable.
When to use: After pushing branch, automatically via GitHub checks
Quick start:
# Push branch
git push -u origin your-branch
# Create PR with test link
# PR description MUST include:
# Preview: https://branch--repo--owner.aem.page/path/to/test
# Monitor checks
gh pr checks --watch
Performance tests run automatically when you include a test link in your PR description.
For detailed step-by-step workflow, see resources/testing-workflow.md.
Quick summary:
npm run test:watchnpm test - all tests passnpm run lint - linting passestest/tmp/drafts/tmp/test/tmp/screenshots/gh checksgh pr checksFor detailed troubleshooting guide, see resources/troubleshooting.md.
Common issues:
npm test -- path/to/test.jsnpm run lint:fixgh pr checks for detailsaem up --html-folder draftsdrafts/tmp//tmp/ path: http://localhost:3000/drafts/tmp/my-blockawait page.waitForSelector('.block')resources/unit-testing.md - Complete guide to writing and maintaining unit testsresources/browser-testing.md - Playwright/Puppeteer workflows and best practicesresources/testing-workflow.md - Step-by-step workflow from dev to PRresources/troubleshooting.md - Solutions to common testing issuesresources/vitest-setup.md - One-time configuration guideThe building-blocks skill automatically invokes this skill after implementation.
Expected flow:
Building blocks provides:
This skill returns:
Testing in AEM Edge Delivery follows a pragmatic value-versus-cost approach:
Create keeper tests for:
Use throwaway browser tests for:
Always do:
Remember: The goal is confidence that your code works correctly, not achieving 100% test coverage. Write tests that provide value, and validate everything else in a browser.
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer