Add nox and nox-uv for DX testing improvements

[birdcar]

Description

TL;DR -- You (or an agent) can now run script/test.sh locally to verify that changes to the SDK work across all supported Python versions

Testing locally kinda sucks right now. #323 helped by making it possible to run uv run --python=3.11 to target a specific Python version (and recreate the environment effortlessly), but it's still a manual process.

This change extends that improvement by adding nox and nox-uv for improved multi-version Python testing.

With this change, local devs will be able to:

• Test against all supported Python versions (3.8-3.14) with a single command
• Cache the virtual environments used in testing by default for faster local iteration
• Leverage a new scripts/test.sh script that means you don't even need to remember the syntax
• Allow LLM's like Claude Code to verify that their changes work for all supported versions of Python.

One limitation is that uv-nox specifically doesn't work on versions of Python < 3.9, but thats' for the contributor, not the library consumer. Since that's EOL anyways, it's safe to assume that folks shouldn't be developing with that version of Python imo.

One final note, this does not change the ci.yaml file, and it doesn't change that intentionally. A matrix strategy is still faster in CI and is working well. This is purely an improvement for the developer experience.

Below is the experience / performance of running it after you have cached the first run (and have the dependencies in the nox environment for each version):

$ scripts/test.sh
.......
========================================= 409 passed, 47397 warnings in 4.52s =========================================
nox > Session tests-3.14 was successful in 5 seconds.
nox > Ran 7 sessions in 44 seconds:
nox > * tests-3.8: success, took 6 seconds
nox > * tests-3.9: success, took 6 seconds
nox > * tests-3.10: success, took 6 seconds
nox > * tests-3.11: success, took 6 seconds
nox > * tests-3.12: success, took 6 seconds
nox > * tests-3.13: success, took 6 seconds
nox > * tests-3.14: success, took 5 seconds

Documentation

Does this require changes to the WorkOS Docs? E.g. the API Reference or code snippets need updates.

[ ] Yes

If yes, link a related docs PR and add a docs maintainer as a reviewer. Their approval is required.

[greptile-apps]

Greptile Summary

Added nox and nox-uv to enable local multi-version Python testing (3.8-3.14) with a single command, significantly improving developer experience while keeping CI unchanged.

• Fixed typo in CLAUDE.md: ur run → uv run in ruff command
• Added comprehensive nox configuration (noxfile.py) with sessions for tests, coverage, linting, type checking, and CI checks
• Created user-friendly scripts/test.sh wrapper with flexible argument parsing (version selection, coverage, fresh envs, pytest passthrough)
• Added nox dependencies to pyproject.toml with appropriate Python >=3.9 constraints (nox-uv doesn't support Python 3.8 for contributors, but library still supports 3.8+ consumers)
• Updated CLAUDE.md with extensive documentation on nox usage patterns and testing workflows
• Lockfile (uv.lock) properly updated with new transitive dependencies

The implementation follows best practices: virtual environment caching for fast iteration, clear session naming conventions, and proper separation between local DX improvements and CI infrastructure.

Confidence Score: 5/5

• This PR is safe to merge with no risk - it only adds optional developer tooling
• Score of 5 reflects that this PR introduces purely additive changes for local developer experience without modifying any production code, tests, or CI workflows. The nox configuration follows established patterns, dependencies are properly constrained, and the shell script includes appropriate error handling. No breaking changes or risky modifications.
• No files require special attention - all changes are well-implemented

Important Files Changed

Filename	Overview
CLAUDE.md	Fixed typo in ruff command (ur run → uv run) and added comprehensive nox documentation for multi-version testing
noxfile.py	Well-structured nox configuration with sessions for tests, coverage, linting, and CI checks across Python 3.8-3.14
pyproject.toml	Added nox and nox-uv dependencies to new dependency group, appropriately constrained to Python >=3.9
scripts/test.sh	Robust bash script for running nox sessions with flexible argument parsing, version selection, and pytest passthrough

Sequence Diagram

sequenceDiagram
    participant Dev as Developer
    participant Script as scripts/test.sh
    participant Nox as nox
    participant UV as uv
    participant Test as pytest

    Dev->>Script: ./scripts/test.sh 3.12
    Script->>Script: Parse arguments (versions, flags)
    Script->>UV: Check uv availability
    UV-->>Script: ✓ Available
    Script->>Script: Build nox command
    Script->>Nox: uv run nox -s tests-3.12
    Nox->>UV: Create/reuse virtual env (Python 3.12)
    UV-->>Nox: ✓ Environment ready
    Nox->>UV: Install test dependencies
    UV-->>Nox: ✓ Dependencies installed
    Nox->>Test: Run pytest
    Test-->>Nox: Test results
    Nox-->>Script: Exit code
    Script-->>Dev: Test results displayed

Loading

[greptile-apps]

_{4 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}