# Jupyter Notebook Testing

> Create and manage Jupyter notebooks for testing Adobe Edge Delivery Services (EDS) blocks interactively in the browser using the ipynb-viewer block. Interactive JavaScript execution, overlay previews with backdrop, direct ES6 imports. Use when creating notebooks, testing blocks with ipynb files in browser, generating overlay previews, or creating executable documentation.

- Skill: `majiayu000/jupyter-notebook-testing-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/jupyter-notebook-testing-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/jupyter-notebook-testing-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/majiayu000/jupyter-notebook-testing-2

---


# Jupyter Notebook Testing for EDS Blocks

Interactive testing environment for EDS blocks using Jupyter notebooks **in the browser** via the ipynb-viewer block.

## When to Use This Skill

Use this skill when:
- Creating new Jupyter notebooks (`.ipynb` files) for EDS block testing
- Using direct imports for helper functions (`testBlock`, `showPreview`)
- Testing blocks in browser environment with ipynb-viewer block
- Generating overlay previews with `showPreview()`
- Debugging blocks with different content structures
- Creating executable documentation for blocks
- Working with minimal DOM structure requirements
- Troubleshooting preview styling or decoration issues

## Overview

Test EDS blocks rapidly with Jupyter notebooks using **browser execution**:

- **Browser execution only**: Notebooks run via ipynb-viewer block on your EDS site
- **Direct imports**: Each cell imports what it needs independently
- **Helper functions**: `testBlock` and `showPreview` via ES6 imports
- **Overlay previews**: Full-screen overlays with backdrop (no popup blockers)
- **Minimal DOM**: Critical EDS-compatible structure (block decoration)

### Key Benefits

- **Browser-native**: Uses native browser APIs directly
- **No build steps**: Test blocks immediately without compilation
- **Visual previews**: Overlay with full styling (no popup blockers)
- **No initialization**: Each cell imports what it needs
- **EDS-compatible**: Follows EDS block decoration patterns
- **Executable docs**: Share interactive notebooks with end users

### Technology Stack

- **ipynb-viewer**: EDS block for executing notebooks in browser
- **Browser native APIs**: Direct DOM manipulation
- **scripts/ipynb-helpers.js**: External helper module with browser functions

## Quick Start

### 0. Verify Working Directory

**⚠️ CRITICAL: Before creating or modifying notebook files:**

Verify you're in the project root:

```bash
pwd
# Should output: /Users/tomcranstoun/Documents/GitHub/allaboutV2
```

If in a subdirectory, navigate to project root:
```bash
cd /Users/tomcranstoun/Documents/GitHub/allaboutV2
```

Verify project markers:
```bash
ls -la | grep -E "(\.claude|blocks|package\.json|CLAUDE\.md)"
```

All four must exist. If not, you're in the wrong directory!

### 1. Create or Open Notebook

**Option A: Copy existing template**
```bash
cp test.ipynb my-block-tests.ipynb
# View on EDS site using ipynb-viewer block
```

**Option B: Create from scratch**
- Create new `.ipynb` file
- Copy the first code cell from `test.ipynb`
- Add to EDS page via ipynb-viewer block

### 2. View Notebook on EDS Site

Add ipynb-viewer block to your page:

```
| IPynb Viewer |
|--------------|
| /test.ipynb |
```

### 3. Test Your Block

**Simple pattern - import what you need:**

```javascript
// Any cell: Test a block
const { testBlock } = await import('/scripts/ipynb-helpers.js');
const block = await testBlock('accordion', `
  <div>
    <div>Question 1</div>
    <div>Answer 1</div>
  </div>
`);
console.log('✓ Block created');
return block.outerHTML;
```

**Note:** Just write your code naturally with `await` and `return` - it runs in async context.

### 4. Generate Visual Preview

**Opens overlay:**

```javascript
// Any cell: Visual preview in overlay
const { showPreview } = await import('/scripts/ipynb-helpers.js');
const content = `
  <div>
    <div>Question 1</div>
    <div>Answer 1</div>
  </div>
`;

// Opens overlay with backdrop
await showPreview('accordion', content);

return '✓ Preview overlay opened';
```

## Browser Execution

### Purpose

End-user interaction and presentations with executable notebooks.

### Features

- Native browser APIs
- Direct JavaScript execution
- Console output display
- Overlay previews (no popup blockers)
- Interactive block decoration
- No file system access

### When to Use

- Sharing executable demos
- Interactive tutorials
- Client presentations
- Live coding examples
- Block testing and experimentation

## Helper Functions

All helper functions are in **scripts/ipynb-helpers.js**, imported in each cell as needed.

### Available Helper Functions

Import what you need in each cell:

| Function | Purpose | Behavior |
|----------|---------|----------|
| `testBlock()` | Test block decoration | Uses native browser DOM |
| `showPreview()` | Visual preview | Opens overlay with backdrop |

**Usage Pattern:**

```javascript
// Import what you need in each cell
const { testBlock, showPreview } = await import('/scripts/ipynb-helpers.js');

// Use the functions
const block = await testBlock('accordion', '<div>content</div>');
await showPreview('accordion', '<div>content</div>');

// Use document directly
const div = document.createElement('div');

return block.outerHTML; // Return value to display in output
```

## Overlay Preview System

Live previews use full-screen overlays - no popup blockers!

### How It Works

1. **Creates overlay**: Full-screen overlay with semi-transparent backdrop
2. **Responsive preview buttons**: Switch between Mobile (375×667), Tablet (768×1024), and Desktop (95%×95vh) views
3. **Minimal DOM** (EDS-compatible): Block decorated properly with CSS/JS
4. **Auto-decoration**: Dynamically imports and executes block JavaScript

### Key Benefits

✅ No popup blockers | ✅ Responsive testing | ✅ Better UX (stays on page) | ✅ Clean DOM | ✅ EDS-compatible | ✅ Full styling

### Responsive Preview Controls

Test blocks across different device sizes with one click:

- **📱 Mobile** (375px × 667px) - iPhone SE/8 size
- **📱 Tablet** (768px × 1024px) - iPad size
- **🖥️ Desktop** (95% × 95vh) - Full desktop view (default)

Switch between views interactively with smooth transitions to test block responsiveness!

## DOM Structure Requirements

### Minimal Structure

Block is decorated properly within overlay content area:

```html
<div class="ipynb-preview-content">
  <div class="blockname block"><!-- content rows --></div>
</div>
```

### Why This Matters

EDS blocks iterate over `block.children` directly. The overlay system ensures proper structure for decoration.

**Benefits:** No wrapper interference | Proper block decoration | Full CSS/JS support

## Troubleshooting

### Preview Shows Unstyled Content

**Cause:** CSS not loading or block decoration failed. **Check DevTools Console + Network tab** for 404s and errors. **Fix:** Verify block CSS exists.

### Overlay Not Appearing

**Symptom:** `showPreview()` runs but no overlay appears. **Cause:** JavaScript error during execution. **Fix:** Check browser console for errors.

### Import Errors

**Symptom:** Cells fail with import errors. **Cause:** Incorrect import path. **Fix:** Use absolute path `/scripts/ipynb-helpers.js`

## When to Use Notebooks

**✅ Use For:** Quick validation, content experimentation, debugging, prototyping, executable documentation, `showPreview()` testing, interactive demos

**❌ Don't Use For:** Complex interactions requiring Node.js, file system operations, automated testing, CI/CD pipelines

## Best Practices

1. **Import what you need**: Each cell imports helper functions independently
2. **Write async code naturally**: Use `await` directly - cells run in async context
3. **Return values**: Use `return` to display results in output cell
4. **Use direct imports**: `const { testBlock, showPreview } = await import(...)`
5. **Test visual output**: Always use `showPreview()` for verification
6. **No initialization required**: Run any cell at any time
7. **Structure notebooks**: Clear, focused cells with markdown documentation

## Integration with ipynb-viewer Block

The **ipynb-viewer** EDS block executes notebooks in browser:

```
| IPynb Viewer |
|--------------|
| /path/to/notebook.ipynb |
```

**Features:** Interactive execution (async/await support), console capture, markdown rendering (tables, code blocks, lists), error handling

**Key Points:** No initialization required | Each cell imports independently | Browser uses native APIs | Helper functions via ES6 imports

## Reference Files

For detailed information, see:

- **[EXAMPLES.md](EXAMPLES.md)** - Content structure patterns and complete examples
- **[ADVANCED_TECHNIQUES.md](ADVANCED_TECHNIQUES.md)** - Performance testing, batch testing, validation
- **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Solutions for popup issues, styling issues

## Related Documentation

- **[docs/for-ai/explaining-jupyter.md](../../docs/for-ai/explaining-jupyter.md)** - Comprehensive Jupyter notebook documentation
- **[blocks/ipynb-viewer/README.md](../../blocks/ipynb-viewer/README.md)** - ipynb-viewer block documentation
- **[scripts/ipynb-helpers.js](../../scripts/ipynb-helpers.js)** - Helper functions implementation
- **[test.ipynb](../../test.ipynb)** - Reference notebook with examples

## Summary

Jupyter notebooks with browser execution provide an interactive testing environment for EDS blocks that:

- **Browser-native execution**: Direct browser APIs, no Node.js complexity
- **No initialization required**: Each cell imports what it needs
- **Helper functions**: `testBlock`, `showPreview` via direct imports
- **Overlay previews**: Visual feedback (no popup blockers)
- **Minimal DOM structure**: EDS-compatible block decoration
- **ipynb-viewer integration**: End-user executable notebooks
- **Instant feedback**: No server or build overhead
- **Shareable**: Create interactive demos and documentation

Use this skill whenever you need to rapidly test, debug, or document EDS blocks in the browser without the ceremony of traditional development environments.

---

**Skill Status**: ✅ Complete - Browser-only execution
**Line Count**: < 500 lines
**Progressive Disclosure**: Detailed content in reference files

## Best Practices

### Proper Newline Formatting in Notebook Cells

**CRITICAL**: Every line in a Jupyter notebook cell's source array must end with `\n` (newline character) except the last line. This ensures proper rendering and navigation in VSCode outline.

**Why it matters for testing notebooks:**
- VSCode outline shows test structure for easy navigation
- Test scenarios organized by headings need proper outline hierarchy
- Developers navigate between tests via outline sidebar
- Without newlines, test sections don't appear in outline structure

**Problem:**
```python
# ❌ WRONG - Breaks outline navigation
"source": [
  "### Test: Accordion Expand/Collapse**Setup**Code---### Test: Error Handling..."
]
```

**Solution:**
```python
# ✅ CORRECT - Clear test structure in outline
"source": [
  "### Test: Accordion Expand/Collapse\n",
  "\n",
  "**Setup**\n",
  "\n",
  "Code\n",
  "\n",
  "---\n",
  "\n",
  "### Test: Error Handling\n"
]
```

**For testing notebooks:**
- Use `##` for block categories (Accordion Tests, Hero Tests)
- Use `###` for individual test cases
- Proper newlines enable quick navigation between test scenarios
- Developers can jump to specific tests via outline
- Essential for notebooks with many test cases

**Key rules:**
1. Every line ends with `\n` except the last line
2. Test headings need newlines before and after
3. Horizontal rules (test separators): `"---\n"` + `"\n"`
4. Blank lines between test sections

**See:** `LEARNINGS.md` for complete details and examples.