iris-devtester
/iris-devtester
Use when writing tests that need a live IRIS container, using IRISContainer factory methods, debugging connection failures, or understanding the password reset story. Covers iris-devtester 1.18.0+ patterns: CPF-first password strategy, factory methods, gotchas, and the full connection flow.
- Author
- intersystems-community ↗
- Repository
- iris-agentic-dev ↗
- Licence
- MIT
- Last repository change
- 25.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when writing tests that need a live IRIS container, using IRISContainer factory methods, debugging connection failures, or understanding the password reset story. Covers iris-devtester 1.18.0+ patterns: CPF-first password strategy, factory methods, gotchas, and the full connection flow.
Original author description
Use when writing tests that need a live IRIS container, using IRISContainer factory methods, debugging connection failures, or understanding the password reset story. Covers iris-devtester 1.18.0+ patterns: CPF-first password strategy, factory methods, gotchas, and the full connection flow.
How it works
- HARD GATE — Common Mistakes
- Factory Methods
- Password Strategy (1.18.0+) — CPF-First
- Connection Flow
- Diagnostic Tools (1.16.0+)
- Public Exports
- pytest Fixtures
- CLI (idt)
- Gotchas
SKILL.md preview
---
name: iris-devtester
tier: extra
description: >
Use when writing tests that need a live IRIS container, using IRISContainer
factory methods, debugging connection failures, or understanding the password
reset story. Covers iris-devtester 1.18.0+ patterns: CPF-first password
strategy, factory methods, gotchas, and the full connection flow.
tags: [iris, devtester, testing, docker, python, password, connection]
---
# iris-devtester — Container Testing Toolkit
**PyPI**: `pip install iris-devtester>=1.18.0`
**Repo**: `github.com/intersystems-community/iris-devtester`
---
## HARD GATE — Common Mistakes
- **DO NOT** call `unexpire_all_passwords()` proactively in `get_connection()` — 1.18.0 is CPF-first; docker exec only fires as fallback
- **DO NOT** connect as `localhost` on macOS — use `127.0.0.1` (IPv6 resolution bug)
- **DO NOT** use `IRISContainer(); iris.start()` — always `with IRISContainer.community() as iris:`
- **DO NOT** hardcode ports — use `iris.get_mapped_port(1972)`
- **DO NOT** bind-mount host directories on Linux without fixing uid 51773 — see `iris-linux-docker` skill
---
## Factory Methods
```python
from iris_devtester import IRISContainer
# Community — default, auto-detects ARM64 vs x86
with IRISContainer.community() as iris:
conn = iris.get_connection()
# Light — CI/CD, 580MB, no web server
with IRISContainer.light() as iris: ...
# Enterprise — needs IRIS_LICENSE_KEY env var or license_key= kwarg
with IRISContainer.enterprise(license_key="~/iris.key") as iris: ...
# Health — irishealth-community + FHIR R4 pre-installed (see irishealth-container skill)
with IRISContainer.health() as iris:
h = iris.fhir_health_check()
# AI Hub — %AI.Agent, VECTOR SQL, ISC internal registry (see irishealth-container skill)
with IRISContainer.ai_hub(build="159") as iris: ...
# Attach — reconnect to existing container (e.g. started by idt container up)
iris = IRISContainer.attach("container-name")
conn = iris.get_connection()
```
---
## Password Strategy (1.18.0+) — CPF-First
**How it works:**
1. `start()` injects `CPFPreset.SECURE_DEFAULTS` via `ISC_CPF_MERGE_FILE` — sets `ChangePassword=0` for `_SYSTEM` and `SuperUser` **before IRIS opens connections**. No `docker exec` needed.
2. `get_connection()` tries `iris.connect()` directly (optimistic).
3. If that fails with a password-change error AND `_password_handled` is False → calls `unexpire_all_passwords()` once (docker exec fallback) → retries.
4. `_password_handled = True` prevents double-remediation.
**What this means:**
- Happy path: zero `docker exec` calls. Works in restricted CI environments.
- Fallback path: one `docker exec` on `attach()` containers or existing containers.
**Manual escape hatches:**
```bash
idt test-connection --auto-fix # detect + reset + retry
idt container reset-password <name> --timeout 30
```
```python
from iris_devtester.utils import reset_password_if_needed
reset_password_if_needed(e, container_name="iris_db", username="_SYSTEM")
```
---
## Connection Flow
```text
IRISContainer.community().__enter__()
→ start()
→ with_cpf_merge(SECURE_DEFAULTS) # ChangePassword=0 via ISC_CPF_MERGE_FILE
→ super().start() # IRIS reads CPF, opens port 1972
→ _password_handled = True
iris.get_connection()
→ enable_callin_service() # docker exec once
→ get_connection(config) # iris.connect() — optimistic
→ on ChangePassword error:
unexpire_all_passwords() # fallback, once
retry iris.connect()
```
---
## Diagnostic Tools (1.16.0+)
```python
from iris_devtester import probe_connection, ContainerHealth, ConnectionProbe
# Inspect connection state (schemas, IRIS version, latency)
result = probe_connection(conn)
print(result.report())
# Health check from container (includes schema visibility)
health = iris.health_check()
print(health.tables_visible) # False if schema not seeded
print(health.report())
```
`ConnectionDiagnosticError` wraps SQLCODE -30 (table not found) and -23 (CTE scoping) with schema visibility context and suggested fix. Raised automatically — no call-site changes needed.
---
## Public Exports
```python
from iris_devtester import (
IRISContainer,
get_connection,
probe_connection,
ContainerHealth,
ConnectionProbe,
ConnectionDiagnosticError,
IRISConfig,
)
```
---
## pytest Fixtures
```python
def test_example(iris_db): # function-scoped, fresh container
def test_example(iris_db_shared): # module-scoped, shared container
def test_example(iris_container): # raw IRISContainer access
```
---
## CLI (idt)
```bash
idt container up --port 11972 # exact port mapping
idt container up --auto-port # auto-assign from 1972-2000
idt container exec iris_db --objectscript "Write $ZVERSION"
idt container reset-password iris_db --timeout 30
idt test-connection --container iris_db --auto-fix -v
idt fixture load --name my-data
```
---
## Gotchas
**Ryuk kills containers on process exit** — use `idt container up` + `IRISContainer.attach()` for persistent containers. See `containers/AGENTS.md`.
**No web server on enterprise irishealth** — `irishealth:2026.2.0AI.*` and `iris:XXXX` (enterprise) have `WebServer=0`. Port 1972 only. A webgateway CANNOT substitute — it proxies CSP protocol to the superserver, not Atelier REST. Use `irishealth-community` or `iris-community` for VSCode/Atelier access. See `irishealth-container` skill.
**`%AI.*` classes in read-only irislib** — cannot transplant to community image. Two-container split is correct.
**DinD port mapping** — `get_mapped_port(52773)` raises `ConnectionError` inside CI containers. Fixed in 1.15.1: falls back to internal port. Set `TC_HOST=<ip>` to override.
Versions
The database has no other skills named iris-devtester.
Database snapshot: 13.11.2026 · package version c67178bea078 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100iris-cpf-merge
Use when configuring IRIS containers via CPF merge files (ISC_CPF_MERGE_FILE). Covers CPFPreset patterns, the grongierisc template pattern, how to set a password at first boot (and why a merge line cannot do it safely), and common CPF merge mistakes. Load when: setting up IRIS… - 100irishealth-container
Use when working with irishealth-community (FHIR R4) or irishealth AI Hub containers, OR when setting up VSCode/iris-dev extension against any IRIS container. Covers IRISContainer.health() and ai_hub() factory methods, four hard-won gotchas, the two-container architecture,… - 100iris-ecs
Designs, writes, debugs, and tests applications built on iris-ecs, the Entity Component System for TypeScript. Use when code imports iris-ecs, or when the user plans or changes an Iris ECS feature: choosing its domain, modeling data with defineComponent and Type schemas, tags,… - 100add-redis-iris
Add Redis Iris to an existing AI agent in any framework (LangGraph, LangChain, OpenAI Agents SDK, Google ADK, Pydantic AI, CrewAI, or a plain loop). Use when the user asks to add Iris, Redis Agent Memory, Agent Playbooks, Context Gateway, Intent Router, or Lens to their agent,… - 95testng-data-driven
Use when implementing data-driven tests with TestNG DataProviders, factory methods, and parameterization patterns. - 100email-and-password-best-practices
Configure email verification, implement password reset flows, set password policies, and customise hashing algorithms for Better Auth email/password authentication. Use when users need to set up login, sign-in, sign-up, credential authentication, or password security with Better Auth.