dotCMS / dotCMS/core

e2e: Add E2E test suite for `@dotcms/create-app` CLI

Open
#35,096 0 comments 0 reactions 1 assignee View on GitHub

@fmontes is already working on this.

Since Mar 24, 2026.

Dominant language
Java
Stars
970
Forks
486
Avg merge
3d 33m
Merged PRs (30d)
170

Description

Description

The @dotcms/create-app CLI currently has no E2E test coverage. As part of the feat/create-app-custom-starter-url branch work, a full manual E2E regression was performed and all test cases were documented. This task is to implement those test cases as automated E2E tests using Jest + execa.

Tech approach:

  • Use execa (already a project dependency) to spawn the CLI process
  • Add a separate jest.e2e.config.ts alongside the existing unit test config
  • Add a dedicated test-e2e target in project.json
  • Tests live in libs/sdk/create-app/e2e/
  • Run serially (maxWorkers: 1) to avoid port conflicts
  • Strip ANSI codes before asserting on output

Test cases to implement:

Group 1 — Fast validation (no network, no Docker):

  • E2E-003: --url without protocol (e.g. demo.dotcms.com) → exit non-zero, error mentions http:// or https://
  • E2E-010: --starter without protocol → exit non-zero, URL format error
  • E2E-015: --framework react (unsupported) → exit non-zero, lists supported frameworks
  • E2E-017: --version → exit 0, prints version string

Group 2 — Cloud (requires live dotCMS URL):

  • E2E-001: All flags provided (--url, --username, --password, --framework) → exit 0, token generated, UVE configured, frontend scaffolded
  • E2E-004: Interactive cloud flow — wrong creds twice then correct → succeeds on 3rd attempt
  • E2E-005: Interactive cloud flow — wrong creds 3 times → exit non-zero, max attempts message
  • E2E-006: Unreachable URL (http://localhost:65530) → exit non-zero, connection error after retries

Group 3 — Local/Docker (requires Docker running):

  • E2E-007: --local --framework astro → exit 0, Docker starts, UVE configured, Astro scaffolded
  • E2E-008: --starter <valid-zip-url> → exit 0, CUSTOM_STARTER_URL set in docker-compose.yml, scaffolding skipped
  • E2E-009: --starter <url> --url https://x --username u --password p → warning printed, local mode wins, cloud params ignored
  • E2E-011: --starter <bad-url> (non-zip or unreachable) → exit non-zero, error surfaced
  • E2E-012: Port 8082 occupied → exit non-zero, actionable port-busy message
  • E2E-013: Docker not running → exit non-zero, Docker availability error

Group 4 — Usability:

  • E2E-014a: --framework next → normalized to nextjs, no framework error
  • E2E-014b: --framework ng → normalized to angular, no framework error
  • E2E-016: Target directory non-empty → prompts or errors, no silent destructive behavior

Acceptance Criteria

  • jest.e2e.config.ts added with testTimeout: 120_000 and maxWorkers: 1
  • test-e2e target added to project.json running yarn nx run sdk-create-app:test-e2e
  • All Group 1 (validation) tests implemented and passing in CI
  • All Group 4 (alias normalization) tests implemented and passing in CI
  • Group 2 and Group 3 tests implemented with appropriate skip guards (@requires-docker, @requires-network) so they don't break CI when infrastructure is unavailable
  • ANSI strip helper utility added at e2e/helpers/strip-ansi.ts
  • Cleanup (rm -rf temp dirs, docker compose down) handled in afterEach/afterAll

Additional Context

  • execa is already a dependency — no new packages needed for non-interactive tests
  • For interactive prompt tests (E2E-004, E2E-005, E2E-016), pipe answers via proc.stdin?.write('answer\n')
  • The built artifact used for testing: dist/libs/sdk/create-app/index.js
  • Reference PR: feat/create-app-custom-starter-url
  • Manual regression report available in that PR's conversation history

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.