Merge pull request #9 from isc-tdyar/033-devtester-skills

feat: Integrate iris-devtester agentic skills for automated testing

Author: isc-tdyar

AGENTS.md

@@ -0,0 +1,29 @@
+# iris-pgwire-gh Development Guidelines
+
+Auto-generated from all feature plans. Last updated: 2026-01-02
+
+## Active Technologies
+
+- Python 3.11+ + `iris-devtester`, `intersystems-irispython`, `psycopg[binary]` (033-devtester-skills)
+
+## Project Structure
+
+```text
+src/
+tests/
+```
+
+## Commands
+
+cd src [ONLY COMMANDS FOR ACTIVE TECHNOLOGIES][ONLY COMMANDS FOR ACTIVE TECHNOLOGIES] pytest [ONLY COMMANDS FOR ACTIVE TECHNOLOGIES][ONLY COMMANDS FOR ACTIVE TECHNOLOGIES] ruff check .
+
+## Code Style
+
+Python 3.11+: Follow standard conventions
+
+## Recent Changes
+
+- 033-devtester-skills: Added Python 3.11+ + `iris-devtester`, `intersystems-irispython`, `psycopg[binary]`
+
+<!-- MANUAL ADDITIONS START -->
+<!-- MANUAL ADDITIONS END -->

docs/testing.md

@@ -44,6 +44,15 @@ This framework follows the project's constitutional principles:
 - **Principle III**: Protocol Fidelity (real PostgreSQL clients)
 - **Principle V**: Diagnostic Excellence (comprehensive failure capture)
 
+### Automated Infrastructure with iris-devtester
+
+The framework now integrates with `iris-devtester` to provide automated container management and troubleshooting.
+
+✅ **Automated Containers**: `iris_container` fixture automatically starts an IRIS instance if one is not running.
+✅ **Auto-Remediation**: `iris_connection` automatically handles "Password change required" and enables CallIn services.
+✅ **Test Fixtures**: `iris_fixture` allows loading and exporting reproducible test data sets via `.DAT` files.
+✅ **Agentic Diagnostics**: Failures trigger the `/troubleshooting` skill logic to provide remediation hints in `test_failures.jsonl`.
+
 ---
 
 ## Quick Start
@@ -254,6 +263,46 @@ def test_pgwire_query(pgwire_client):
 
 **Cleanup**: Connection closed after test
 
+### `iris_connection` (Function-Scoped)
+
+**Purpose**: Provides a DBAPI connection to IRIS with auto-remediation
+
+**Returns**: `irispython.Connection` (or equivalent DBAPI connection)
+
+**Features**:
+- Auto-retries on transient connection failures
+- Automatically handles "ChangePassword" requirement
+- Enables CallIn service if disabled
+
+**Example**:
+```python
+def test_with_remediation(iris_connection):
+    with iris_connection.cursor() as cur:
+        cur.execute("SELECT 1")
+        assert cur.fetchone()[0] == 1
+```
+
+---
+
+### `iris_fixture` (Function-Scoped)
+
+**Purpose**: Load and export IRIS test data sets (.DAT files)
+
+**Returns**: Fixture helper object
+
+**Methods**:
+- `load(dat_file)`: Loads a .DAT file into IRIS
+- `export(table_name, output_file)`: Exports a table to a .DAT file
+
+**Example**:
+```python
+def test_vector_search(iris_fixture, iris_connection):
+    iris_fixture.load("healthcare_data.dat")
+    with iris_connection.cursor() as cur:
+        cur.execute("SELECT COUNT(*) FROM Patients")
+        assert cur.fetchone()[0] > 0
+```
+
 ---
 
 ## Timeout Configuration

pyproject.toml

@@ -78,6 +78,7 @@ test = [
     # [binary] includes C extension + libpq, no system dependencies needed
     "psycopg[binary]>=3.1.0",
     "docker>=6.0.0",
+    "iris-devtester>=0.1.0",
     # Runtime dependencies needed when importing iris_pgwire modules in tests
     "sqlparse>=0.4.0",
     # Kerberos test realm isolation (constitutional TDD requirement - feature 024)

specs/033-devtester-skills/checklists/requirements.md

@@ -0,0 +1,42 @@
+# Specification Quality Checklist: IRIS DevTester Agentic Skills Integration
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2025-01-02
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Spec is ready for `/speckit.plan` phase
+- All clarifications resolved with reasonable defaults
+- 14 functional requirements defined covering:
+  - Dependency management (2 requirements)
+  - Container management (3 requirements)
+  - Connection management (3 requirements)
+  - Test data management (2 requirements)
+  - Troubleshooting (2 requirements)
+  - New functionality testing (2 requirements)

specs/033-devtester-skills/contracts/pytest-fixtures.md

@@ -0,0 +1,61 @@
+# Contract: IRIS DevTester Pytest Fixtures
+
+## Purpose
+This contract defines the public interface for the `pytest` fixtures provided by the `iris-devtester` integration.
+
+## Fixtures
+
+### 1. `iris_container`
+High-level fixture that ensures a healthy IRIS instance is available.
+
+- **Scope**: Session or Module
+- **Returns**: `iris_devtester.IRISContainer` object
+- **Responsibilities**:
+  - Pull image if missing.
+  - Start container.
+  - Wait for port 1972 to be ready.
+  - Disable password expiry.
+  - Enable CallIn service.
+  - Cleanup on teardown.
+
+### 2. `iris_connection`
+Provides a DBAPI connection with auto-remediation.
+
+- **Scope**: Function
+- **Depends on**: `iris_container`
+- **Returns**: `iris.dbapi.Connection`
+- **Responsibilities**:
+  - Auto-retry on transient failures.
+  - Handle "ChangePassword" requirement.
+  - Switch to requested namespace.
+
+### 3. `iris_fixture`
+Helper to load specific test data sets.
+
+- **Scope**: Function
+- **Usage**:
+  ```python
+  def test_vectors(iris_fixture):
+      iris_fixture.load("vectors_1024d.dat")
+      # ...
+  ```
+- **Responsibilities**:
+  - Load `.DAT` files via `FixtureCreator`.
+  - Validate schema before loading.
+  - Teardown (optional) - drop tables if requested.
+
+## Hooks
+
+### `pytest_runtest_makereport` (Failure Hook)
+- On `call.failed`, triggers the `/troubleshooting` skill logic.
+- Captures:
+  - IRIS connection status.
+  - Container health.
+  - Last few IRIS system log entries.
+- Outputs to: `test_failures.jsonl`
+
+## Configuration
+Controlled via `pytest` CLI or `pyproject.toml`:
+- `--iris-image`: Specify custom IRIS image.
+- `--iris-namespace`: Default namespace for connections.
+- `--iris-persist`: If True, don't stop container on teardown (for debugging).

specs/033-devtester-skills/plan.md

@@ -0,0 +1,65 @@
+# Implementation Plan: IRIS DevTester Agentic Skills Integration
+
+**Branch**: `033-devtester-skills` | **Date**: 2025-01-02 | **Spec**: specs/033-devtester-skills/spec.md
+**Input**: Feature specification from `/specs/033-devtester-skills/spec.md`
+
+## Summary
+
+Integrate `iris-devtester`'s agentic skills (slash commands) into the `iris-pgwire` testing workflow to automate container management, connection handling, and test data fixtures. This will replace manual `docker-compose` management with automated container lifecycle handling within `pytest` and provide auto-remediation for common IRIS/Docker issues.
+
+## Technical Context
+
+**Language/Version**: Python 3.11+
+**Primary Dependencies**: `iris-devtester`, `intersystems-irispython`, `psycopg[binary]`
+**Storage**: InterSystems IRIS (managed via Docker)
+**Testing**: `pytest`
+**Target Platform**: Docker-enabled environments
+**Project Type**: Python Library
+**Performance Goals**: Container startup/health check < 60s; troubleshooting < 5s
+**Constraints**: Must match constitutional principles; no manual container setup required for tests
+**Scale/Scope**: 14 Functional Requirements covering dependency, container, connection, data management, and troubleshooting
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+| Principle | Status | Justification |
+|-----------|--------|---------------|
+| I. Protocol Fidelity | ✅ PASS | Improves testing of PostgreSQL compatibility without changing protocol implementation. |
+| II. Test-First Development | ✅ PASS | Feature specifically enhances the testing infrastructure and reliability. |
+| III. Phased Implementation | ✅ PASS | Follows standard feature implementation lifecycle. |
+| IV. IRIS Integration | ✅ PASS | Leverages native IRIS integration patterns via `iris-devtester`. |
+| V. Production Readiness | ✅ PASS | Ensures test reliability and reduces setup time for new developers/CI. |
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/033-devtester-skills/
+├── plan.md              # This file
+├── research.md          # Phase 0 output
+├── quickstart.md        # Phase 1 output
+├── contracts/           # Phase 1 output
+└── tasks.md             # Phase 2 output (generated by /speckit.tasks)
+```
+
+### Source Code (repository root)
+
+```text
+src/iris_pgwire/
+├── tests/
+│   ├── conftest.py          # Update to use iris-devtester container management
+│   ├── test_devtester_integration.py # New tests for devtester skills
+
+tests/
+├── unit/
+├── integration/
+├── conftest.py              # Update to leverage new devtester skills
+```
+
+**Structure Decision**: Single project structure (Option 1). We will update existing `conftest.py` files to use `iris-devtester` and add integration tests for the new skills.
+
+## Complexity Tracking
+
+> **No violations detected.**

specs/033-devtester-skills/quickstart.md

@@ -0,0 +1,57 @@
+# Quickstart: Automated Testing with iris-devtester
+
+This guide shows how to leverage the new automated testing infrastructure in `iris-pgwire`.
+
+## Prerequisites
+1. **Docker Desktop** running.
+2. **Local iris-devtester**: Clone and install in editable mode.
+   ```bash
+   cd ..
+   git clone https://github.com/intersystems-community/iris-devtester.git
+   cd iris-devtester
+   pip install -e .
+   ```
+
+## Running Tests
+You no longer need to manually run `docker-compose up`. Simply run `pytest`:
+
+```bash
+# Run all tests (automatically starts IRIS)
+pytest
+
+# Run with specific IRIS image
+pytest --iris-image=intersystems/iris-community:2025.1.0
+
+# Run only integration tests
+pytest tests/integration/ -v
+```
+
+## Using the Agentic Skills (Slash Commands)
+If you are using **Claude Code**, you can invoke the skills directly:
+
+- **`/container`**: Manage your test container.
+- **`/connection`**: Debug your database connection.
+- **`/fixture`**: Load test data.
+- **`/troubleshooting`**: Diagnose test failures.
+
+## Writing a New Test
+The framework provides high-level fixtures:
+
+```python
+def test_my_new_feature(iris_connection):
+    # iris_connection is already connected and ready
+    with iris_connection.cursor() as cursor:
+        cursor.execute("SELECT 1")
+        assert cursor.fetchone()[0] == 1
+
+def test_with_data(iris_fixture, iris_connection):
+    # Load specific data set
+    iris_fixture.load("healthcare_data.dat")
+    
+    with iris_connection.cursor() as cursor:
+        cursor.execute("SELECT COUNT(*) FROM Patients")
+        assert cursor.fetchone()[0] > 0
+```
+
+## Troubleshooting Failures
+On failure, check `test_failures.jsonl` in the project root for detailed diagnostics and remediation steps.