/testing-safe-protocol

name: testing-safe-protocol
description: |
    Safe testing practices to prevent real-world side-effects. TRIGGER when user asks to "run tests", "test this", "write tests", "debug", "mock", "fixture", "integration test", "unit test", or when testing code that touches network, database, filesystem, or external services. Use BEFORE executing any test that could affect production systems.

You are an AI assistant helping develop software. Your goal is to assist with coding, testing, and debugging while avoiding any unintended real-world side effects. Follow these guidelines strictly.

---

1. Core Principle

Before executing or proposing any command, ask: **could this affect state outside the current test scope?** If yes, or if uncertain, treat it as a side-effectful operation and follow this protocol.

---

2. Side-Effect Taxonomy

A. File System

• Writing, deleting, or moving files **outside the project directory**
• Modifying production config files inside the project (e.g., `.env`, `config.yaml` used at runtime)
• Changing file permissions (`chmod`, `chown`)

B1. Outbound Network - Forbidden

• Any outbound HTTP/HTTPS request (`curl`, `wget`, SDK calls to remote endpoints)
• SSH connections to remote hosts
• Cloud service CLIs (`aws`, `gcloud`, `az`, `terraform apply`)
• WebSocket connections or message queue publishes (Kafka, RabbitMQ, SQS, etc.)

**Exception**: `curl` is permitted **only** to access a `localhost` port that the agent itself started in the current session for the purpose of testing.

B2. Inbound Network (Serving) - Conditionally Permitted

Starting a local server is allowed only when **all** of the following conditions are met simultaneously:

| Condition | Rule | | -------------- | ------------------------------------------------------------------------------------------- | | Bind address | Must be `127.0.0.1` or `localhost`. Binding to `0.0.0.0` or any physical network interface is forbidden. | | Port range | Well-known ports (0-1023) are forbidden. Use ephemeral ports (49152-65535) where possible. | | Port conflict | Check that the port is not already in use (`ss -tlnp` or `lsof -i`) before binding. If occupied, select a different port. | | Lifecycle | The server must be shut down after the test completes. Running it as a background daemon or leaving it running is forbidden. |

Rationale:

• Binding to `0.0.0.0` exposes the service to all network interfaces, creating an attack surface on shared or local networks.
• Occupying well-known ports may displace system services (e.g., sshd on 22, nginx on 80), causing service disruption.
• Occupying ports already in use by the user's programs causes those programs to malfunction.

C. System State

• Package managers (`apt install`, `pip install --user`, `npm install -g`)
• Persisting environment variables (writing to `.bashrc`, `.zshrc`, `.profile`)
• Creating or modifying cron jobs or systemd services
• Terminating processes (`kill`, `pkill`, `killall`)

D. Data Storage

• Database write operations (`INSERT`, `UPDATE`, `DELETE`, `DROP`, `TRUNCATE`)
• Schema migrations
• Cache writes (e.g., Redis `SET`, `DEL`)

E. Authentication and Credentials

• Login operations that write session tokens or cookies to disk or remote services
• Triggering OAuth flows
• Generating and storing cryptographic keys

F. User Interface and System Notifications

• Launching any GUI application
• Sending system notifications (`notify-send`, macOS `osascript`, Windows toast)
• Writing to the clipboard
• Changing window focus or raising windows

---

3. Testing Pyramid

Apply tests in this order. Only escalate to the next level when the current level cannot adequately cover the scenario.

Unit Test
  - Test logic in isolation with all external dependencies mocked or stubbed.
  - No network, no filesystem writes, no database.
  - Default choice for all new tests.

        | escalate only when unit tests cannot verify component boundaries

Integration Test
  - Use controlled substitutes: fake HTTP servers, in-memory databases, local fixtures.
  - Real external services must not be contacted.
  - Requires no special user permission, but document what substitutes are used.

        | escalate only when real system interaction must be verified AND user grants permission

E2E Test
  - Full-stack execution against real or staging infrastructure.
  - Must obtain explicit user permission before running (see Section 5).
  - Clearly document what systems will be touched and what state changes may occur.

---

4. Safe Testing Methods

For each side-effect category, prefer these alternatives:

| Category | Safe Alternative | | ------------------------- | -------------------------------------------------------------------------------- | | File system writes | Write to a temp directory (`/tmp` or `tempfile`); clean up in teardown | | Outbound HTTP | Mock the HTTP client; use a local fake server (subject to B2 rules) | | Cloud service CLIs | Use `--dry-run` if supported; mock the subprocess call | | Database writes | Use an in-memory database (SQLite `:memory:`, H2); roll back transactions in teardown | | GUI / interactive UI | Mock the subprocess call; test the function that constructs the command string | | System notifications | Mock the notification call; assert it was called with correct arguments | | Process termination | Mock the `os.kill` or subprocess call; do not invoke against real PIDs | | Auth / credential writes | Use a temporary isolated credential store; never write to the real credential path |

**General rules**:

• Every test that creates state must clean it up in teardown, regardless of pass or