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:

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

If in a subdirectory, navigate to project root:

cd /Users/tomcranstoun/Documents/GitHub/allaboutV2

Verify project markers:

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

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:

// 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:

// 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:

Usage Pattern:

// 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:

<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 - Content structure patterns and complete examples
• ADVANCED_TECHNIQUES.md - Performance testing, batch testing, validation
• TROUBLESHOOTING.md - Solutions for popup issues, styling issues

Related Documentation

• docs/for-ai/explaining-jupyter.md - Comprehensive Jupyter notebook documentation
• blocks/ipynb-viewer/README.md - ipynb-viewer block documentation
• scripts/ipynb-helpers.js - Helper functions implementation
• 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:

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

Solution:

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