testcell

One good thing about working in Jupyter notebooks is that they make it easy to quickly test a bit of code by evaluating it in notebook cell. But one bad thing is that the definitions resulting from that evaluation hang around afterwards, when all you wanted was just to test that one bit of code.

%%testcell is a simple simple solution to that problem. It lets you execute notebook cells in isolation. Test code, try snippets, and experiment freely: no variables, functions, classes, or imports are left behind. This helps to keep your namespace clean, so that leftover symbols do not confuse later work.

WARNING: this doesn’t protect you from the side effects of your code like deleting a file or mutating the state of a global variable.

Install

Lightweight and reliable: %%testcell depends only on IPython and works in all major notebook environments including Jupyter, Colab, Kaggle, Modal, Solveit, and the IPython console.

pip install testcell

Quick Start

First import testcell:

importtestcell

Then use it:

%%testcelltemp_var="This won't pollute namespace"temp_var

"This won't pollute namespace"

# temp_var doesn't exist — it was only defined inside the test celltemp_var# NameError: name 'temp_var' is not defined

How it works

Import testcell and use the %%testcell magic at the top of any cell. Under the hood, your code is wrapped in a temporary function that executes and then deletes itself.

Use verbose to see the generated wrapper code:

%%testcellverboseresult="isolated execution"result

### BEGINdef_test_cell_():
#| echo: falseresult="isolated execution"returnresult# %%testcelltry:
_=_test_cell_()
finally:
del_test_cell__# This will be added to global scope### END

'isolated execution'

Suppressing output

Like normal Jupyter cells, add a semicolon ; to the last statement to suppress display:

%%testcellcalculation=42*2calculation;

No output is displayed, and calculation still doesn’t leak to globals.

Skip execution

Skip cells without deleting code using the skip command.

IMPORTANT: This is especially useful in notebook environments like Colab, Kaggle, and Modal where you can’t use Jupyter’s “Raw cell” type to disable execution.

%%testcellskipraiseValueError('This will not execute')

<testcell.MessageBox object>

To skip all %%testcell cells at once (useful for production runs), use: testcell.global_skip = True

Visual marking

Use banner to display a colored indicator at the top of cell output, making test cells instantly recognizable:

%%testcellbanner"clearly marked"

<testcell.MessageBox object>
'clearly marked'

The banner adapts to your environment. In HTML-based notebooks like Jupyter, it displays as a full-width colored box. In console environments like IPython, it appears as text with an emoji.

Colors and emojis are fully customizable through testcell.params.

IMPORTANT: To enable banners for all %%testcell cells, use: testcell.global_use_banner = True

Run in complete isolation

%%testcelln is a shortcut for %%testcell noglobals and executes cells with zero access to your notebook’s global scope. Only Python’s __builtins__ are available.

This is powerful for: - Detecting hidden dependencies: catch when your code accidentally relies on global variables - Testing portability: verify functions work standalone - Clean slate execution: run code exactly as it would in a fresh Python session

my_global="I'm in the global scope"

%%testcell'my_global'inglobals()

True# my_global is available

%%testcelln'my_global'inglobals()

False# my_global is NOT available

%%testcellnglobals().keys()

dict_keys(['__builtins__'])

Explicit dependencies

The (inputs)->(outputs) syntax gives you precise control: you can pass any symbol (variables, functions, classes) into the isolated context and save only chosen ones back to globals.

This forces explicit dependency declaration, giving you full control over what enters and exits the cell. It prevents accidental reliance on symbols from the main context that would hurt you when exporting the code.

data= [1, 2, 3, 4, 5]

%%testcelln (data)->(calculate_stats)
# Only 'data' is available, only 'calculate_stats' is saveddefcalculate_stats(values):
return {
'mean': sum(values) /len(values),
'min': min(values),
'max': max(values)
}
# Test it worksprint(calculate_stats(data))

{'mean': 3.0, 'min': 1, 'max': 5}

calculate_stats now exists in globals. No test code or intermediate variables leaked.

calculate_stats([10, 20, 30])

{'mean': 20.0, 'min': 10, 'max': 30}

Advanced parsing

Thanks to Python’s ast module, %%testcell correctly handles complex code patterns including comments on the last line and multi-line statements:

%%testcellverboseresult="complex parsing"
(result,
True)
# comment on last line

### BEGINdef_test_cell_():
#| echo: falseresult="complex parsing"return (result,
True) # %%testcelltry:
_=_test_cell_()
finally:
del_test_cell__# This will be added to global scope### END

('complex parsing', True)

Links:

• PROJECT PAGE: https://github.com/artste/testcell
• DOCUMENTATION: https://artste.github.io/testcell
• PYPI: https://pypi.org/project/testcell
• DETAILED DEMO: https://github.com/artste/testcell/blob/main/demo/testcell_demo.ipynb
• USE CASE ZOO: https://github.com/artste/testcell/blob/main/demo/testcell_zoo.ipynb
• LAUNCHING BLOG: Introducing %%testcell
• COLAB DEMO: testcell_demo.ipynb
• KAGGLE SAMPLE NOTEBOOK: https://www.kaggle.com/artste/introducing-testcell

Todo:

• Install as a plugin to enable it by default like other cell’s magic.