PSA/ee/docs/plans/2026-01-01-workflow-e2e-ticket-comment/PRD.md

PRD — Workflow E2E: Ticket Created → Add Comment

• Slug: workflow-e2e-ticket-comment
• Date: 2026-01-01
• Status: Draft

Summary

Add a Playwright integration test that validates a very basic workflow runs end-to-end with the v2 workflow runtime + worker:

1. A user creates a new workflow in Automation Hub / Designer.
2. The workflow is triggered by the TICKET_CREATED event.
3. The workflow runs one action: tickets.add_comment with body hello from workflow.
4. The test creates a new ticket to trigger the event.
5. The test asserts:
   • A comment is added to the created ticket.
   • A workflow run record exists and completes successfully.

This is intended as a “canary” test proving the workflow engine is wired correctly (UI → persistence → event ingestion → worker execution → business side effect).

Problem

We currently lack an automated, end-to-end regression test proving:

• workflow definitions created in the UI can be activated,
• runtime events are emitted on real application actions (ticket creation),
• the worker consumes events and executes workflow logic,
• the workflow produces a real side effect (ticket comment).

Without this, workflow/runtime regressions are easy to introduce and hard to diagnose.

Goals

1. Verify the workflow worker/runtime processes a real TICKET_CREATED event.
2. Verify the runtime executes tickets.add_comment correctly.
3. Verify the user-auth/tenant scoping is correct (comment created under the tenant that created the ticket).
4. Make the test deterministic and debuggable (clear assertions + DB verification).

Non-goals

• Exhaustive coverage of designer capabilities.
• Testing workflow waits, retries, or complex branching.
• Validating event catalog simulation flows.

Users and Primary Flows

Persona

• Internal Admin user configuring workflows.

Primary flow (under test)

1. Navigate to Automation Hub → Workflows/Designer.
2. Create a new workflow.
3. Select trigger event: TICKET_CREATED.
4. Add action step: “Add Ticket Comment”.
5. Publish/activate workflow.
6. Create a new ticket.
7. Observe the workflow run and comment side effect.

UX / UI Notes

The test will need stable selectors for:

• Automation Hub navigation (top-row tabs: Workflows, Designer, Runs, Event Catalog)
• “Create workflow” affordance
• Trigger event picker (select TICKET_CREATED)
• Action library selection (select tickets.add_comment)
• Input mapping UI (map ticket_id from trigger payload, set body)
• Publish/activate workflow
• Ticket creation UI (fill required fields)
• Ticket detail page comment timeline/list

If selectors are missing or unstable, add data-automation-id attributes to critical controls rather than relying on text-only locators.

Requirements

Functional Requirements

1. The test can create a new workflow in the designer and persist it.
2. The workflow can be activated/published and becomes eligible to run.
3. Creating a ticket publishes TICKET_CREATED with a payload that includes ticketId.
4. The worker consumes the event and starts a workflow run.
5. The workflow executes tickets.add_comment and writes a comment to the comments table for that ticket.
6. The UI shows the “hello from workflow” comment on the ticket.

Implementation Outline

Playwright test skeleton

• Test location: ee/server/src/__tests__/integration/workflow-ticket-created-add-comment.playwright.test.ts
• Follow the established helpers/patterns:
  • applyPlaywrightAuthEnvDefaults()
  • createTestDbConnection()
  • createTenantAndLogin(db, page, ...)
  • resolvePlaywrightBaseUrl()
• Use DB-backed polling helpers in the test to wait for:
  • the workflow comment row to appear in comments
  • the corresponding workflow_runs row to reach a terminal success status

Worker/runtime dependency

The Playwright run must include a live workflow worker connected to the same DB/Redis as the dev server:

• Preferred: start/stop a dockerized worker from Playwright global setup/teardown (mirrors existing MinIO setup).
• Alternative: start a host process in parallel with npm run dev.

Non-functional Requirements

1. Determinism: The test avoids race conditions by waiting on a DB-backed condition (comment row / workflow run state), not only UI timing.
2. Debuggability: On failure, capture:
   • screenshot/video (Playwright defaults)
   • workflow id + run id (from DB query)
   • worker logs location/command to tail
3. Isolation: The test runs against a dedicated Playwright database and does not rely on pre-existing workflows.

Data / API / Integrations

Relevant tables (expected)

• workflow_definitions, workflow_definition_versions
• workflow_runtime_events
• workflow_runs, workflow_action_invocations
• tickets, comments

Key runtime entities

• Trigger event type: TICKET_CREATED
• Action: tickets.add_comment (v1)

Security / Permissions

• Test tenant must have sufficient permissions to:
  • manage workflows (create/publish/activate)
  • create tickets
  • update tickets (add comments) via workflow action execution context

Observability

Test assertions should include DB queries proving:

• event record exists in workflow_runtime_events for TICKET_CREATED
• run record exists in workflow_runs and transitions to a terminal success state
• comment row exists in comments with note = "hello from workflow"

Rollout / Migration

None. This is a test + minor infra wiring (starting the worker for Playwright).

Test Environment Setup (Local)

This plan assumes a repeatable Playwright dependency stack is available:

• Postgres (reachable from host at PLAYWRIGHT_DB_HOST:PLAYWRIGHT_DB_PORT)
• Redis (reachable from host at REDIS_HOST:REDIS_PORT)
• Workflow worker connected to the same Postgres + Redis

To avoid conflicts with other worktrees, use the alga-test-env-setup port detection + secrets generation:

1. Detect a free port set (example env number 2):
   • python3 /Users/roberisaacs/.codex/skills/alga-test-env-setup/scripts/detect_ports.py --env-num 2
2. Generate dedicated secrets (recommended: keep separate from developer secrets):
   • python3 /Users/roberisaacs/.codex/skills/alga-test-env-setup/scripts/generate_secrets.py --secrets-dir ./secrets-playwright --force
3. Start dependency containers using the detected ports (implementation choice):
   • Option A: create a dedicated docker-compose.playwright-deps.yml (postgres + redis + worker) and start/stop it from Playwright global setup/teardown.
   • Option B: reuse an existing e2e compose (e.g. docker-compose.e2e-with-worker.yaml) but parameterize ports via env.

Playwright must be pointed at these ports via env vars:

• PLAYWRIGHT_DB_HOST, PLAYWRIGHT_DB_PORT, PLAYWRIGHT_DB_NAME
• PLAYWRIGHT_DB_ADMIN_PASSWORD and PLAYWRIGHT_DB_APP_PASSWORD (can point at /run/secrets/<name>; bootstrap resolves to ./secrets/<name>)
• REDIS_HOST, REDIS_PORT (+ REDIS_PASSWORD if required)

Open Questions

1. What is the canonical Automation Hub route path for:
   • workflows list
   • designer “new workflow” mode
2. What are the stable data-automation-id selectors for:
   • event trigger picker
   • adding an action from the action library
   • mapping trigger payload → action inputs
3. What is the authoritative terminal success status in workflow_runs.status (e.g., SUCCEEDED vs COMPLETED)?
4. How should the Playwright environment start the workflow worker?
   • Option A: start a host process via npm --workspace=services/workflow-worker run dev
   • Option B: start a Docker container (compose) like the existing MinIO setup does
   • Decision criteria: reliability + ease of local debugging + CI friendliness

Acceptance Criteria (Definition of Done)

• A Playwright test exists that:
  • creates a workflow (trigger TICKET_CREATED, action tickets.add_comment with body hello from workflow)
  • creates a ticket
  • verifies the comment appears on the ticket
  • verifies a workflow run completed successfully
• The test starts required dependencies (at least Postgres, Redis, workflow worker) in a repeatable way.
• Running the test locally produces a deterministic pass on a clean environment.