feat: Introduce testing.constructors module and a pytest plugin

.github/workflows/extremes.yml

@@ -6,6 +6,7 @@ on:
 env:
   PY_COLORS: 1
   PYTEST_ADDOPTS: "--numprocesses=logical"
+  COVERAGE_PROCESS_START: pyproject.toml
   UV_SYSTEM_PYTHON: 1
 jobs:
   minimum_versions:
@@ -44,7 +45,10 @@ jobs:
           echo "$DEPS" | grep 'scikit-learn==1.1.0'
           echo "$DEPS" | grep 'duckdb==1.1'
       - name: Run pytest
-        run: pytest tests --cov=narwhals --cov=tests --cov-fail-under=50 --runslow --constructors=pandas,pyarrow,polars[eager],polars[lazy],duckdb
+        run: |
+          coverage run -m pytest tests --runslow --constructors=pandas,pyarrow,polars[eager],polars[lazy],duckdb
+          coverage combine
+          coverage report --fail-under=50
 
   pretty_old_versions:
     strategy:
@@ -82,7 +86,10 @@ jobs:
           echo "$DEPS" | grep 'scikit-learn==1.1.0'
           echo "$DEPS" | grep 'duckdb==1.2'
       - name: Run pytest
-        run: pytest tests --cov=narwhals --cov=tests --cov-fail-under=50 --runslow --constructors=pandas,pyarrow,polars[eager],polars[lazy],duckdb
+        run: |
+          coverage run -m pytest tests --runslow --constructors=pandas,pyarrow,polars[eager],polars[lazy],duckdb
+          coverage combine
+          coverage report --fail-under=50
 
   not_so_old_versions:
     strategy:
@@ -119,7 +126,10 @@ jobs:
           echo "$DEPS" | grep 'dask==2024.10'
           echo "$DEPS" | grep 'duckdb==1.3'
       - name: Run pytest
-        run: pytest tests --cov=narwhals --cov=tests --cov-fail-under=50 --runslow --constructors=pandas,pyarrow,polars[eager],polars[lazy],dask,duckdb
+        run: |
+          coverage run -m pytest tests --runslow --constructors=pandas,pyarrow,polars[eager],polars[lazy],dask,duckdb
+          coverage combine
+          coverage report --fail-under=50 
 
   nightlies:
     strategy:
@@ -175,5 +185,6 @@ jobs:
           echo "$DEPS" | grep 'dask.*@'
       - name: Run pytest
         run: |
-          pytest tests --cov=narwhals --cov=tests --cov-fail-under=50 --runslow \
-          --constructors=pandas,pandas[nullable],pandas[pyarrow],pyarrow,polars[eager],polars[lazy],dask,duckdb
+          coverage run -m pytest tests --runslow --constructors=pandas,pandas[nullable],pandas[pyarrow],pyarrow,polars[eager],polars[lazy],dask,duckdb
+          coverage combine
+          coverage report --fail-under=50

.github/workflows/pytest-ibis.yml

@@ -6,6 +6,7 @@ on:
 env:
   PY_COLORS: 1
   PYTEST_ADDOPTS: "--numprocesses=logical"
+  COVERAGE_PROCESS_START: pyproject.toml
   UV_SYSTEM_PYTHON: 1
 jobs:
 

.github/workflows/pytest-modin.yml

@@ -6,6 +6,7 @@ on:
 env:
   PY_COLORS: 1
   PYTEST_ADDOPTS: "--numprocesses=logical"
+  COVERAGE_PROCESS_START: pyproject.toml
   UV_SYSTEM_PYTHON: 1
 jobs:
 

.github/workflows/pytest-pyspark.yml

@@ -14,6 +14,7 @@ on:
 env:
   PY_COLORS: 1
   PYTEST_ADDOPTS: "--numprocesses=logical"
+  COVERAGE_PROCESS_START: pyproject.toml
   UV_SYSTEM_PYTHON: 1
 jobs:
   pytest-pyspark-constructor:
@@ -40,7 +41,10 @@ jobs:
       - name: show-deps
         run: uv pip freeze
       - name: Run pytest
-        run: pytest tests --cov=narwhals/_spark_like --cov-fail-under=95 --runslow --constructors pyspark
+        run: |
+          coverage run -m pytest tests --runslow --constructors pyspark
+          coverage combine
+          coverage report --fail-under=95 --include "narwhals/_spark_like/*"
 
 
   pytest-pyspark-min-version-constructor:
@@ -133,7 +137,10 @@ jobs:
           echo "Spark Connect server started"
 
       - name: Run pytest
-        run: pytest tests --cov=narwhals/_spark_like --cov-fail-under=95 --runslow --constructors "pyspark[connect]"
+        run: |
+          coverage run -m pytest tests --runslow --constructors "pyspark[connect]"
+          coverage combine
+          coverage report --fail-under=95 --include="narwhals/_spark_like/*"
 
       - name: Stop Spark Connect server
         if: always()

.github/workflows/pytest.yml

@@ -6,6 +6,7 @@ on:
 env:
   PY_COLORS: 1
   PYTEST_ADDOPTS: "--numprocesses=logical"
+  COVERAGE_PROCESS_START: pyproject.toml
   UV_SYSTEM_PYTHON: 1
 jobs:
   pytest-39:
@@ -30,7 +31,15 @@ jobs:
       - name: show-deps
         run: uv pip freeze
       - name: Run pytest
-        run: pytest tests --cov=narwhals --cov=tests --cov-fail-under=75 --constructors=pandas,pyarrow,polars[eager],polars[lazy]
+        env:
+          # coverage's execv/fork patches raise on Windows; collapse to `subprocess`
+          # there (coverage dedupes) and keep the default values on Linux.
+          COVERAGE_PATCH_EXECV: ${{ matrix.os == 'windows-latest' && 'subprocess' || 'execv' }}
+          COVERAGE_PATCH_FORK: ${{ matrix.os == 'windows-latest' && 'subprocess' || 'fork' }}
+        run: |
+          coverage run -m pytest tests --constructors=pandas,pyarrow,polars[eager],polars[lazy]
+          coverage combine
+          coverage report --fail-under=75
       - name: install-test-plugin
         run: uv pip install -e test-plugin/.
 
@@ -40,6 +49,11 @@ jobs:
         python-version: ["3.10", "3.12"]
         os: [windows-latest]
     runs-on: ${{ matrix.os }}
+    env:
+      # coverage's execv/fork patches raise on Windows; collapse them to `subprocess`
+      # in the pyproject `patch` list (coverage dedupes).
+      COVERAGE_PATCH_EXECV: subprocess
+      COVERAGE_PATCH_FORK: subprocess
     steps:
       - uses: actions/checkout@v6
       - uses: actions/setup-python@v6
@@ -60,7 +74,9 @@ jobs:
         run: uv pip freeze
       - name: Run pytest
         run: |
-          pytest tests --cov=narwhals --cov=tests --runslow --cov-fail-under=95 --constructors=pandas,pandas[nullable],pandas[pyarrow],pyarrow,polars[eager],polars[lazy],duckdb,sqlframe --durations=30
+          coverage run -m pytest tests --runslow --constructors=pandas,pandas[nullable],pandas[pyarrow],pyarrow,polars[eager],polars[lazy],duckdb,sqlframe --durations=30
+          coverage combine
+          coverage report --fail-under=95
 
   pytest-full-coverage:
     strategy:
@@ -91,7 +107,10 @@ jobs:
       - name: show-deps
         run: uv pip freeze
       - name: Run pytest
-        run: pytest tests --cov=narwhals --cov=tests --cov-fail-under=100 --runslow --constructors=pandas,pandas[nullable],pandas[pyarrow],pyarrow,polars[eager],polars[lazy],dask,duckdb,sqlframe --durations=30
+        run: |
+          coverage run -m pytest tests --runslow --constructors=pandas,pandas[nullable],pandas[pyarrow],pyarrow,polars[eager],polars[lazy],dask,duckdb,sqlframe --durations=30
+          coverage combine
+          coverage report --fail-under=100
       - name: Run doctests
         # reprs differ between versions, so we only run doctests on the latest Python
         if: matrix.python-version == '3.13'
@@ -157,7 +176,10 @@ jobs:
       - name: show-deps
         run: uv pip freeze
       - name: Run pytest
-        run: pytest tests --cov=narwhals --cov=tests --runslow --durations=30 --constructors=pandas,pandas[nullable],pandas[pyarrow],pyarrow,polars[eager],polars[lazy],duckdb,sqlframe --cov-fail-under=50
+        run: |
+          coverage run -m pytest tests --runslow --constructors=pandas,pandas[nullable],pandas[pyarrow],pyarrow,polars[eager],polars[lazy],dask,duckdb,sqlframe --durations=30
+          coverage combine
+          coverage report --fail-under=50
 
   python-314t:
     strategy:
@@ -183,4 +205,7 @@ jobs:
       - name: show-deps
         run: uv pip freeze
       - name: Run pytest
-        run: pytest tests --cov=narwhals --cov=tests --runslow --durations=30 --constructors=pandas,pandas[nullable],pandas[pyarrow],pyarrow --cov-fail-under=50
+        run: |
+          coverage run -m pytest tests --runslow --durations=30 --constructors=pandas,pandas[nullable],pandas[pyarrow],pyarrow
+          coverage combine
+          coverage report --fail-under=50

.github/workflows/random_ci_pytest.yml

@@ -6,6 +6,7 @@ on:
 env:
   PY_COLORS: 1
   PYTEST_ADDOPTS: "--numprocesses=logical"
+  COVERAGE_PROCESS_START: pyproject.toml
 
 jobs:
   tox:
@@ -36,5 +37,6 @@ jobs:
         run: uv pip freeze
       - name: Run pytest
         run: |
-            pytest tests --cov=narwhals --cov=tests --cov-fail-under=75 \
-            --constructors=pandas,pyarrow,polars[eager],polars[lazy]
+            coverage run -m pytest tests --constructors=pandas,pyarrow,polars[eager],polars[lazy]
+            coverage combine
+            coverage report --fail-under=75

CONTRIBUTING.md

@@ -149,7 +149,7 @@ If you add code that should be tested, please add tests.
 
 - To run tests, run `pytest`. To check coverage: `pytest --cov=narwhals`
 - To run tests on the doctests, use `pytest narwhals --doctest-modules`
-- To run unit tests and doctests at the same time, run `pytest tests narwhals --cov=narwhals --doctest-modules`
+- To run unit tests and doctests at the same time, run `pytest tests narwhals --doctest-modules`
 - To run tests multiprocessed, you may also want to use [pytest-xdist](https://github.com/pytest-dev/pytest-xdist) (optional)
 - To choose which backends to run tests with you, you can use the `--constructors` flag:
   - To only run tests for pandas, Polars, and PyArrow, use `pytest --constructors=pandas,pyarrow,polars`

Makefile

@@ -38,3 +38,15 @@ docs-serve:  # Build and serve the docs locally
 	$(VENV_BIN)/uv run --no-sync utils/generate_backend_completeness.py
 	$(VENV_BIN)/uv run --no-sync utils/generate_zen_content.py
 	$(VENV_BIN)/uv run --no-sync zensical serve
+
+.PHONY: test
+test: ## Run unittest
+	$(VENV_BIN)/uv pip install \
+		--upgrade \
+		--editable test-plugin/. \
+		--editable .[ibis,modin,pyspark] \
+		--group core \
+		--group tests
+	$(VENV_BIN)/uv run --no-sync coverage run -m pytest tests --all-cpu-constructors --numprocesses=logical
+	$(VENV_BIN)/uv run --no-sync coverage combine
+	$(VENV_BIN)/uv run --no-sync coverage report --fail-under=95

docs/api-reference/testing.md

@@ -1,8 +1,72 @@
 # `narwhals.testing`
 
+## Asserts
+
 ::: narwhals.testing
     handler: python
     options:
       members:
         - assert_frame_equal
         - assert_series_equal
+
+## `pytest` plugin
+
+Narwhals register a pytest plugin that exposes parametrized fixtures with callables
+to build native frames from a column-oriented python `dict`.
+
+### Available fixtures
+
+| Fixture | Backends |
+|---|---|
+| `constructor` | every selected backend (eager + lazy) |
+| `constructor_eager` | only eager backends |
+
+The selection is controlled by two CLI options:
+
+* `--constructors=pandas,polars[lazy],duckdb`: comma-separated list.
+    Defaults to [`DEFAULT_CONSTRUCTORS`][narwhals.testing.constructors.DEFAULT_CONSTRUCTORS]
+    intersected with the backends installed in the current environment.
+* `--all-cpu-constructors`: shortcut for "every CPU backend that is installed".
+* `--use-external-constructor`: Skip narwhals.testing's parametrisation and let
+    another plugin provide the `constructor*` fixtures.
+
+Set the `NARWHALS_DEFAULT_CONSTRUCTORS` environment variable to override the default
+list (useful e.g. when running under `cudf.pandas`).
+
+### Quick start
+
+The plugin auto-loads as soon as you `pip install narwhals`. Just write a test:
+
+```python
+from typing import TYPE_CHECKING
+
+import narwhals as nw
+
+if TYPE_CHECKING:
+    from narwhals.testing.typing import ConstructorEager, Data
+
+
+def test_shape(constructor_eager: ConstructorEager) -> None:
+    data: Data = {"x": [1, 2, 3]}
+    df = nw.from_native(constructor_eager(data), eager_only=True)
+    assert df.shape == (3, 1)
+```
+
+The fixtures are parametrised against every supported backend that is installed
+in the current environment. Filter the matrix on the command line:
+
+```bash
+pytest --constructors="pandas,polars[lazy]"
+pytest --all-cpu-constructors
+```
+
+### Type aliases
+
+::: narwhals.testing.typing
+    handler: python
+    options:
+      members:
+        - Constructor
+        - ConstructorEager
+        - ConstructorLazy
+        - Data

narwhals/stable/v1/typing.py

@@ -8,7 +8,12 @@
 if TYPE_CHECKING:
     from typing_extensions import TypeAlias
 
-    from narwhals._native import NativeDataFrame, NativeDuckDB, NativeLazyFrame
+    from narwhals._native import (
+        NativeDataFrame,
+        NativeDuckDB,
+        NativeIbis,
+        NativeLazyFrame,
+    )
     from narwhals.stable.v1 import DataFrame, Expr, LazyFrame, Series
 
     class DataFrameLike(Protocol):
@@ -25,7 +30,9 @@ def __dataframe__(self, *args: Any, **kwargs: Any) -> Any: ...
 `nw.Expr`, e.g. `df.select('a')`.
 """
 
-IntoDataFrame: TypeAlias = Union["NativeDataFrame", "DataFrameLike", "NativeDuckDB"]
+IntoDataFrame: TypeAlias = Union[
+    "NativeDataFrame", "DataFrameLike", "NativeDuckDB", "NativeIbis"
+]
 """Anything which can be converted to a Narwhals DataFrame.
 
 Use this if your function accepts a narwhalifiable object but doesn't care about its backend.

narwhals/testing/asserts/frame.py

@@ -13,7 +13,6 @@
 
 if TYPE_CHECKING:
     from narwhals._typing import Arrow, IntoBackend, Pandas, Polars
-    from narwhals.typing import DataFrameT, LazyFrameT
 
 GUARANTEES_ROW_ORDER = {
     Implementation.PANDAS,
@@ -26,8 +25,8 @@
 
 
 def assert_frame_equal(
-    left: DataFrameT | LazyFrameT,
-    right: DataFrameT | LazyFrameT,
+    left: DataFrame[Any] | LazyFrame[Any],
+    right: DataFrame[Any] | LazyFrame[Any],
     *,
     check_row_order: bool = True,
     check_column_order: bool = True,
@@ -145,8 +144,8 @@ def assert_frame_equal(
 
 
 def _check_correct_input_type(  # noqa: RET503
-    left: DataFrameT | LazyFrameT,
-    right: DataFrameT | LazyFrameT,
+    left: DataFrame[Any] | LazyFrame[Any],
+    right: DataFrame[Any] | LazyFrame[Any],
     backend: IntoBackend[Polars | Pandas | Arrow] | None,
 ) -> tuple[DataFrame[Any], DataFrame[Any]]:
     # Adapted from https://github.com/pola-rs/polars/blob/afdbf3056d1228cf493901e45f536b0905cec8ea/py-polars/src/polars/testing/asserts/frame.py#L15-L17
@@ -165,8 +164,8 @@ def _check_correct_input_type(  # noqa: RET503
 
 
 def _assert_dataframe_equal(
-    left: DataFrameT,
-    right: DataFrameT,
+    left: DataFrame[Any],
+    right: DataFrame[Any],
     impl: Implementation,
     *,
     check_row_order: bool,
@@ -232,7 +231,11 @@ def _assert_dataframe_equal(
 
 
 def _check_schema_equal(
-    left: DataFrameT, right: DataFrameT, *, check_dtypes: bool, check_column_order: bool
+    left: DataFrame[Any],
+    right: DataFrame[Any],
+    *,
+    check_dtypes: bool,
+    check_column_order: bool,
 ) -> None:
     """Compares DataFrame schema based on specified criteria.