testing-blocks
/testing-blocks
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.
Assessment and security
- Files in this package
- 8
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 3
No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
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.
Original author 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.
How it works
- Related Skills
- When to Use This Skill
- Testing Workflow
- Step 1: Run Linting
- Step 2: Browser Validation (MANDATORY)
- Step 3: Unit Tests (Optional)
- Step 4: Run Existing Tests
- Troubleshooting
- Resources
- Integration with Building Blocks Skill
SKILL.md preview
---
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:**
```bash
npm run lint
```
**If linting fails:**
```bash
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.
```javascript
// 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
---
## Step 3: Unit Tests (Optional)
**Determine if unit tests are needed for this change.**
**Write unit tests when:**
- ✅ Logic-heavy functions (calculations, transformations)
- ✅ Utility functions used across multiple blocks
- ✅ Data processing or API integrations
- ✅ Complex business logic
**Skip unit tests when:**
- ❌ Simple DOM manipulation
- ❌ CSS-only changes
- ❌ Straightforward decoration logic
- ❌ Changes easily validated in browser
**For guidance on what to test:** See [references/testing-philosophy.md](references/testing-philosophy.md)
**If unit tests needed:**
```bash
# Verify test setup (see references/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');
});
});
```
**For detailed unit testing guidance:** See [references/unit-testing.md](references/unit-testing.md)
**Success criteria:**
- ✅ Unit tests written for logic-heavy code
- ✅ Tests pass: `npm test`
- ✅ OR determined unit tests not needed
**Mark complete when:** Unit tests written and passing, or determined not needed
---
## Step 4: Run Existing Tests
**Verify your changes don't break existing functionality:**
```bash
npm test
```
**If tests fail:**
1. Read error message carefully
2. Run single test to isolate: `npm test -- path/to/test.js`
3. Fix code or update test if expectations changed
4. Re-run full test suite
**Success criteria:**
- ✅ All existing tests pass
- ✅ No regressions introduced
**Mark complete when:** `npm test` passes with no failures
## Troubleshooting
For detailed troubleshooting guide, see [references/troubleshooting.md](references/troubleshooting.md).
**Common issues:**
### Tests fail
- Read error message carefully
- Run single test: `npm test -- path/to/test.js`
- Fix code or update test
### Linting fails
- Run `npm run lint:fix`
- Manually fix remaining issues
### Browser tests fail
- Verify dev server running: `aem up --html-folder drafts`
- Check test content exists in `drafts/tmp/`
- Verify URL uses `/tmp/` path: `http://localhost:3000/drafts/tmp/my-block`
- Add waits: `await page.waitForSelector('.block')`
## Resources
- **Unit Testing:** [references/unit-testing.md](references/unit-testing.md) - Complete guide to writing and maintaining unit tests
- **Troubleshooting:** [references/troubleshooting.md](references/troubleshooting.md) - Solutions to common testing issues
- **Vitest Setup:** [references/vitest-setup.md](references/vitest-setup.md) - One-time configuration guide
- **Testing Philosophy:** [references/testing-philosophy.md](references/testing-philosophy.md) - Guide on what and how to test
## Integration with Building Blocks Skill
The **building-blocks** skill invokes this skill during Step 5 (Test Implementation).
**Inputs received from building-blocks:**
- Block name being tested
- Test content URL(s) (from CDD Step 4)
- Any variants that need testing
- Screenshots of existing implementation/design/mockup to verify against (if provided)
- Acceptance criteria to verify (from CDD Step 2)
**Expected outputs to return to building-blocks:**
- ✅ Confirmation all testing steps complete
- ✅ Screenshots from browser testing as proof
- ✅ Confirmation linting passes
- ✅ Confirmation tests pass
- ✅ Any issues discovered and resolved
Files in this package (8)
- .releaserc.json 1 KB
- CHANGELOG.md 1 KB
- SKILL.md 10 KB
- package.json 1 KB
- references/testing-philosophy.md 2 KB
- references/troubleshooting.md 9 KB
- references/unit-testing.md 8 KB
- references/vitest-setup.md 4 KB
Versions
The database has no other skills named testing-blocks.
Database snapshot: 13.11.2026 · package version ceec40b0e1ba (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90Code Review
Review code for AEM Edge Delivery Services projects. Use for self-review before committing, or to review pull requests with one-click GitHub suggestions. - 100playwright-testing
UI/E2E test automation with Playwright MCP. Use when the user asks to "test the UI", "automate browser tests", "check the page", "take a screenshot", "run Playwright", "write E2E tests", or anything about browser-based testing. - 100content-modeling
Use this when you are building new AEM Edge Delivery Services blocks or changing the initial structure that authors work with in an existing block. Covers designing content models that are easy for authors to use. - 100building-blocks
Use this when implementing code changes in AEM Edge Delivery Services (EDS, Franklin, Helix), whether new or modified blocks, core functionality (scripts.js, styles, delayed.js, etc.), or both. Creates and modifies block folders and decorate functions, updates core scripts,… - 96smoke-testing
Use when you need confidence the demo path works — a few fast tests for the critical flow (unit tests for logic, a browser smoke test with Playwright, API checks with curl). - 95memstack-development-webapp-testing
Use when the user says 'write browser tests', 'test this page', 'playwright test', 'e2e test', 'end to end test', 'browser test', 'test the UI', or needs Playwright-based browser testing for a web application. Do NOT use for unit tests, API tests, or non-browser testing.