test(bulk-import): increase test coverage, dev harness, and contributor docs

[PatAKnight]

Hey, I just made a Pull Request!

This PR aims to increase the test coverage for the bulk import plugins, with a focus on Backstage integration.

It also adds a contributor guide with steps for running the plugin dev/ harness, running the usual package/workspace validation commands, and a short manual smoke checklist.

✔️ Checklist

• A changeset describing the change and affected packages. (more info)
• Added or Updated documentation
• Tests for new functionality and regression tests for bug fixes
• Screenshots attached (for UI changes)

[rhdh-gh-app]

Changed Packages

Package Name	Package Path	Changeset Bump	Current Version
@red-hat-developer-hub/backstage-plugin-bulk-import-backend	workspaces/bulk-import/plugins/bulk-import-backend	patch	v8.0.1
@red-hat-developer-hub/backstage-plugin-bulk-import	workspaces/bulk-import/plugins/bulk-import	patch	v8.0.1

[sonarqubecloud]

Quality Gate passed

Issues
3 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

[rhdh-qodo-merge]

PR Summary by Qodo

Expand bulk-import tests and add local dev/contributor guides

🧪 Tests 📝 Documentation 🕐 40+ Minutes

AI Description

• Add backend integration/router coverage for migrations, auth gates, and token redaction.
• Rework useRepositories hook tests to use real React Query + Backstage API providers.
• Add contributor guides and link them from plugin READMEs for bump-smoke workflows.

Diagram

graph TD
  Contributor["Contributor"] --> Guides[/"Contrib guides"/] --> FrontendTests["Frontend tests"] --> Frontend["Bulk-import UI"] --> Common["Common perms"] --> Backend["Bulk-import API"] --> BackendTests["Backend tests"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Rely on workspace Playwright e2e for “bump trust”

• ➕ Exercises UI flows end-to-end with browser automation
• ➕ Can catch regressions in routing/navigation
• ➖ Workspace e2e explicitly mocks OAuth, so it won’t validate real SCM token/on-behalf-of flows
• ➖ Slower and typically more brittle than targeted unit/integration tests

2. Keep tests purely unit-level with heavy mocking

• ➕ Fastest execution and minimal setup
• ➕ Very deterministic when mocking all dependencies
• ➖ Lower confidence on real Backstage wiring (router registration, migrations, service factories)
• ➖ More risk of tests diverging from actual runtime behavior during Backstage bumps

3. Move credential-backed OAuth coverage to overlays/consumer deployments only

• ➕ Validates real multi-user OAuth and real SCM integrations
• ➕ Closer to production conditions
• ➖ Harder to run in CI for this repo and less actionable for day-to-day Backstage bump validation
• ➖ Doesn’t replace the need for local harness + contract-level tests

Recommendation: The PR’s approach is the best default: use Backstage’s test utilities for backend integration coverage (router + migrations) and realistic frontend hook testing with a real QueryClient/TestApiProvider, then document the intended dev harness + smoke checks. Reserve Playwright and overlay/consumer deployments for targeted scenarios where browser-level or real OAuth coverage is required.

Files changed (11) +861 / -44

Enhancement (1) +6 / -2

testUtils.tsGeneralize backend test server helper to accept extra backend features +6/-2

Generalize backend test server helper to accept extra backend features

• Tightens types for the optional config/db parameters and adds an 'extraFeatures' parameter to inject additional 'BackendFeature's into the test backend. This enables tests to plug in mocks (e.g., auditor) without duplicating server bootstrap logic.

workspaces/bulk-import/plugins/bulk-import-backend/fixtures/testUtils.ts

Tests (5) +723 / -2

plugin.integration.test.tsAdd backend plugin integration test for router registration and migrations +80/-0

Add backend plugin integration test for router registration and migrations

• Introduces an integration test using 'startTestBackend' to verify '/ping' is reachable and that database migrations run on plugin init by asserting expected tables exist.

workspaces/bulk-import/plugins/bulk-import-backend/src/plugin.integration.test.ts

router.test.tsIncrease router test coverage for missing tokens and auditor redaction +67/-0

Increase router test coverage for missing tokens and auditor redaction

• Adds parameterized 401 coverage when 'X-SCM-Tokens' is absent for token-gated endpoints and verifies auditor events do not persist token header values. Uses the new 'extraFeatures' hook to inject an auditor mock into the backend test server.

workspaces/bulk-import/plugins/bulk-import-backend/src/service/router.test.ts

permissions.test.tsAdd contract test for exported permission name/resourceType +24/-0

Add contract test for exported permission name/resourceType

• Adds a small unit test to lock down the stable permission name and resource type exported by the common package.

workspaces/bulk-import/plugins/bulk-import-common/src/permissions.test.ts

useRepositories.test.tsxRewrite 'useRepositories' tests to use TestApiProvider + real QueryClient +529/-0

Rewrite 'useRepositories' tests to use TestApiProvider + real QueryClient

• Replaces the previous heavily mocked hook tests with a wrapper that provides Backstage APIs (config/identity/scmAuth) and a real React Query client. Expands assertions around token collection/gating, login rejection handling, and query-key token secrecy.

workspaces/bulk-import/plugins/bulk-import/src/hooks/useRepositories.test.tsx

plugin.test.tsAdd plugin API factory test for 'bulkImportApiRef' wiring +23/-2

Add plugin API factory test for 'bulkImportApiRef' wiring

• Updates the plugin test to assert the plugin registers 'bulkImportApiRef' and that the API factory constructs a 'BulkImportBackendClient' when provided config and identity APIs.

workspaces/bulk-import/plugins/bulk-import/src/plugin.test.ts

Documentation (4) +126 / -40

CONTRIBUTING.mdExpand backend contributor guide (dev harness, smoke curls, validation commands) +65/-40

Expand backend contributor guide (dev harness, smoke curls, validation commands)

• Replaces the minimal setup notes with a structured contributor guide covering prerequisites, standalone dev harness usage, curl-based smoke checks, and scoped workspace validation commands. Clarifies expectations around permissions testing and where bump-trust coverage should live.

workspaces/bulk-import/plugins/bulk-import-backend/CONTRIBUTING.md

README.mdLink backend README to CONTRIBUTING dev/testing guide +2/-0

Link backend README to CONTRIBUTING dev/testing guide

• Adds a pointer from the backend README to CONTRIBUTING.md for local development and bump smoke guidance.

workspaces/bulk-import/plugins/bulk-import-backend/README.md

CONTRIBUTING.mdAdd frontend contributor guide (dev harness, scoped validation, e2e guidance) +57/-0

Add frontend contributor guide (dev harness, scoped validation, e2e guidance)

• Adds a new contributor doc describing the frontend dev harness (NFS and legacy), scoped validation commands, and guidance on when to use full workspace apps vs Playwright vs overlays for OAuth-backed scenarios.

workspaces/bulk-import/plugins/bulk-import/CONTRIBUTING.md

README.mdLink frontend README to CONTRIBUTING dev/testing guide +2/-0

Link frontend README to CONTRIBUTING dev/testing guide

• Adds a pointer from the frontend README to CONTRIBUTING.md for local development and Backstage bump smoke checks.

workspaces/bulk-import/plugins/bulk-import/README.md

Other (1) +6 / -0

clean-jokes-sell.mdAdd changeset for contributor-doc + test coverage updates +6/-0

Add changeset for contributor-doc + test coverage updates

• Adds a patch changeset for both bulk-import backend and frontend packages, documenting the new contributor guides and bump-trust testing focus.

workspaces/bulk-import/.changeset/clean-jokes-sell.md

[rhdh-qodo-merge]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 58.07%. Comparing base (b261d26) to head (1aa94f2).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4148      +/-   ##
==========================================
+ Coverage   58.06%   58.07%   +0.01%     
==========================================
  Files        2411     2412       +1     
  Lines       96367    96369       +2     
  Branches    26806    26793      -13     
==========================================
+ Hits        55953    55966      +13     
+ Misses      40218    40207      -11     
  Partials      196      196              

Flag	Coverage Δ		*Carryforward flag
adoption-insights	84.55% <ø> (ø)		Carriedforward from b261d26
ai-integrations	69.71% <ø> (ø)		Carriedforward from b261d26
app-defaults	69.79% <ø> (ø)		Carriedforward from b261d26
augment	46.67% <ø> (ø)		Carriedforward from b261d26
boost	76.77% <ø> (ø)		Carriedforward from b261d26
bulk-import	72.79% <ø> (+0.23%)	⬆️
cost-management	13.55% <ø> (ø)		Carriedforward from b261d26
dcm	60.72% <ø> (ø)		Carriedforward from b261d26
extensions	56.59% <ø> (ø)		Carriedforward from b261d26
global-floating-action-button	71.18% <ø> (ø)		Carriedforward from b261d26
global-header	66.50% <ø> (ø)		Carriedforward from b261d26
homepage	47.50% <ø> (ø)		Carriedforward from b261d26
install-dynamic-plugins	59.95% <ø> (ø)		Carriedforward from b261d26
intelligent-assistant	74.61% <ø> (ø)		Carriedforward from b261d26
konflux	91.98% <ø> (ø)		Carriedforward from b261d26
lightspeed	69.02% <ø> (ø)		Carriedforward from b261d26
mcp-integrations	83.40% <ø> (ø)		Carriedforward from b261d26
orchestrator	66.87% <ø> (ø)		Carriedforward from b261d26
quickstart	63.74% <ø> (ø)		Carriedforward from b261d26
sandbox	79.56% <ø> (ø)		Carriedforward from b261d26
scorecard	85.45% <ø> (ø)		Carriedforward from b261d26
theme	88.52% <ø> (ø)		Carriedforward from b261d26
translations	5.12% <ø> (ø)		Carriedforward from b261d26
x2a	79.20% <ø> (ø)		Carriedforward from b261d26

*This pull request uses carry forward flags. Click here to find out more.

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update b261d26...1aa94f2. Read the comment docs.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.