What am I testing?
│
├─ Pure logic / data transformation
│  └─ Level 1: DI with fake implementations
│
├─ External service interaction
│  │
│  ├─ Can service run locally? (Docker/VM)
│  │  ├─ YES → Level 2: Real service in Docker
│  │  └─ NO  → Level 3: Real service on internet
│  │
│  └─ Thinking of mocking?
│     └─ STOP. Redesign with DI (Level 1) or use real service (Level 2/3)

from dataclasses import dataclass
from typing import Callable, Protocol


class CommandRunner(Protocol):
    def run(self, cmd: list[str]) -> tuple[int, str, str]: ...


@dataclass
class SyncDependencies:
    run_command: CommandRunner
    get_env: Callable[[str], str | None] = os.environ.get


def sync_to_remote(source: str, dest: str, deps: SyncDependencies) -> SyncResult:
    cmd = build_command(source, dest)
    returncode, stdout, stderr = deps.run_command.run(cmd)
    return SyncResult(success=returncode == 0)


# Test with controlled implementation
def test_sync_returns_success_on_zero_exit():
    class FakeRunner:
        def run(self, cmd: list[str]) -> tuple[int, str, str]:
            return (0, "Transferred: 5 files", "")

    deps = SyncDependencies(run_command=FakeRunner())
    result = sync_to_remote("/src", "remote:dest", deps)
    assert result.success is True

def test_command_includes_checksum_flag():
    cmd = build_rclone_command("/source", "remote:dest", checksum=True)
    assert "--checksum" in cmd


def test_unicode_paths_preserved():
    cmd = build_rclone_command("/tank/фото", "remote:резервная")
    assert "/tank/фото" in cmd

from dataclasses import dataclass, field
from typing import Iterator
import itertools

_id_counter: Iterator[int] = itertools.count(1)


@dataclass
class AuditResultFactory:
    url: str = field(default_factory=lambda: f"https://example.com/{next(_id_counter)}")
    performance: int = 90

    def build(self) -> dict:
        return {"url": self.url, "scores": {"performance": self.performance}}


def test_fails_on_low_performance():
    result = AuditResultFactory(performance=45).build()
    analysis = analyze_results([result], deps)
    assert analysis.passed is False

@dataclass
class PostgresHarness:
    container_name: str = "test-postgres"
    port: int = 5432

    def start(self) -> None:
        subprocess.run(
            [
                "docker",
                "run",
                "-d",
                "--name",
                self.container_name,
                "-p",
                f"{self.port}:5432",
                "-e",
                "POSTGRES_PASSWORD=test",
                "postgres:15",
            ],
            check=True,
        )
        self._wait_for_ready()

    def stop(self) -> None:
        subprocess.run(["docker", "rm", "-f", self.container_name])

    @property
    def connection_string(self) -> str:
        return f"postgresql://postgres:test@localhost:{self.port}/postgres"

@pytest.fixture(scope="module")
def database():
    harness = PostgresHarness()
    harness.start()
    yield harness
    harness.stop()


@pytest.fixture(autouse=True)
def reset_database(database):
    yield
    database.reset()


@pytest.mark.integration
def test_user_repository_saves_and_retrieves(database):
    repo = UserRepository(database.connection_string)
    user = User(email="test@example.com", name="Test User")
    repo.save(user)

    retrieved = repo.find_by_email("test@example.com")
    assert retrieved.name == "Test User"

CREDENTIALS_DOC = """
Level 3 tests require these environment variables:

Required:
  DROPBOX_TEST_TOKEN    - From 1Password: "Engineering/Test Credentials"

Setup:
  cp .env.test.example .env.test
  # Fill in values from 1Password
"""


def load_credentials() -> dict | None:
    token = os.environ.get("DROPBOX_TEST_TOKEN")
    if not token:
        return None
    return {"token": token}


@pytest.fixture
def dropbox_config(tmp_path) -> Path | None:
    creds = load_credentials()
    if not creds:
        pytest.skip("DROPBOX_TEST_TOKEN not set")

    config = tmp_path / "rclone.conf"
    config.write_text(f"""
[dropbox-test]
type = dropbox
token = {creds["token"]}
""")
    return config

credentials = load_credentials()
skip_no_creds = pytest.mark.skipif(
    credentials is None, reason="E2E credentials not configured"
)


@skip_no_creds
@pytest.mark.e2e
def test_full_sync_workflow(dropbox_test_folder, dropbox_config):
    result = sync_to_dropbox(local_path, dropbox_test_folder, config=dropbox_config)
    assert result.success

# pyproject.toml
[tool.pytest.ini_options]
testpaths = ["spx"]
python_files = ["*.test.py"]

# Run by level (path-based, no markers needed):
# pytest spx/ -k "unit"         # Level 1 only
# pytest spx/ -k "integration"  # Level 2
# pytest spx/ -k "e2e"          # Level 3
# pytest spx/                   # All tests

# ❌ Mocking destroys confidence
@patch("subprocess.run")
@patch("os.path.exists")
def test_sync(mock_exists, mock_run):
    mock_exists.return_value = True
    mock_run.return_value = Mock(returncode=0)
    result = sync_files(src, dest)
    assert result.success  # What did we prove? NOTHING.

# ❌ Jumping to Level 3 without Level 1/2 coverage
@pytest.mark.e2e
def test_sync_to_dropbox():
    sync_to_dropbox(local_path, "dropbox:backup")
    # If this fails, we don't know if it's our code or Dropbox

# ❌ Testing HOW, not WHAT
def test_uses_rclone_sync_command():
    with capture_subprocess() as captured:
        sync_dataset(src, dest)
    assert "rclone sync" in captured.command  # Implementation detail!


# ✅ Test the observable behavior instead
def test_files_synced():
    sync_dataset(src, dest)
    assert (dest / "file.txt").exists()

spx/
└── {capability}/
    └── {feature}/
        ├── {feature}.md           # Feature spec
        └── tests/
            ├── {name}.unit.test.py        # Level 1 (pytest)
            ├── {name}.integration.test.py # Level 2 (pytest)
            ├── {name}.e2e.test.py          # Level 3, non-browser (pytest)
            └── {name}.e2e.spec.py          # Level 3, browser (Playwright)

pytest spx/ -k "unit"         # All unit tests
pytest spx/ -k "integration"  # All integration tests
pytest spx/ -k "e2e" --ignore="*.spec.py"  # Non-browser E2E
npx playwright test spx/      # Browser E2E (finds *.spec.py)

myproject_testing/          # INSTALLABLE via uv pip install -e ".[dev]"
├── __init__.py
├── harnesses/              # Active code for tests
│   ├── __init__.py
│   ├── context.py          # Test environment context manager
│   ├── postgres.py         # PostgreSQL harness
│   ├── docker.py           # Generic Docker harness
│   └── factories.py        # Seeded data factories
└── fixtures/               # Static test data
    ├── sample_config.json
    └── values.py           # TYPICAL, EDGES collections

# In spx/{capability}/{feature}/tests/sync.unit.test.py
from myproject_testing.harnesses.factories import SyncResultFactory
from myproject_testing.fixtures.values import TYPICAL_PATHS