chore: move tests to a narwhals-testing package

.github/workflows/extremes.yml

@@ -31,6 +31,8 @@ jobs:
       - name: install-reqs
         run: |
           uv pip install -e . --group tests
+      - name: install-narwhals-testing
+        run: uv pip install -e narwhals-testing/.
       - name: show-deps
         run: uv pip freeze
       - name: Assert dependencies
@@ -44,7 +46,7 @@ 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: pytest --cov=narwhals --cov=narwhals-testing/narwhals_testing/tests --cov-fail-under=50 --runslow --constructors=pandas,pyarrow,polars[eager],polars[lazy],duckdb
 
   pretty_old_versions:
     strategy:
@@ -67,6 +69,8 @@ jobs:
         run: uv pip install pipdeptree tox virtualenv setuptools pandas==1.1.5 polars==0.20.4 numpy==1.19.3 pyarrow==14.0.0 "pyarrow-stubs<17" scipy==1.6.0 scikit-learn==1.1.0 duckdb==1.2 tzdata
       - name: install-reqs
         run: uv pip install -e . --group tests
+      - name: install-narwhals-testing
+        run: uv pip install -e narwhals-testing/.
       - name: show-deps
         run: uv pip freeze
       - name: show-deptree
@@ -82,7 +86,7 @@ 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: pytest --cov=narwhals --cov=narwhals-testing/narwhals_testing/tests --cov-fail-under=50 --runslow --constructors=pandas,pyarrow,polars[eager],polars[lazy],duckdb
 
   not_so_old_versions:
     strategy:
@@ -105,6 +109,8 @@ jobs:
         run: uv pip install tox virtualenv setuptools pandas==2.0.3 polars==0.20.8 numpy==1.24.4 pyarrow==15.0.0 "pyarrow-stubs<17" scipy==1.8.0 scikit-learn==1.3.0 duckdb==1.3 dask[dataframe]==2024.10 tzdata
       - name: install-reqs
         run: uv pip install -e . --group tests
+      - name: install-narwhals-testing
+        run: uv pip install -e narwhals-testing/.
       - name: show-deps
         run: uv pip freeze
       - name: Assert not so old versions dependencies
@@ -119,7 +125,7 @@ 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: pytest --cov=narwhals --cov=narwhals-testing/narwhals_testing/tests --cov-fail-under=50 --runslow --constructors=pandas,pyarrow,polars[eager],polars[lazy],dask,duckdb
 
   nightlies:
     strategy:
@@ -140,6 +146,8 @@ jobs:
           cache-dependency-glob: "pyproject.toml"
       - name: install-reqs
         run: uv pip install -e . --group tests
+      - name: install-narwhals-testing
+        run: uv pip install -e narwhals-testing/.
       - name: install polars pre-release
         run: |
           uv pip uninstall polars
@@ -176,5 +184,5 @@ jobs:
           echo "$DEPS" | grep 'duckdb.*dev'
       - name: Run pytest
         run: |
-          pytest tests --cov=narwhals --cov=tests --cov-fail-under=50 --runslow \
+          pytest --cov=narwhals --cov=narwhals-testing/narwhals_testing/tests --cov-fail-under=50 --runslow \
           --constructors=pandas,pandas[nullable],pandas[pyarrow],pyarrow,polars[eager],polars[lazy],dask,duckdb

.github/workflows/pytest-ibis.yml

@@ -33,7 +33,9 @@ jobs:
           # Temporary pin until it's fixed upstream
           uv pip install "sqlglot<28.6"
           uv pip install -e ".[ibis]"
+      - name: install-narwhals-testing
+        run: uv pip install -e narwhals-testing/.
       - name: show-deps
         run: uv pip freeze
       - name: Run pytest
-        run: pytest tests --constructors ibis
+        run: pytest --constructors ibis

.github/workflows/pytest-modin.yml

@@ -31,7 +31,9 @@ jobs:
       - name: install modin
         run: |
           uv pip install -e ".[modin]"
+      - name: install-narwhals-testing
+        run: uv pip install -e narwhals-testing/.
       - name: show-deps
         run: uv pip freeze
       - name: Run pytest
-        run: pytest tests --constructors modin[pyarrow]
+        run: pytest --constructors modin[pyarrow]

.github/workflows/pytest-pyspark.yml

@@ -6,8 +6,8 @@ on:
       - narwhals/_expression_parsing.py
       - narwhals/_spark_like/**
       - narwhals/_sql/**
-      - tests/*scan*.py
-      - tests/frame/*sink*.py
+      - narwhals-testing/narwhals_testing/tests/*scan*.py
+      - narwhals-testing/narwhals_testing/tests/frame/*sink*.py
   schedule:
     - cron: 0 12 * * 0  # Sunday at mid-day
 
@@ -37,10 +37,12 @@ jobs:
         run: uv pip install -e . --group core-tests
       - name: install pyspark
         run: uv pip install -e ".[pyspark]"
+      - name: install-narwhals-testing
+        run: uv pip install -e narwhals-testing/.
       - 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: pytest --cov=narwhals/_spark_like --cov-fail-under=95 --runslow --constructors pyspark
 
 
   pytest-pyspark-min-version-constructor:
@@ -64,10 +66,12 @@ jobs:
         run: uv pip install -e . --group core-tests --system
       - name: install pyspark (min version)
         run: uv pip install "pyspark==3.5.0" --system
+      - name: install-narwhals-testing
+        run: uv pip install -e narwhals-testing/.
       - name: show-deps
         run: uv pip freeze
       - name: Run pytest
-        run: pytest tests --constructors pyspark
+        run: pytest --constructors pyspark
 
   pytest-pyspark-connect-constructor:
     strategy:
@@ -103,6 +107,8 @@ jobs:
         run: uv pip install -e . --group core-tests --group extra "pyarrow<22.0"
       - name: install pyspark
         run: echo "setuptools<78" | uv pip install -e . "pyspark[connect]==${SPARK_VERSION}"
+      - name: install-narwhals-testing
+        run: uv pip install -e narwhals-testing/.
       - name: show-deps
         run: uv pip freeze
 
@@ -133,7 +139,7 @@ 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: pytest --cov=narwhals/_spark_like --cov-fail-under=95 --runslow --constructors "pyspark[connect]"
 
       - name: Stop Spark Connect server
         if: always()

.github/workflows/pytest.yml

@@ -29,10 +29,12 @@ jobs:
         run: uv pip install -e ".[pandas,polars,pyarrow]" --group tests
       - 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]
       - name: install-test-plugin
         run: uv pip install -e test-plugin/.
+      - name: install-narwhals-testing
+        run: uv pip install -e narwhals-testing/.
+      - name: Run pytest
+        run: pytest --cov=narwhals --cov=narwhals-testing/narwhals_testing/tests --cov-fail-under=75 --constructors=pandas,pyarrow,polars[eager],polars[lazy]
 
   pytest-windows:
     strategy:
@@ -56,11 +58,13 @@ jobs:
         run: uv pip install -e "." --group core-tests --group extra
       - name: install-test-plugin
         run: uv pip install -e test-plugin/.
+      - name: install-narwhals-testing
+        run: uv pip install -e narwhals-testing/.
       - name: show-deps
         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
+          pytest --cov=narwhals --cov=narwhals-testing/narwhals_testing/tests --runslow --cov-fail-under=95 --constructors=pandas,pandas[nullable],pandas[pyarrow],pyarrow,polars[eager],polars[lazy],duckdb,sqlframe --durations=30
 
   pytest-full-coverage:
     strategy:
@@ -88,10 +92,12 @@ jobs:
         run: uv pip install -e ".[dask]" --group core-tests --group extra
       - name: install-test-plugin
         run: uv pip install -e test-plugin/.
+      - name: install-narwhals-testing
+        run: uv pip install -e narwhals-testing/.
       - 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: pytest --cov=narwhals --cov=narwhals-testing/narwhals_testing/tests --cov-fail-under=100 --runslow --constructors=pandas,pandas[nullable],pandas[pyarrow],pyarrow,polars[eager],polars[lazy],dask,duckdb,sqlframe --durations=30
       - name: Run doctests
         # reprs differ between versions, so we only run doctests on the latest Python
         if: matrix.python-version == '3.13'
@@ -118,22 +124,23 @@ jobs:
       - name: install-reqs
         run: |
           uv pip install -e ".[pandas]" --group tests
+          uv pip install -e narwhals-testing/.
           uv pip freeze
       - name: Run pytest (pandas and pandas[nullable])
-        run: pytest tests --runslow --constructors=pandas,pandas[nullable]
+        run: pytest --runslow --constructors=pandas,pandas[nullable]
       - name: install-more-reqs
         run: |
           uv pip install -U pyarrow
           uv pip freeze
       - name: Run pytest (pandas[pyarrow] and pyarrow)
-        run: pytest tests --runslow --constructors=pandas[pyarrow],pyarrow
+        run: pytest --runslow --constructors=pandas[pyarrow],pyarrow
       - name: install-polars
         run: |
           uv pip uninstall pandas pyarrow
           uv pip install polars
           uv pip freeze
       - name: Run pytest (polars)
-        run: pytest tests --runslow --constructors=polars[eager],polars[lazy]
+        run: pytest --runslow --constructors=polars[eager],polars[lazy]
 
   python-314:
     strategy:
@@ -154,10 +161,12 @@ jobs:
           cache-dependency-glob: "pyproject.toml"
       - name: install-reqs
         run: uv pip install -e . --group tests pandas polars pyarrow duckdb sqlframe
+      - name: install-narwhals-testing
+        run: uv pip install -e narwhals-testing/.
       - 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: pytest --cov=narwhals --cov=narwhals-testing/narwhals_testing/tests --runslow --durations=30 --constructors=pandas,pandas[nullable],pandas[pyarrow],pyarrow,polars[eager],polars[lazy],duckdb,sqlframe --cov-fail-under=50
 
   python-314t:
     strategy:
@@ -180,7 +189,9 @@ jobs:
           cache-dependency-glob: "pyproject.toml"
       - name: install-reqs
         run: uv pip install -e . --group tests --pre pandas pyarrow
+      - name: install-narwhals-testing
+        run: uv pip install -e narwhals-testing/.
       - 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: pytest --cov=narwhals --cov=narwhals-testing/narwhals_testing/tests --runslow --durations=30 --constructors=pandas,pandas[nullable],pandas[pyarrow],pyarrow --cov-fail-under=50

.github/workflows/random_ci_pytest.yml

@@ -32,9 +32,11 @@ jobs:
         run: uv pip install -r random-requirements.txt --system
       - name: install-narwhals
         run: uv pip install -e . --group tests --system
+      - name: install-narwhals-testing
+        run: uv pip install -e narwhals-testing/.
       - name: show versions
         run: uv pip freeze
       - name: Run pytest
         run: |
-            pytest tests --cov=narwhals --cov=tests --cov-fail-under=75 \
+            pytest --cov=narwhals --cov=narwhals-testing/narwhals_testing/tests --cov-fail-under=75 \
             --constructors=pandas,pyarrow,polars[eager],polars[lazy]

CONTRIBUTING.md

@@ -12,7 +12,7 @@ If you've got experience with open source contributions, the following instructi
 - `git remote add origin <your fork goes here>`
 - `uv venv -p 3.12`
 - `. .venv/bin/activate`
-- `uv pip install -U -e . --group local-dev -e test-plugin`
+- `uv pip install -U -e . --group local-dev -e test-plugin -e narwhals-testing`
 - To run tests: `pytest`
 - To run all linting checks: `pre-commit run --all-files`
 - To run static typing checks: `make typing`
@@ -124,7 +124,7 @@ If you want to run PySpark-related tests, you'll need to have Java installed. Re
 
    4. Activate it. On Linux, this is `. .venv/bin/activate`, on Windows `.\.venv\Scripts\activate`.
 
-2. Install Narwhals: `uv pip install -e . --group local-dev -e test-plugin`. This will include fast-ish core libraries and dev dependencies.
+2. Install Narwhals: `uv pip install -e . --group local-dev -e test-plugin -e narwhals-testing`. This will include fast-ish core libraries and dev dependencies.
    If you also want to test other libraries like Dask , PySpark, and Modin, you can install them too with
    `uv pip install -e ".[dask, pyspark, modin]" --group local-dev`.
 

narwhals-testing/narwhals_testing/__init__.py

@@ -0,0 +1,18 @@
+"""narwhals-testing: Narwhals test suite distribution for plugin authors.
+
+Usage::
+
+    pip install narwhals-testing my-narwhals-plugin
+    pytest --pyargs narwhals_testing.tests --use-external-constructor
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+__version__ = "0.1.0"
+
+
+def get_test_dir() -> Path:
+    """Return the path to the distributed tests directory."""
+    return Path(__file__).resolve().parent / "tests"

narwhals-testing/narwhals_testing/_plugin.py

@@ -0,0 +1,48 @@
+"""narwhals-testing pytest plugin.
+
+Registered via the ``pytest11`` entry point. Handles two concerns:
+
+1. Adds the ``narwhals_testing`` package directory to ``sys.path`` so that
+   distributed test files can resolve ``from tests.utils import ...``.
+   This happens at import time because entry-point plugin modules are
+   imported before conftest files are loaded.
+
+2. Registers CLI options (``--use-external-constructor``, etc.) so they are
+   available even when tests are run via ``--pyargs``.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import pytest
+
+_PACKAGE_DIR = str(Path(__file__).resolve().parent)
+
+if _PACKAGE_DIR not in sys.path:
+    sys.path.insert(0, _PACKAGE_DIR)
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    group = parser.getgroup("narwhals-testing")
+    group.addoption(
+        "--runslow", action="store_true", default=False, help="run slow tests"
+    )
+    group.addoption(
+        "--all-cpu-constructors",
+        action="store_true",
+        default=False,
+        help="run tests with all cpu constructors",
+    )
+    group.addoption(
+        "--use-external-constructor",
+        action="store_true",
+        default=False,
+        help="run tests with external constructor",
+    )
+    group.addoption(
+        "--constructors", action="store", default=None, type=str, help="libraries to test"
+    )