ComfyUI-Manager/reports/scenario_effects.md

# Scenario × Functional Effect Mapping

**Generated**: 2026-04-18
**Definition of "effect"**: The actual **functional purpose** of the feature — not just any side effect. A scenario is verified only when the intended outcome is observably achieved.

| Pattern | Effect definition |
|---|---|
| Success scenario | The feature's PURPOSE is fulfilled and observable |
| Validation/security error | The purpose is NOT fulfilled + correct rejection signal |
| State edge case | The purpose is correctly short-circuited or no-op |

Unless specified, status code alone is NOT sufficient evidence of effect.

---

# Section 1 — Glob v2 Endpoints

## 1.1 Queue Management (Install/Uninstall/Update/Fix/Disable/Enable/Model)

### POST /v2/manager/queue/task (kind=install)

Purpose: **install a custom node pack so it becomes loadable by ComfyUI**.

| Scenario | Functional effect to verify |
|---|---|
| Success (CNR pack) | (a) pack directory exists under `custom_nodes/`, (b) `.tracking` file present (CNR marker), (c) pack appears in GET `customnode/installed` with correct cnr_id + version, (d) worker `task_worker_lock` released after completion |
| Success (nightly/URL) | (a) pack directory exists, (b) `.git` subdir present (git clone), (c) repo remote matches requested URL, (d) appears in installed list |
| Success (skip_post_install + already disabled) | Pack moved from `.disabled/` back to active (enable shortcut), NOT a fresh install |
| Validation error (bad `kind` value) | Task NOT queued (queue/status unchanged), queue/history does not contain this ui_id, pack NOT installed |
| Validation error (missing ui_id/client_id) | Same: no queued task, no installation side-effect |
| Worker auto-start | After task queued, `queue/status.is_processing=true` and eventually `done_count` increments |

### POST /v2/manager/queue/task (kind=uninstall)

Purpose: **remove an installed pack so it is no longer loaded**.

| Scenario | Effect to verify |
|---|---|
| Success | Pack directory no longer exists under `custom_nodes/`, pack absent from `customnode/installed`, no import error on next ComfyUI reload |
| Target not installed | No-op or error — purpose already satisfied; no state change |
| Unknown pack | No filesystem change |

### POST /v2/manager/queue/task (kind=update)

Purpose: **update an installed pack to a newer version**.

| Scenario | Effect to verify |
|---|---|
| Success | (a) pack directory still exists, (b) version actually changed (check `.tracking` content or pyproject version), (c) dependencies refreshed, (d) still loadable by ComfyUI |
| Already up-to-date | No-op or confirmatory response; no downgrade |
| Unknown pack / Update fails | No partial state (pack not removed nor corrupted) |

### POST /v2/manager/queue/task (kind=fix)

Purpose: **re-install dependencies of an existing pack without changing source**.

| Scenario | Effect to verify |
|---|---|
| Success | (a) pack directory unchanged (same HEAD/version), (b) dependencies present in venv after fix, (c) pack import succeeds on reload |
| Missing dependencies pre-fix | After fix, imports succeed |

### POST /v2/manager/queue/task (kind=disable)

Purpose: **stop loading a pack without removing it, reversibly**.

| Scenario | Effect to verify |
|---|---|
| Success | (a) pack moved from `custom_nodes/<name>/` to `custom_nodes/.disabled/<name>/`, (b) on next ComfyUI reload, pack nodes NOT registered, (c) pack absent from `customnode/installed` (active) |
| Already disabled | No-op; still in `.disabled/` |

### POST /v2/manager/queue/task (kind=enable)

Purpose: **restore a disabled pack to active, loadable state**.

| Scenario | Effect to verify |
|---|---|
| Success | (a) pack restored from `.disabled/` to active `custom_nodes/` (may be case-normalized CNR name), (b) on reload, nodes registered again, (c) appears in `customnode/installed` |
| Not disabled (already active) | No-op; no regression |

### POST /v2/manager/queue/install_model

Purpose: **download a model file to the appropriate models/ subdirectory**.

| Scenario | Effect to verify |
|---|---|
| Success | (a) task queued (queue/status reflects), (b) eventually file downloaded to `models/<type>/<filename>`, (c) file size > 0, (d) visible via `externalmodel/getlist` with `installed=True` (legacy) |
| Missing client_id/ui_id | Task NOT queued; no download attempted |
| Invalid metadata | Task NOT queued |
| Not in whitelist (legacy check) | Download rejected; no file written |
| Non-safetensors + security<high+ | Rejected; no file written |

### POST /v2/manager/queue/update_all

Purpose: **queue update tasks for ALL currently active packs**.

| Scenario | Effect to verify |
|---|---|
| Success | queue/status.pending_count == N where N = (active_nodes + unknown_active_nodes - manager-skip). Each queued task has correct `kind=update` + correct `node_name` |
| Security denied (<middle+) | 403; NO tasks queued; queue/status unchanged |
| Missing params | 400; NO tasks queued |
| mode=local | No remote fetch; uses local channel data |
| Desktop build | `comfyui-manager` pack NOT in queued tasks |

### POST /v2/manager/queue/update_comfyui

Purpose: **queue a self-update task for ComfyUI core**.

| Scenario | Effect to verify |
|---|---|
| Success | (a) queue/status.total_count increased by 1, (b) the queued task has `kind=update-comfyui` with `params.is_stable` matching request/config |
| Missing params | 400; no task queued |
| stable=true overrides config | Task params.is_stable==True regardless of config policy |

### POST /v2/manager/queue/reset

Purpose: **clear all queued/running/history tasks**.

| Scenario | Effect to verify |
|---|---|
| Success | queue/status: total_count=0, done_count=0, pending_count=0, in_progress_count=0, is_processing=false |
| Already empty | Same; idempotent |

### POST /v2/manager/queue/start

Purpose: **start the worker thread to process queued tasks**.

| Scenario | Effect to verify |
|---|---|
| Worker not running | queue/status.is_processing becomes true (may be momentary if queue empty); tasks transition pending → running → done |
| Already running | 201; is_processing remains true; no duplicate worker spawned |
| Empty queue | Worker starts and idles; no errors |

### GET /v2/manager/queue/status

Purpose: **accurately reflect the current queue state**.

| Scenario | Effect to verify |
|---|---|
| No filter | Counts match actual internal queue state (cross-check via known queued tasks) |
| With client_id filter | client_id echo + filtered counts correspond to only that client's tasks |
| Fields shape | total/done/in_progress/pending/is_processing all present + correct types |

### GET /v2/manager/queue/history

Purpose: **retrieve completed task records for introspection**.

| Scenario | Effect to verify |
|---|---|
| id=<batch_id> query | Returns JSON content of that batch file (not another's) |
| Path traversal | file read DOES NOT occur; returns 400 |
| ui_id filter | Returns the matching single task record |
| client_id filter | Returns only that client's history |
| Pagination | Result size ≤ max_items |
| Serialization limitation | If 400 returned, server didn't crash; no corrupted state |

### GET /v2/manager/queue/history_list

Purpose: **list available batch history file IDs**.

| Scenario | Effect to verify |
|---|---|
| Success | Returned `ids` ⊆ files in `manager_batch_history_path` (mtime-desc sorted) |
| Empty | ids=[] reflects empty dir |

## 1.2 Custom Node Info

### GET /v2/customnode/getmappings

Purpose: **provide node→pack mapping for the UI to resolve missing nodes**.

| Scenario | Effect to verify |
|---|---|
| Success mode=local/cache/remote | Returned dict: values are `[node_list, metadata]`, all currently-loaded `NODE_CLASS_MAPPINGS` either present in a node_list OR matched by `nodename_pattern` regex |
| mode=nickname | Nicknames filter applied (each entry has nickname field) |
| Missing mode query | 500/KeyError; no partial data returned |

### GET /v2/customnode/fetch_updates (deprecated)

Purpose: **(deprecated) was previously used to fetch git updates**.

| Scenario | Effect to verify |
|---|---|
| Always | 410 + `{deprecated: true}`. No git fetch performed (no disk I/O on .git dirs) |

### GET /v2/customnode/installed

Purpose: **list currently-installed packs with metadata for the UI**.

| Scenario | Effect to verify |
|---|---|
| mode=default | Dict reflects real filesystem scan of `custom_nodes/`: every dir with proper marker appears |
| mode=imported | Returns snapshot frozen at startup (unchanged after runtime installs) — proves stability |
| Newly installed pack | After install, default mode reflects it; imported mode does NOT |

### POST /v2/customnode/import_fail_info

Purpose: **return detailed traceback/message for a pack that failed to import at startup**.

| Scenario | Effect to verify |
|---|---|
| Known failed pack via cnr_id | 200 + body has `msg` + `traceback` matching `cm_global.error_dict[module]` |
| Known failed via url | Same |
| Unknown pack | 400 (no info); `error_dict` NOT mutated |
| Missing fields / non-dict | 400 with appropriate text |

### POST /v2/customnode/import_fail_info_bulk

Purpose: **same as above but for multiple packs in one call**.

| Scenario | Effect to verify |
|---|---|
| cnr_ids list | Each key maps to either {error, traceback} (if failed) or null (if no failure). Unknown cnr_ids → null |
| urls list | Same semantics |
| Empty lists | 400 |
| Mixed types inside list | 400 or skip with per-item error |

## 1.3 Snapshots

### GET /v2/snapshot/get_current

Purpose: **capture and return the current system state (not persist it)**.

| Scenario | Effect to verify |
|---|---|
| Success | Returned dict contains `comfyui` (hash/tag), `git_custom_nodes` (list), `cnr_custom_nodes` (list), `pips`. Consistent with actual installed state |

### POST /v2/snapshot/save

Purpose: **persist current system state so it can be restored later**.

| Scenario | Effect to verify |
|---|---|
| Success | (a) new file created in `manager_snapshot_path` with timestamped name, (b) file content == get_current() at save time, (c) appears in `snapshot/getlist.items` |

### GET /v2/snapshot/getlist

Purpose: **list saved snapshots for UI selection**.

| Scenario | Effect to verify |
|---|---|
| Success | items list matches .json files in snapshot dir (without extension), sorted desc |
| After save | New snapshot name appears at top |
| After remove | Removed name absent |

### POST /v2/snapshot/remove

Purpose: **delete a saved snapshot permanently**.

| Scenario | Effect to verify |
|---|---|
| Success | File removed from disk; absent from getlist |
| Nonexistent target | No change; 200 (no-op) |
| Path traversal | File NOT removed; 400; any other files untouched |
| Security denied | File NOT removed; 403 |

### POST /v2/snapshot/restore

Purpose: **schedule a snapshot to be applied on next server restart** (the actual restore happens at startup).

| Scenario | Effect to verify |
|---|---|
| Success | `restore-snapshot.json` copied to `manager_startup_script_path`. Next reboot → actual state reverts to snapshot (verifiable by reboot + get_current comparison) |
| Nonexistent target | No marker file created; 400 |
| Path traversal | No file operations; 400 |
| Security denied | No marker file; 403 |

## 1.4 Configuration

### GET /v2/manager/db_mode

Purpose: **return current DB source mode config**.

| Scenario | Effect to verify |
|---|---|
| Success | Returned text == `core.get_config()["db_mode"]` value in `config.ini` |

### POST /v2/manager/db_mode

Purpose: **persist new DB mode to config.ini**.

| Scenario | Effect to verify |
|---|---|
| Valid value | (a) config.ini written to disk with new value, (b) GET returns new value, (c) survives process restart |
| Malformed JSON / missing value | 400; config.ini UNCHANGED |

### GET/POST /v2/manager/policy/update

Purpose: **read/persist update policy (stable vs nightly)**.

Same verification pattern as db_mode but for `update_policy` key.

### GET /v2/manager/channel_url_list

Purpose: **return available channels + currently selected**.

| Scenario | Effect to verify |
|---|---|
| Success | `selected` matches channel whose URL == config.channel_url (else "custom"); `list` is all known channels as "name::url" |

### POST /v2/manager/channel_url_list

Purpose: **switch active channel by name**.

| Scenario | Effect to verify |
|---|---|
| Known name | config.channel_url written with new URL; GET.selected matches new name |
| Unknown name | Silent no-op; 200; channel_url UNCHANGED (verify) |
| Malformed | 400; channel_url UNCHANGED |

## 1.5 System

### GET /v2/manager/is_legacy_manager_ui

Purpose: **let UI know which Manager UI (legacy vs current) to load**.

| Scenario | Effect to verify |
|---|---|
| Success | `is_legacy_manager_ui` matches the CLI flag `--enable-manager-legacy-ui` that was passed |

### GET /v2/manager/version

Purpose: **report the Manager package version**.

| Scenario | Effect to verify |
|---|---|
| Success | Text == core.version_str (non-empty, semver-ish) |
| Idempotent | Consecutive calls return identical value |

### POST /v2/manager/reboot

Purpose: **restart the server process**.

| Scenario | Effect to verify |
|---|---|
| Success | (a) server process actually exits, (b) new process binds same port, (c) new process serves requests, (d) pre-reboot state preserved (version, config) |
| CLI session mode | `.reboot` marker file created before exit(0); process-manager restarts |
| Security denied | 403; process continues (no restart) |

### GET /v2/comfyui_manager/comfyui_versions

Purpose: **enumerate available ComfyUI versions + current**.

| Scenario | Effect to verify |
|---|---|
| Success | `current` is a git tag/hash present in `.git` log; `versions` array non-empty; current ∈ versions |
| Git failure | 400; no partial response |

### POST /v2/comfyui_manager/comfyui_switch_version

Purpose: **queue a task to switch ComfyUI to a target version (actual switch happens via worker)**.

| Scenario | Effect to verify |
|---|---|
| Success | (a) task queued with `params.target_version=<ver>`, (b) queue/status reflects, (c) eventually `.git` HEAD points at target commit/tag after worker runs |
| Missing params | 400; no task queued |
| Security denied (<high+) | 403; no task queued |

---

# Section 2 — Legacy-only Endpoints (UI → effect)

For these, the functional purpose is triggered by UI interaction. The effect MUST be observable both through the UI (state transitions, renders) AND/OR through the backend (filesystem, queue state).

### POST /v2/manager/queue/batch (legacy)

Purpose: **accept one aggregated request to enqueue multiple operations, then start the worker**.

| Scenario | Effect to verify |
|---|---|
| install item(s) | Each pack installed (filesystem effect); `failed` list only contains actually-failed ids |
| uninstall item(s) | Each pack removed |
| update item(s) | Packs updated (version change verifiable) |
| reinstall item(s) | Pack removed then re-installed (dir exists, .tracking present) |
| disable | Pack in `.disabled/` |
| install_model | Model file downloaded |
| fix | Dependencies re-resolved |
| update_comfyui | ComfyUI update task queued |
| update_all | All active pack updates queued |
| Mixed kinds | Each kind's effect achieved; `failed` contains only real failures |

### GET /v2/customnode/getlist (legacy)

Purpose: **feed the Custom Nodes Manager dialog with the list of available + installed packs**.

| Scenario | Effect to verify |
|---|---|
| Success | Response has `channel` + `node_packs`; each pack includes install state (installed/disabled), stars (github-stats), update availability (if skip_update=false) |
| skip_update=true | No git fetch performed (check timing / no remote calls) |
| Channel resolution | Maps URL back to name (default/custom/etc.) |

### GET /customnode/alternatives (legacy)

Purpose: **show alternative pack recommendations for a given pack**.

| Scenario | Effect to verify |
|---|---|
| Success | Response dict keyed by unified pack id; values from `alter-list.json` with markdown processed |

### GET /v2/externalmodel/getlist (legacy)

Purpose: **list available external models with install state for Model Manager dialog**.

| Scenario | Effect to verify |
|---|---|
| Success | Each model entry has `installed` ∈ {'True','False'}; True ⟺ file actually exists under appropriate models subdir |
| HuggingFace sentinel | Filename resolved from URL basename; installed flag correct |
| Custom save_path | Path resolved correctly |

### GET /v2/customnode/versions/{node_name} (legacy)

Purpose: **list all versions of a CNR pack for the user to pick**.

| Scenario | Effect to verify |
|---|---|
| Known CNR pack | Response array lists all available versions (latest first, typically) matches CNR registry |
| Unknown pack | 400; no partial data |

### GET /v2/customnode/disabled_versions/{node_name} (legacy)

Purpose: **list versions of a pack currently in the disabled state for possible re-enable**.

| Scenario | Effect to verify |
|---|---|
| Has disabled versions | Response array matches actual `cnr_inactive_nodes[node]` keys + "nightly" if in `nightly_inactive_nodes` |
| None disabled | 400 |

### POST /v2/customnode/install/git_url (legacy)

Purpose: **clone a pack from arbitrary git URL (dangerous; requires high+)**.

| Scenario | Effect to verify |
|---|---|
| Success | Repo cloned into `custom_nodes/`, `.git` dir present, repo remote matches URL |
| Already installed | 200 skip; no duplicate; no overwrite |
| Clone failure | 400; no partial dir left behind |
| Security denied (<high+) | 403; no filesystem change |

### POST /v2/customnode/install/pip (legacy)

Purpose: **run `pip install <packages>` in the venv**.

| Scenario | Effect to verify |
|---|---|
| Success | Packages are importable from the venv Python afterwards (or `pip list` shows them) |
| Security denied (<high+) | 403; no pip invocation |

### GET /v2/manager/notice (legacy)

Purpose: **fetch the News wiki content and augment with version footer**.

| Scenario | Effect to verify |
|---|---|
| GitHub reachable | HTML returned; contains markdown-body content + ComfyUI/Manager version footer appended |
| GitHub unreachable | "Unable to retrieve Notice"; no crash |
| Non-git ComfyUI | Response starts with "Your ComfyUI isn't git repo" warning |
| Outdated ComfyUI | Response starts with "too OUTDATED!!!" warning |
| Desktop variant | Footer uses `__COMFYUI_DESKTOP_VERSION__` instead of commit hash |

---

# Section 3 — UI→effect Mapping (Legacy)

For Playwright tests, the "UI→effect" contract requires:

| UI action | Target endpoint | Effect to verify |
|---|---|---|
| Click Manager menu button | (none — UI only) | `#cm-manager-dialog` visible |
| Click "Custom Nodes Manager" menu item | GET customnode/getlist + getmappings | `#cn-manager-dialog` + grid populated (rows > 0) |
| Click "Model Manager" menu item | GET externalmodel/getlist | `#cmm-manager-dialog` + grid populated |
| Click "Snapshot Manager" menu item | GET snapshot/getlist | `#snapshot-manager-dialog` + list populated |
| Click "Install" on a pack row | GET customnode/versions/{id} → POST queue/batch (install) → WebSocket cm-queue-status | Pack dir exists on disk + row shows "Installed" state in UI + WebSocket `all-done` received |
| Click "Uninstall" on installed row | POST queue/batch (uninstall) | Pack dir removed + row state updates to "Not Installed" |
| Click "Disable" on row | POST queue/batch (disable) | Pack in `.disabled/` + row state "Disabled" |
| Click "Update" on outdated row | POST queue/batch (update) | Pack version changes + row state update |
| Click "Fix" on row | POST queue/batch (fix) | Dependencies restored |
| Click "Try alternatives" | GET /customnode/alternatives | Alternatives list rendered |
| Open "Versions" dropdown on row | GET customnode/versions/{id} | Version list rendered in UI |
| Open "Disabled Versions" on row | GET customnode/disabled_versions/{id} | Disabled versions rendered |
| Click "Install via Git URL" button + enter URL + confirm | POST customnode/install/git_url | Pack cloned; dir visible in UI |
| Click "Install via pip" | POST customnode/install/pip | Package installed; no UI crash |
| Click "Install" on Model Manager row | POST queue/install_model | Model file downloaded; row state "Installed" |
| Change DB mode dropdown | POST db_mode | Config persisted; dropdown value persists after dialog reopen |
| Change Update Policy dropdown | POST policy/update | Same |
| Change Channel dropdown | POST channel_url_list | Same |
| Click "Update All" button | POST queue/update_all | Multiple tasks queued; progress indicator shows count |
| Click "Update ComfyUI" button | POST queue/update_comfyui | Task queued; status indicator |
| Click "Save Snapshot" in Snapshot Manager | POST snapshot/save | New row in dialog list with timestamp |
| Click "Remove" on snapshot row | POST snapshot/remove?target=X | Row disappears from list |
| Click "Restore" on snapshot row | POST snapshot/restore?target=X | Marker file created; next reboot applies |
| Click "Restart" button | POST manager/reboot | Server restarts; UI reconnects |
| Open Manager menu with pending News | GET manager/notice | News panel visible with HTML content |
| Filter/search in grid | (client-side) | Row count ≤ initial count |
| Close dialog (X button / Esc) | (none) | Dialog hidden; no leaked DOM |

---

# Section 4 — Effects Not Easily Observable

Some purposes can only be proven via side-channel observation:

| Endpoint | Purpose | Why hard to verify |
|---|---|---|
| POST snapshot/restore | Apply snapshot at next reboot | Must actually reboot + compare post-state; destructive |
| POST switch_version (positive) | Change ComfyUI version | Destructive; needs rollback |
| POST manager/reboot | Restart process | Hard to assert "new process" vs "same process" cleanly; proxy: pid change or connection drop+rebind |
| POST queue/start → worker runs | Tasks execute | Timing-dependent; must poll done_count |
| GET manager/notice | Content from GitHub | External dependency; flaky |
| POST install (network) | Actually installs | Depends on CNR/GitHub availability |
| POST install_model (download) | File downloaded | Slow; large files; fake whitelist URL returns quick 404 |

For these, tests either (a) accept destructive as out-of-scope, (b) use timing/polling, or (c) mock at minimum granularity.

---
*End of Scenario × Effect Mapping*