PSA/ee/docs/extension-scheduling-temporal-test-plan.md

Extension Scheduling + Temporal Execution Test Plan (Hosted EE)

This document defines a concrete, implementation-oriented test plan to validate extension scheduling and Temporal execution paths in hosted Enterprise Edition. It focuses on ensuring that schedules created via UI/host APIs are registered in Temporal and executed by the worker, and that failures surface safely.

Goals

• Validate that extension schedules are registered in Temporal and executed via genericJobWorkflow.
• Validate the end-to-end flow from UI/API schedule creation to Temporal execution and runner invocation.
• Validate task-queue routing and worker handler registration for extension-scheduled-invocation.
• Validate run-now execution uses Temporal workflow path and updates job/schedule records.
• Validate Temporal worker startup configuration for hosted EE.

Non-goals

• Coverage for non-extension scheduling (billing schedules, ticket scheduling, etc.).
• Performance/load testing or latency benchmarking.
• Full validation of runner implementation or extension code behavior beyond schedule invocation.
• Testing the legacy pg-boss scheduling path (CE).

Current Coverage Summary

Existing tests cover DB-level scheduling logic, validation, and handler behavior, but do not validate real Temporal execution.

Key current tests:

• ee/server/src/__tests__/integration/extension-schedules.actions.integration.test.ts
  • DB integration for admin-facing schedule CRUD, validation, atomicity, enable/disable, run-now enqueue.
  • Mocks job runner (no Temporal).
• ee/server/src/__tests__/integration/schedulerHostApi.integration.test.ts
  • DB integration for scheduler host API (runner-facing, by endpoint path).
  • Mocks job runner (no Temporal).
• ee/server/src/__tests__/integration/extension-schedule-cleanup.integration.test.ts
  • Uninstall/toggle cleanup for schedules and runner cancellation. Mocks job runner.
• ee/server/src/__tests__/integration/extension-schedule-remap.integration.test.ts
  • Remap schedule endpoints across extension version update. Mocks job runner.
• ee/server/src/__tests__/integration/extension-scheduled-invocation.handler.integration.test.ts
  • Invokes extensionScheduledInvocationHandler directly. Uses DB + fetch mock; no Temporal.
• ee/server/src/__tests__/unit/temporalJobRunner.*.test.ts
  • Unit tests for TemporalJobRunner using mocked @temporalio/client.
• ee/server/src/__tests__/integration/extension-schedules.playwright.test.ts
  • UI schedule create/edit/toggle/run-now; verifies DB only.

Temporal workflow tests exist but do not cover generic job workflow:

• ee/temporal-workflows/src/workflows/portal-domains/__tests__/registration.workflow.integration.test.ts
• ee/temporal-workflows/src/activities/__tests__/tenant-activities.test.ts
• ee/temporal-workflows/src/activities/__tests__/email-activities.temporal.test.ts

Gaps:

• No test verifies that schedules created in UI/API are registered in Temporal.
• No test validates genericJobWorkflow execution, status updates, or activity wiring.
• No test validates initializeJobHandlersForWorker registration for extension scheduled jobs.
• No test validates real Temporal schedule execution path for extension schedules.
• No test validates worker startup configuration checks in ee/temporal-workflows/src/config/startupValidation.ts.

Key Risks (Production)

• Temporal schedules not created or misconfigured despite green tests.
• genericJobWorkflow fails to execute or update job status, and tests don’t catch it.
• Worker task queue misconfiguration (missing alga-jobs) leads to no executions.
• Worker fails startup validation in hosted environments due to missing required secrets.
• Handler registration for extension-scheduled-invocation fails, leaving jobs queued forever.

Test Pyramid

Unit (fast, deterministic):

• Validate parsing, validation, error handling in isolation.
• Mock DB and Temporal SDK.

Integration (real DB + Temporal):

• Validate Temporal schedule creation, execution, and job status updates end-to-end.
• Use @temporalio/testing (time-skipping) or docker Temporal (full integration).

E2E (UI + Temporal + DB):

• Validate UI flows create Temporal schedules and that those schedules execute.

Proposed New Tests (Exact Suggestions)

Unit

1. ee/temporal-workflows/src/workflows/__tests__/generic-job-workflow.temporal.test.ts

• Use TestWorkflowEnvironment.createTimeSkipping().
• Start genericJobWorkflow with stubbed activities for:
  • executeJobHandler success and failure
  • updateJobStatus called with expected status
• Assert workflow state transitions and final result structure.

2. ee/temporal-workflows/src/config/__tests__/startupValidation.test.ts

• Validate missing required envs cause failure.
• Validate optional defaults are applied.
• Validate EMAIL_PROVIDER=resend requires RESEND_API_KEY.
• Mock secrets provider via @alga-psa/core/secrets import.

3. ee/server/src/__tests__/unit/temporalJobRunner.parseScheduleSpec.test.ts

• Validate cron vs interval parsing and timezone propagation.
• Include cron with 5 fields and duration strings.

Integration (Temporal + DB)

4. ee/server/src/__tests__/integration/extension-schedules.temporal.integration.test.ts

Goal: verify schedule creation registers a Temporal schedule and executes handler.

Suggested flow:

• Setup real DB using createTestDbConnection and apply EE migrations.
• Use Temporal test env or docker Temporal.
• Create schedule via createExtensionSchedule or schedulerHostApi.createSchedule.
• Verify Temporal schedule exists: client.schedule.getHandle(id).describe().
• Advance time or trigger schedule; verify:
  • genericJobWorkflow executed via Temporal.
  • extensionScheduledInvocationHandler updates tenant_extension_schedule.last_run_*.

5. ee/server/src/__tests__/integration/extension-run-now.temporal.integration.test.ts

• Create schedule (enabled or disabled), call runExtensionScheduleNow.
• Verify Temporal workflow started on alga-jobs and completed.
• Verify jobs table updated to completed/failed and schedule last-run fields updated.

6. ee/temporal-workflows/src/__tests__/worker-extension-handler.integration.test.ts

• Start a Worker using the real activities set, ensure initializeJobHandlersForWorker executes.
• Start genericJobWorkflow on alga-jobs and assert the executeJobHandler activity is invoked.
• Mock runner HTTP using fetch, reuse extensionScheduledInvocationHandler tests as guidance.

E2E (UI + Temporal)

7. Extend ee/server/src/__tests__/integration/extension-schedules.playwright.test.ts

• After UI schedule create, verify Temporal schedule exists and fires (use Temporal client from test).
• For hosted CI: run against docker Temporal in compose.

Required Mocks vs Real Dependencies

Unit tests:

• Mock @temporalio/client and DB access.
• Mock secrets provider.

Integration tests:

• Real Postgres (test DB) + Temporal (test env or docker).
• Mock only runner HTTP (globalThis.fetch) to avoid depending on actual runner service.
• Do not mock Temporal client/worker.

E2E tests:

• Real Postgres + Temporal.
• Runner HTTP can be stubbed or use a lightweight fake service.

CI Execution Strategy

Split into tiers to keep CI stable and fast:

1. Unit tier (fast):

cd ee/server && npm run test:unit
cd ee/temporal-workflows && npm run test:unit

2. Integration tier (Temporal + DB):

• Use docker Temporal from ee/temporal-workflows/docker-compose.test.yml.
• Run new Temporal integration tests with a dedicated Vitest config (single fork).

Example:

cd ee/temporal-workflows && npm run docker:test:up
cd ee/server && npm run test:integration -- --runInBand --testNamePattern=Temporal
cd ee/temporal-workflows && npm run test -- src/__tests__/worker-extension-handler.integration.test.ts
cd ee/temporal-workflows && npm run docker:test:down

3. E2E tier (Playwright + Temporal):

cd ee/server && npm run test:playwright

Local/Manual Validation Steps

Temporal + UI:

docker-compose -f docker-compose.ee.yaml up -d temporal-dev temporal-ui
cd ee/temporal-workflows && npm run dev
cd ee/server && npm run dev

• Create an extension schedule in UI.
• Use Temporal UI (http://localhost:8233) to verify schedule exists.
• Wait for execution and verify tenant_extension_schedule.last_run_* fields update.

Direct run-now:

• Trigger run-now in UI and verify Temporal workflow execution in Temporal UI.
• Verify jobs and schedule records update.

Rollout Phases

Quick wins (1–3 days):

• Add genericJobWorkflow Temporal test.
• Add startupValidation unit tests.
• Add parseScheduleSpec unit tests.

Must-have before release:

• Add Temporal integration tests for schedule registration and execution.
• Add run-now Temporal integration test.
• Add worker handler registration integration test.

Hardening:

• Extend Playwright schedule test to assert Temporal schedule exists and fires.
• Add Temporal failure-mode tests (connection failure, schedule update error handling).

Exit Criteria

• Unit tests:

  • genericJobWorkflow verified for success and failure paths.
  • startupValidation required/optional config behaviors validated.
  • parseScheduleSpec covers cron/interval and edge cases.

• Integration tests:

  • Creating a schedule via API results in a real Temporal schedule and at least one execution.
  • Run-now triggers a Temporal workflow execution and updates DB job/schedule state.
  • Worker registers extension-scheduled-invocation handler and executes genericJobWorkflow successfully.

• E2E:

  • UI schedule creation results in a Temporal schedule and recorded execution.

• CI stability:

  • Temporal integration tests run reliably in CI with docker Temporal.
  • New tests are under 10 minutes aggregate runtime in CI.