# 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. Use when this capability is needed.

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

---


# 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.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/ddttom) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-15 -->