diff --git a/docs/examples/test_embed/embed1.py b/docs/examples/test_embed/embed1.py
new file mode 100644
index 0000000..cdf55e4
--- /dev/null
+++ b/docs/examples/test_embed/embed1.py
@@ -0,0 +1,10 @@
+"""This tests standard embedding, automatically detecting the module and
+local namespaces."""
+
+f = set([1,2,3,4,5])
+
+def bar(foo):
+    import IPython
+    IPython.embed(banner1='check f in globals, foo in locals')
+
+bar(f)
diff --git a/docs/examples/test_embed/embed2.py b/docs/examples/test_embed/embed2.py
new file mode 100644
index 0000000..a60e3e9
--- /dev/null
+++ b/docs/examples/test_embed/embed2.py
@@ -0,0 +1,5 @@
+"""This tests passing a dict for the user_ns at shell instantiation."""
+from IPython import embed
+
+user_ns = dict(cookie='monster')
+embed(user_ns=user_ns, banner1="check 'cookie' present, locals and globals equivalent")
diff --git a/docs/examples/test_embed/embed3.py b/docs/examples/test_embed/embed3.py
new file mode 100644
index 0000000..aed8f4d
--- /dev/null
+++ b/docs/examples/test_embed/embed3.py
@@ -0,0 +1,7 @@
+"""This tests passing local_ns and global_ns (for backwards compatibility only)
+at activation of an embedded shell."""
+from IPython.frontend.terminal.embed import InteractiveShellEmbed
+
+user_ns = dict(cookie='monster')
+ISE = InteractiveShellEmbed(banner1='check cookie in locals, and globals empty')
+ISE(local_ns=user_ns, global_ns={})