---
name: eds-block-testing
description: Guide for testing EDS blocks using test.html files and the development server. Covers test file structure, EDS core integration, testing patterns, and debugging workflows for Adobe Edge Delivery Services blocks.
---
# EDS Block Testing Guide
## Purpose
Guide developers through testing Adobe Edge Delivery Services (EDS) blocks using test.html files, the development server, and proper EDS integration patterns.
## When to Use This Skill
Automatically activates when:
- Creating or editing `test.html` files in block directories
- Working with keywords: "test block", "test.html", "debug block"
- Implementing block testing patterns
- Using the development server
---
## Quick Start: Create a Test File
Every block should have a `test.html` file in its directory:
```
blocks/your-block/
├── your-block.js
├── your-block.css
├── README.md
├── EXAMPLE.md
└── test.html ← Create this file
```
---
## Standard Test File Template
```html
Your Block Test - EDS Native Pattern
Your Block Test Page
Test Case 1: Basic Usage
Title 1
Description 1
Title 2
Description 2
Test Case 2: With Images
Content with image
```
**Important Notes:**
- The `document.body.classList.add('appear')` line is **required** and must be called **before** `loadBlock()`. EDS hides the body by default (`body { display: none; }` in `styles/styles.css`) to prevent Flash of Unstyled Content (FOUC). Adding the `appear` class makes the page visible. In production, EDS adds this automatically, but test files must add it manually.
- **The `.block` class is automatically added by the script** (line `block.classList.add('block')`) to mimic EDS production behavior. In your HTML, only use the block name class (e.g., `class="your-block"`).
- This approach ensures test files behave identically to production where EDS's `decorateBlock()` adds the `.block` class automatically.
---
## Development Server Workflow
### Start the Server
```bash
npm run debug
```
The server starts on `http://localhost:3000` with:
- Automatic proxy fallback to production site
- CORS headers for cross-origin requests
- Enhanced logging for debugging
- Hot-reload support
### Access Your Test
```
http://localhost:3000/blocks/your-block/test.html
```
### Development Flow
1. Edit your block JavaScript or CSS
2. Refresh the test page in your browser
3. Check the browser console for errors
4. Iterate and test
---
## EDS Block Structure in Test Files
### Basic Two-Column Structure
```html
Column 1 Content
Column 2 Content
Column 1 Content
Column 2 Content
```
**Important:**
- This structure matches how EDS creates blocks from Google Docs tables
- The `.block` class is **automatically added** by EDS's `decorateBlock()` function in production
- For test files, you can either:
- Add `.block` manually: `
`
- Let your test script add it automatically (recommended - mimics production behavior)
### With Images
```html
```
**Note:** Examples show blocks without the `.block` class. Your test script should add it automatically to mimic EDS production behavior.
---
## Loading Blocks Programmatically
### Basic Block Loading
```html
```
### Loading Multiple Blocks
```html
```
### With Error Handling
```html
```
---
## Testing Different Scenarios
### Test Empty Content
```html
Test Case: Empty Content
```
### Test Invalid Content
```html
Test Case: Invalid Structure
Only One Column
```
### Test Edge Cases
```html
Test Case: Very Long Content
Short title
Lorem ipsum dolor sit amet, consectetur adipiscing elit... (very long text)
```
### Test Responsive Behavior
```html
Test Case: Mobile View (375px)
Test Case: Tablet View (768px)
```
---
## Debugging Tips
### Console Logging
```html
```
### Timing Performance
```html
```
### Check Network Requests
Open Chrome DevTools → Network tab to see:
- Which CSS files are loaded
- Which JavaScript modules are loaded
- Any failed requests (404, 500, etc.)
### Common Issues and Solutions
#### Issue: Page is Blank or Invisible
**Symptoms:**
- Page loads but nothing displays
- Browser shows white/blank screen
- Console shows no JavaScript errors
- Elements exist in DOM but aren't visible
**Root Cause:** CSS class name conflicts with EDS reserved names
**Solution:** Never use these class patterns in your CSS or JavaScript:
- `.{blockname}-container` - EDS adds to parent `` elements
- `.{blockname}-wrapper` - EDS adds to block parent `
` wrappers
- `.block` - EDS adds to all block elements (avoid styling globally)
- `.section` - EDS adds to all sections (avoid styling globally)
- `.button-container` - EDS adds to button parent elements
- `.default-content-wrapper` - EDS adds to default content wrappers
**Example of the bug:**
```css
/* ❌ BAD - Will be applied to parent section, not your modal */
.overlay-container {
position: fixed;
z-index: 999;
opacity: 0; /* Makes entire page invisible! */
}
/* ✅ GOOD - Use different suffix */
.overlay-backdrop {
position: fixed;
z-index: 999;
opacity: 0; /* Only affects your backdrop element */
}
```
**Why this happens:**
1. EDS's `decorateBlock()` adds `.{blockname}-container` to parent sections (aem.js:684)
2. Your CSS targets `.{blockname}-container` for your component
3. Browser applies your styles to the section instead of your element
4. Section gets `position: fixed; opacity: 0` making page invisible
**Other global classes that can cause issues:**
```css
/* ❌ DANGER - These affect ALL blocks/sections if styled incorrectly */
.block { position: fixed; } /* Breaks ALL blocks */
.section { display: none; } /* Hides ALL sections */
.button-container { overflow: hidden; } /* Breaks ALL buttons */
```
**How to debug:**
1. Open browser console
2. Run: `document.querySelector('section').className`
3. If you see `{blockname}-container` in the class list, rename your CSS classes
4. Check if styling global classes like `.block` or `.section` with layout properties
#### Issue: Block CSS Not Loading
**Solution:** Ensure your CSS file has the exact same name as your JS file:
```
blocks/your-block/
├── your-block.js ✅ Matches
├── your-block.css ✅ Matches
└── test.html
```
#### Issue: Block Not Rendering
**Check:**
1. Console for JavaScript errors
2. Block structure matches expected pattern
3. `decorate` function is exported as default
4. Block class name is correct
#### Issue: Images Not Loading
**Solution:** Use absolute paths from project root:
```html
```
---
## Interactive Testing Tools
### Add Test Controls
```html
```
### Data Attribute Testing
```html
```
---
## Accessibility Testing
### Test Keyboard Navigation
```html
Accessibility Test
Use Tab to navigate, Enter/Space to activate
```
### Test Screen Reader Compatibility
**Use Chrome DevTools:**
1. Open DevTools → Elements
2. Right-click element → Inspect Accessibility Properties
3. Check ARIA labels, roles, and descriptions
---
## Performance Testing
### Measure Rendering Time
```html
```
### Check for Memory Leaks
```html
```
---
## Related Documentation
- **[EDS Block Development](../eds-block-development/SKILL.md)** - Block development patterns
- **[EDS Native Testing Standards](../../../docs/for-ai/testing/eds-native-testing-standards.md)** - Comprehensive testing guide
- **[Debug Guide](../../../docs/for-ai/testing/debug.md)** - Debugging workflows
- **[Development Server](../../../docs/Server-README.md)** - Server configuration
---
## Testing Checklist
Before considering your block complete, test:
- [ ] Basic functionality with standard content
- [ ] Empty/missing content handling
- [ ] Very long content (text overflow)
- [ ] Images load correctly
- [ ] Links work and have correct targets
- [ ] Responsive behavior (mobile, tablet, desktop)
- [ ] Keyboard navigation
- [ ] Screen reader compatibility
- [ ] Performance (load time < 100ms for simple blocks)
- [ ] Browser console shows no errors
- [ ] Works with multiple instances on same page
---
## Next Steps
1. Create test.html for your block
2. Start the development server: `npm run debug`
3. Access your test file in the browser
4. Test all scenarios and edge cases
5. Fix any issues found during testing
6. Document test results in your README.md
**Remember:** Proper testing ensures your block works correctly in all scenarios and provides a great user experience on the production site!
```
---
## Interactive Testing Tools
### Add Test Controls
```html