Skip to content
Skills Library
Programming · Testing

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.

Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

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

  1. HARD GATE — Common Mistakes
  2. Factory Methods
  3. Password Strategy (1.18.0+) — CPF-First
  4. Connection Flow
  5. Diagnostic Tools (1.16.0+)
  6. Public Exports
  7. pytest Fixtures
  8. CLI (idt)
  9. Gotchas
Original SKILL.md headings · 162 lines, 623 words
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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.