Add tox for standardized test orchestration across environments

.github/workflows/ci.yml

@@ -107,15 +107,13 @@ jobs:
       run: uv lock && uv sync --locked --all-extras --dev
 
     - name: Verify centralized version constraints
-      run: python scripts/verify_constraints.py
+      run: uv run --frozen tox -e verify-constraints
 
     - name: Check linting
-      run: |
-        uv run --frozen ruff check . --preview
+      run: uv run --frozen tox -e lint
 
     - name: Check formatting
-      run: |
-        uv run --frozen ruff format --check .
+      run: uv run --frozen tox -e format
 
     - name: Build package
       run: |
@@ -124,14 +122,12 @@ jobs:
         AGENT365_PYTHON_SDK_PACKAGE_VERSION: ${{ needs.version-number.outputs.PACKAGE_VERSION }}
 
     - name: Run unit tests
-      run: |
-        uv run --frozen pytest tests/ -v --tb=short -m "not integration"
+      run: uv run --frozen tox -e py3${{ matrix.python-version == '3.11' && '11' || '12' }}
 
     - name: Run integration tests
       # Only run integration tests if secrets are available
       if: ${{ vars.RUN_INTEGRATION_TESTS == 'true' }}
-      run: |
-        uv run --frozen pytest -m integration -v --tb=short
+      run: uv run --frozen tox -e integration
       env:
         AZURE_OPENAI_API_KEY: ${{ secrets.AZURE_OPENAI_API_KEY }}
         AZURE_OPENAI_ENDPOINT: ${{ vars.AZURE_OPENAI_ENDPOINT }}

.gitignore

@@ -72,6 +72,7 @@ dist/
 build/
 .eggs/
 .pytest_cache/
+.tox/
 _version.py
 
 # Test coverage and reports

CLAUDE.md

@@ -61,6 +61,31 @@ pytest tests/ --cov=libraries --cov-report=html -v
 - `unit`: Fast, mocked tests (default)
 - `integration`: Slow tests requiring real services/API keys
 
+### Running with tox
+
+```bash
+# Run all default environments (lint, format, unit tests on 3.11 + 3.12)
+uv run tox
+
+# Run a specific environment
+uv run tox -e lint
+uv run tox -e format
+uv run tox -e py311
+uv run tox -e py312
+
+# Run integration tests (requires env vars)
+uv run tox -e integration
+
+# Verify centralized dependency constraints
+uv run tox -e verify-constraints
+
+# Pass extra args to pytest
+uv run tox -e py311 -- -k "environment"
+
+# List all available environments
+uv run tox list
+```
+
 ### Linting and Formatting
 
 ```bash
@@ -241,7 +266,8 @@ Place it before imports with one blank line after.
 The `.github/workflows/ci.yml` pipeline:
 - Runs on pushes to `main` and `release/*` branches
 - Tests both Python 3.11 and 3.12
-- Executes: lint check → format check → build → unit tests → integration tests (if secrets available)
+- Uses **tox** (via `uv run --frozen tox -e <env>`) to run lint, format, test, and constraint verification steps
+- Executes: verify-constraints → lint → format → build → unit tests → integration tests (if secrets available)
 - Only publishes packages on `release/*` branches when SDK changes detected
 - Uses git-based versioning (tags on release branches = official versions, others = dev versions)
 

pyproject.toml

@@ -48,6 +48,8 @@ dev-dependencies = [
     "pytest-asyncio",
     "pytest-mock",
     "ruff",
+    "tox>=4.0",
+    "tox-uv>=1.0",
     "python-dotenv",
     "openai",
     "agent-framework-azure-ai",
@@ -103,6 +105,10 @@ constraint-dependencies = [
     "PyJWT >= 2.8.0",
     "typing-extensions >= 4.0.0",
 
+    # --- Tox ---
+    "tox >= 4.23.0",
+    "tox-uv >= 1.18.0",
+
     # --- Development & Testing ---
     "black >= 23.0.0",
     "mypy >= 1.0.0",
@@ -207,3 +213,35 @@ skip-magic-trailing-comma = false
 
 # Like Black, automatically detect the appropriate line ending.
 line-ending = "auto"
+
+# Tox configuration
+[tool.tox]
+requires = ["tox>=4.23", "tox-uv>=1.18"]
+
+[tool.tox.env_run_base]
+runner = "uv-venv-lock-runner"
+uv_sync_flags = ["--all-extras", "--dev"]
+commands = [["pytest", "tests/", "-v", "--tb=short", "-m", "not integration", { replace = "posargs", default = "", extend = true }]]
+
+[tool.tox.env.py311]
+base_python = ["python3.11"]
+
+[tool.tox.env.py312]
+base_python = ["python3.12"]
+
+[tool.tox.env.lint]
+base_python = ["python3.11"]
+commands = [["ruff", "check", ".", "--preview", { replace = "posargs", default = "", extend = true }]]
+
+[tool.tox.env.format]
+base_python = ["python3.11"]
+commands = [["ruff", "format", "--check", ".", { replace = "posargs", default = "", extend = true }]]
+
+[tool.tox.env.integration]
+base_python = ["python3.11"]
+commands = [["pytest", "-m", "integration", "-v", "--tb=short", { replace = "posargs", default = "", extend = true }]]
+pass_env = ["AZURE_OPENAI_API_KEY", "AZURE_OPENAI_ENDPOINT", "AZURE_OPENAI_DEPLOYMENT", "AZURE_OPENAI_API_VERSION", "AGENT365_TEST_TENANT_ID", "AGENT365_TEST_AGENT_ID", "ENABLE_OBSERVABILITY"]
+
+[tool.tox.env.verify-constraints]
+base_python = ["python3.11"]
+commands = [["python", "scripts/verify_constraints.py"]]