test(version-management): add e2e integration tests for plugin check-versions and upgrade

[gashcrumb]

Summary

Adds an automated end-to-end integration test suite (e2e-tests/plugin-version-management.test.ts) covering rhdh-cli plugin check-versions and rhdh-cli plugin upgrade across real plugin file structures, fulfilling the E2E testing requirements of RHIDP-16669.

Key Coverage

• Dependency Auditing (plugin check-versions & alias versions:lint):
  • Verifies exit code 1 when dependencies drift or mismatch from target RHDH release.
  • Verifies human-readable remediation hint (Run rhdh-cli plugin upgrade 2.1.0) and structured --json output (valid: false, status: "mismatch").
  • Verifies exit code 0 when dependencies align.
  • Registers the missing versions:lint alias in src/commands/index.ts.
• Dependency Upgrading (plugin upgrade & alias versions:bump):
  • --dry-run: Verifies table diff output while ensuring package.json and backstage.json remain untouched on disk.
  • --skip-install: Verifies package.json and backstage.json update to target manifest versions without triggering package manager install.
  • Full upgrade: Verifies full upgrade with package manager install (yarn install) updating yarn.lock.
• Multi-step Release Upgrade Lifecycle:
  • Tests step-by-step upgrade across release baselines (1.8 -> 2.0 -> 2.1) without version corruption or loss of third-party dependencies.
• Post-Upgrade Dynamic Plugin Export:
  • Confirms yarn tsc, yarn build, and rhdh-cli plugin export run cleanly on the upgraded plugin, generating dist-dynamic/package.json with matching backstage.supported-versions and zero version conflicts.
• Air-Gapped / Offline Execution:
  • Verifies check-versions and upgrade with --manifest-file <path> and RHDH_OFFLINE=true without external network calls.
• Test Infrastructure (e2e-tests/support/plugin-export-build.ts):
  • Enriches the thrown Error from runCommand with stdout, stderr, code, and signal properties for robust error assertions.

Follow-up documentation refactoring across all on-ramp workflows (plugin new, plugin dev, plugin check-versions, plugin upgrade) will be delivered in a subsequent PR.

[gashcrumb]

/fs-review

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 6:24 PM UTC · Ended 6:35 PM UTC

Commit: 9ce0e86 · View workflow run →

[gashcrumb]

/fs-review

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 6:46 PM UTC · Completed 7:11 PM UTC

Commit: c442487 · View workflow run →

Runtime: claude · Model: sonnet → claude-sonnet-4-6 · Effort: high · Cost: $4.32

[fullsend-ai-review]

Risk Assessment: moderate (2/5)

Details

Primarily a test-addition PR with two small production changes; large blast-radius classification is the dominant risk signal but is offset by high test file ratio, no protected or security-sensitive paths, and a well-scoped, easily reversible change set.

[fullsend-ai-review]

Review

Findings

Medium

• [pattern-violation] e2e-tests/plugin-dev.test.ts:22 — RunCommandOptions is still imported after its only consumer (the local runExpectingFailure function) was removed and promoted to the shared support module. This stale import will produce an unused-variable lint error and fail yarn lint:check in CI.
  Remediation: Remove RunCommandOptions from the import block.

• [incomplete-doc] README.md:43 — The "Checking Plugin Versions" section documents plugin check-versions but omits the versions:lint alias introduced by this PR. The symmetrical "Upgrading Plugin Versions" section explicitly documents the versions:bump alias at line 65. This creates an asymmetric documentation gap for users discovering the CLI.
  Remediation: Add a sentence analogous to line 65: "Its plugin versions:lint alias provides the same behavior."

Low

• [test-correctness] e2e-tests/plugin-version-management.test.ts:345 — The multi-step test asserts upgrade20Json.backstageVersion === '1.52.0' and pkgAfter20.dependencies['@backstage/core-plugin-api'] === '^1.12.7' without pinning to offline mode. Tier-1 remote fetch from the RHDH release-2.0 branch takes precedence when online. RHDH 2.0 is a frozen GA release so practical flakiness risk is low — but the unnecessary network dependency could produce false-negatives if the remote is transiently unavailable.
  Remediation: Add RHDH_OFFLINE: 'true' to the env for the multi-step upgrade/check calls, or use --manifest-file with a local fixture manifest (as the air-gapped describe block does) to make assertions fully deterministic.

• [test-correctness] e2e-tests/plugin-version-management.test.ts:204 — The "dependency upgrading" beforeEach only re-skews two specific packages without a matching afterEach to restore the directory. After the --skip-install test fully upgrades all packages, subsequent beforeEach calls produce a mixed state. Test 3 partially compensates by manually re-applying skewedPackageJson, but the design is fragile against future test additions.
  Remediation: Add an afterEach that restores pluginDir/package.json and backstage.json from a snapshot taken in beforeAll, mirroring the pattern used in the "dependency auditing" block.

• [test-correctness] e2e-tests/plugin-version-management.test.ts:469 — The offlineDir fixture in beforeAll does not include a backstage.json file. syncBackstageJson silently skips when the file is absent, so the backstage.json sync path is not exercised in offline mode. No assertion fails, but the gap is silent.
  Remediation: Add a backstage.json (e.g. { version: '1.54.6' }) to the offline fixture and assert parsedUpgrade.updatedFiles includes 'backstage.json' after upgrade.

• [scope-creep] src/commands/upgrade/command.ts:215 — The PR is typed test(version-management) via Conventional Commits (enforced by pr-semantic.yaml), but includes two production code changes: the versions:lint alias registration and the YARN_ENABLE_IMMUTABLE_INSTALLS env-var management. The PR body is transparent about both changes.
  Remediation: Amend the PR title to fix(version-management) to reflect the production fixes included, or split the production changes into a preceding fix commit.

• [incomplete-doc] README.md:67 — The "Upgrading Plugin Versions" section notes --skip-install to avoid lockfile mutation, but does not mention that the CLI now automatically sets YARN_ENABLE_IMMUTABLE_INSTALLS=false when the install step runs (new behavior in this PR). Users in CI with strict immutable-lockfile policies may be surprised when the lockfile is updated.
  Remediation: Add a note explaining that the CLI temporarily disables YARN_ENABLE_IMMUTABLE_INSTALLS during the install step, and recommend --skip-install for environments that need strict lockfile enforcement.

• [code-organization] src/commands/upgrade/command.ts:220 — runInstallDependencies temporarily mutates process.env.YARN_ENABLE_IMMUTABLE_INSTALLS globally rather than passing the override via subprocess spawn options. The save/restore logic in finally is correct (handles unset, set, and non-yarn cases), but global env mutation is unnecessary for a subprocess invocation.
  Remediation: Pass the override via Task.forCommand's spawn env option (env: { ...process.env, YARN_ENABLE_IMMUTABLE_INSTALLS: 'false' }) to avoid mutating the global environment.

---

Next steps:

• /fs-fix — agent addresses review findings automatically
• /fs-fix <your instruction> — agent fixes with your specific guidance
• Push commits directly — review re-runs automatically on push
• /fs-fix-stop — disable automatic fix runs for this PR

[fullsend-ai-review]

Note: The following review comments could not be posted on the diff (GitHub returned 422) and are included here instead:

• e2e-tests/plugin-version-management.test.ts (file-level): Line 469 · [low] test-correctness

The offlineDir fixture in beforeAll does not include a backstage.json file. syncBackstageJson silently skips when the file is absent, leaving the backstage.json sync path untested in offline mode. No assertion fails, but the gap is silent.

Suggested fix: Add a backstage.json to the offline fixture and assert parsedUpgrade.updatedFiles includes backstage.json after upgrade.

[fullsend-ai-review]

See the review comment for full details.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[PatAKnight]

LGTM