feat: release pytest from experimental (#4467)

## 📝 Summary

Added docs and flipped the flag for pytest run

@akshayka OR @mscolnick

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Akshay Agrawal <akshay@marimo.io>

Author: 3 people

docs/guides/testing/pytest.md

@@ -1,4 +1,48 @@
-# Running unit tests with pytest
+# Testing with pytest
+
+## Testing in notebook
+
+Be default, marimo detects and runs tests in your notebooks automatically. If
+the optional `pytest` library is installed, marimo will run `pytest` on any cells that
+contain test functions (functions that start with `test_`) or test classes
+(classes that start with `Test`) on a per cell basis.
+
+For example,
+
+/// marimo-embed
+
+```python
+@app.cell
+def __():
+    import pytest
+    def inc(x):
+        return x + 1
+    return inc, pytest
+
+@app.cell
+def __(inc, pytest):
+    def test_fails():
+        assert inc(3) == 5, "This test fails"
+
+    def test_sanity():
+        assert inc(3) == 4, "This test passes"
+
+    class TestBlock:
+        @pytest.mark.parametrize(("x", "y"), [(3, 4), (4, 5)])
+        def test_parameterized(x, y):
+            assert inc(x) == y
+    return
+```
+
+///
+
+!!! note "Reactive tests can be disabled"
+
+    You can disable this behavior with the runtime.reactive_test option in the
+    configuration file.
+
+
+## Testing at the command-line
 
 Since marimo notebooks are Python programs, you can test them using
 [`pytest`](https://docs.pytest.org/en/stable/), a popular testing framework

frontend/src/components/app-config/optional-features.tsx

@@ -81,6 +81,12 @@ const OPTIONAL_DEPENDENCIES: OptionalFeature[] = [
     additionalPackageInstalls: [],
     description: "Export as IPYNB",
   },
+  {
+    id: "testing",
+    packagesRequired: [{ name: "pytest" }],
+    additionalPackageInstalls: [],
+    description: "Autorun unit tests",
+  },
 ];
 
 if (getFeatureFlag("lsp")) {

frontend/src/components/app-config/user-config-form.tsx

@@ -914,6 +914,37 @@ export const UserConfigForm: React.FC = () => {
                 </div>
               )}
             />
+            <FormField
+              control={form.control}
+              name="runtime.reactive_tests"
+              render={({ field }) => (
+                <div className="flex flex-col gap-y-1">
+                  <FormItem className={formItemClasses}>
+                    <FormLabel className="font-normal">
+                      Autorun Unit Tests
+                    </FormLabel>
+                    <FormControl>
+                      <Checkbox
+                        data-testid="reactive-test-checkbox"
+                        checked={field.value === true}
+                        onCheckedChange={field.onChange}
+                      />
+                    </FormControl>
+                  </FormItem>
+                  <IsOverridden
+                    userConfig={config}
+                    name="runtime.reactive_tests"
+                  />
+                  <FormMessage />
+                  <FormDescription>
+                    Enable reactive pytest tests in notebook. When a cell
+                    contains only test functions (test_*) and classes (Test_*),
+                    marimo will automatically run them with pytest (requires
+                    notebook restart).
+                  </FormDescription>{" "}
+                </div>
+              )}
+            />
 
             <FormDescription>
               Learn more in the{" "}
@@ -1324,31 +1355,6 @@ export const UserConfigForm: React.FC = () => {
                 </div>
               )}
             />
-            <FormField
-              control={form.control}
-              name="experimental.reactive_tests"
-              render={({ field }) => (
-                <div className="flex flex-col gap-y-1">
-                  <FormItem className={formItemClasses}>
-                    <FormLabel className="font-normal">
-                      Autorun Unit Tests
-                    </FormLabel>
-                    <FormControl>
-                      <Checkbox
-                        data-testid="reactive-test-checkbox"
-                        checked={field.value === true}
-                        onCheckedChange={field.onChange}
-                      />
-                    </FormControl>
-                  </FormItem>
-                  <FormDescription>
-                    Enable experimental reactive pytest tests in notebook. When
-                    a cell contains only test functions and classes, marimo will
-                    automatically run relevant tests.
-                  </FormDescription>{" "}
-                </div>
-              )}
-            />
             <FormField
               control={form.control}
               name="experimental.toplevel_defs"

frontend/src/components/editor/__tests__/data-attributes.test.tsx

@@ -54,6 +54,7 @@ describe("Cell data attributes", () => {
           auto_reload: "off",
           on_cell_change: "lazy",
           watcher_on_save: "lazy",
+          reactive_tests: true,
           output_max_bytes: 1_000_000,
           std_stream_max_bytes: 1_000_000,
           pythonpath: [],
@@ -65,7 +66,7 @@ describe("Cell data attributes", () => {
         },
         save: { autosave: "off", autosave_delay: 1000, format_on_save: false },
         ai: {},
-      };
+      } as UserConfig;
 
       const { container } = render(
         <TooltipProvider>

marimo/_ast/app_config.py

@@ -1,3 +1,4 @@
+# Copyright 2025 Marimo. All rights reserved.
 from dataclasses import asdict, dataclass, field
 from typing import Any, Literal, Optional
 

marimo/_config/config.py

@@ -107,6 +107,8 @@ class RuntimeConfig(TypedDict):
     - `auto_reload`: if `lazy`, cells importing modified modules will marked
       as stale; if `autorun`, affected cells will be automatically run. similar
       to IPython's %autoreload extension but with more code intelligence.
+    - `reactive_tests`: if `True`, marimo will automatically run pytest on cells containing only test functions and test classes.
+      execution.
     - `on_cell_change`: if `lazy`, cells will be marked stale when their
       ancestors run but won't autorun; if `autorun`, cells will automatically
       run when their ancestors run.
@@ -130,6 +132,7 @@ class RuntimeConfig(TypedDict):
 
     auto_instantiate: bool
     auto_reload: Literal["off", "lazy", "autorun"]
+    reactive_tests: bool
     on_cell_change: OnCellChangeType
     watcher_on_save: Literal["lazy", "autorun"]
     output_max_bytes: int
@@ -401,6 +404,7 @@ class PartialMarimoConfig(TypedDict, total=False):
     "runtime": {
         "auto_instantiate": True,
         "auto_reload": "off",
+        "reactive_tests": True,
         "on_cell_change": "autorun",
         "watcher_on_save": "lazy",
         "output_max_bytes": int(

marimo/_runtime/runtime.py

@@ -515,7 +515,7 @@ def __init__(
         self._original_environ = os.environ.copy()
 
         # Adds in a post_execution hook to run pytest immediately
-        if user_config.get("experimental", {}).get("reactive_tests", False):
+        if user_config["runtime"].get("reactive_tests", False):
             from marimo._runtime.runner.hooks_post_execution import (
                 _attempt_pytest,
             )

marimo/_server/print.py

@@ -117,6 +117,7 @@ def print_experimental_features(config: MarimoConfig) -> None:
         "tracing",
         "markdown",
         "sql_engines",
+        "reactive_tests",
     }
     keys = keys - finished_experiments
 

openapi/api.yaml

@@ -1527,6 +1527,8 @@ components:
               items:
                 type: string
               type: array
+            reactive_tests:
+              type: boolean
             std_stream_max_bytes:
               type: integer
             watcher_on_save:
@@ -1537,6 +1539,7 @@ components:
           required:
           - auto_instantiate
           - auto_reload
+          - reactive_tests
           - on_cell_change
           - watcher_on_save
           - output_max_bytes
@@ -2500,7 +2503,7 @@ components:
       type: object
 info:
   title: marimo API
-  version: 0.12.6
+  version: 0.12.7
 openapi: 3.1.0
 paths:
   /@file/{filename_and_length}:

openapi/src/api.ts

@@ -2968,6 +2968,7 @@ export interface components {
         on_cell_change: "lazy" | "autorun";
         output_max_bytes: number;
         pythonpath?: string[];
+        reactive_tests: boolean;
         std_stream_max_bytes: number;
         /** @enum {string} */
         watcher_on_save: "lazy" | "autorun";