test(js): vitest + jsdom unit tests for scheming-ai-suggestions.js (+ fixes 1 polling bug)

[jqnatividad]

Summary

Adds the missing JS test infrastructure for the 419-line scheming-ai-suggestions.js polling controller. The harness immediately caught a real polling bug (STATUS read from the wrong key) — fixed in the same PR. The same pattern as PR #303 catching real qsv bugs once E2E was actually exercised: feature surface that wasn't tested was, predictably, broken.

What's added

File	Purpose
package.json	Vitest + jsdom + jquery devDeps (~24 packages, no Babel)
vitest.config.js	jsdom env + setup file + test glob
tests/js/setup.js	jQuery loaded into the jsdom realm; ckan.module stub; buildInstance + stubAjax helpers
tests/js/scheming-ai-suggestions.test.js	12 tests across 4 describe blocks
tests/js/README.md	How to run, what's covered, harness internals
.gitignore	node_modules / package-lock.json / coverage

Coverage (12 tests)

• Module registration (3) — name, options defaults, exposed methods
• initialize() early-return guard (2) — bails when data-field-name is missing (the guard added in feat(ai-suggestions): scheming UI for AI-derived metadata (PR #253 follow-up) #302's Copilot follow-up); hides + starts polling when present
• _pollForAiSuggestions() state machine (4) — STATUS=DONE termination, polls again when ai_suggestions absent, caps at maxPollAttempts, retries with exponential backoff on ajax error
• _showAiSuggestionButtons() DOM updates (3) — reveals + sets data attrs; leaves unmatched buttons hidden; no-ops on empty value

Real bug found

Polling never terminated in production. The JS was reading STATUS from dpp_suggestions.STATUS (top level), but AISuggestionsStage._reshape_for_ui writes it INSIDE ai_suggestions.STATUS. The terminal status check never fired → polling ran out the 100s maxPollAttempts clock on every successful AI suggestion run, burning ~40 redundant package_show calls per dataset edit.

Fix: JS now reads dpp_suggestions.ai_suggestions.STATUS first, falls back to the top-level value for forward-compat with custom plugins that mirror the legacy convention. Same blast pattern as the qsv bugs caught by E2E in #303: untested surface == broken surface.

Cleanup

• $(document).ready(handler) → $(handler) (jQuery 3.0+ idiom; clears the deprecation warning).

Run

npm install      # one-time
npm test         # one-shot
npm run test:watch

Node 22+ recommended. The Python test suite (171 tests) is unaffected — JS lives in its own toolchain.

What's NOT covered (deferred)

• Popover creation / positioning / dismissal — lots of jQuery scaffolding, low signal-per-line for unit tests
• Real CKAN-on-page integration — covered by manual UI checks against the integration stack

Why Vitest (not Jest / Karma)

Vitest + jsdom is the minimum-footprint choice for a Python-first project. ~24 npm packages total vs ~500 for Jest+jsdom+Babel. Single vitest.config.js; no Babel toolchain. Documented in tests/js/README.md.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a minimal JavaScript unit-test toolchain (Vitest + jsdom + jQuery) to cover the scheming-ai-suggestions.js polling controller and fixes a production polling termination bug by reading STATUS from dpp_suggestions.ai_suggestions.STATUS.

Changes:

• Introduces Vitest/jsdom-based JS test harness under tests/js/ plus a root vitest.config.js.
• Adds 12 unit tests covering module registration, initialize() guard behavior, polling state machine behavior, and DOM updates.
• Fixes polling termination by reading STATUS from the correct location and updates the jQuery ready handler idiom.

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
vitest.config.js	Adds Vitest configuration to run only tests/js/** under jsdom with a global setup file.
package.json	Introduces a small npm devDependency set and test scripts for running the JS unit suite.
tests/js/setup.js	Implements the jsdom/jQuery/CKAN-module stubs and helpers to load the side-effect SUT and stub ajax.
tests/js/scheming-ai-suggestions.test.js	Adds unit coverage for initialization and polling logic of scheming-ai-suggestions.js.
tests/js/README.md	Documents how to run the JS tests and what contract they cover.
ckanext/datapusher_plus/assets/js/scheming-ai-suggestions.js	Fixes STATUS lookup for polling termination and updates document-ready binding.
.gitignore	Ignores node/vitest artifacts (node_modules, coverage, package-lock).

Comments suppressed due to low confidence (2)

tests/js/setup.js:77

• stubAjax() overwrites window.$.ajax but nothing restores the original implementation, and the global const $ = window.$ is reused across tests. This can cause cross-test bleed (a later test may accidentally hit a stubbed ajax from a previous test). Capture the original $.ajax once and restore it in the global beforeEach/afterEach, or have stubAjax return a restore function that tests call in afterEach.

beforeEach(() => {
  // Reset DOM + globals between tests so module state doesn't bleed.
  document.body.innerHTML = '';
  document.documentElement.innerHTML = '<head></head><body></body>';

  window.$ = $;
  window.jQuery = $;
  global.$ = $;
  global.jQuery = $;

  // CKAN module registrar stub. The real ckan.module(name, callback)
  // wires the returned object up for DOM auto-discovery via
  // ``[data-module=name]``. For tests we just capture the callback
  // so we can instantiate the returned object manually with the
  // ``this`` binding (``this.el``, ``this.options``) we choose.
  window.ckan = {
    SITE_ROOT: '',
    module: (name, factory) => {
      registeredFactory = { name, factory };
    },
  };
  global.ckan = window.ckan;

  // Wipe any leaked global state from prior tests.
  delete window._schemingAiSuggestionsGlobalState;

  // Wipe any previously-registered factory.
  registeredFactory = null;
});

tests/js/scheming-ai-suggestions.test.js:111

• Test name mentions dpp_suggestions.STATUS, but the asserted terminal status in the fixture is dpp_suggestions.ai_suggestions.STATUS (matching the production fix). Rename the test to reflect the actual contract so future readers don’t reintroduce the original bug.

  it('stops polling when dpp_suggestions.STATUS is in terminalStatuses', () => {
    // Seed a button + datasetId; one ajax response with STATUS=DONE.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jqnatividad]

Took a pass through the two low-confidence comments from review #4305403052:

1. stubAjax doesn't restore window.$.ajax (setup.js:77) — applied. Real cross-test bleed: window.$ is the same jQuery instance across all tests (captured once at module load), so window.$.ajax = stub from one test was leaking into the next. Captured originalAjax = $.ajax at module load and restore it in the beforeEach. Tests that want the stub now have to explicitly call stubAjax(); default state matches a fresh page load.

2. Test name says dpp_suggestions.STATUS but fixture uses ai_suggestions.STATUS (test.js:111) — applied. Renamed to stops polling when dpp_suggestions.ai_suggestions.STATUS is in terminalStatuses so the test name reflects the actual contract this PR established. A future reader looking at the name alone now sees the right path.

Both pushed in commit 2df3ebd. 12/12 tests still pass.