Skip to content

Local Extension Testing

Test the extension in your local VS Code before opening a pull request or publishing.

Install dependencies

Run from the repository root:

just init

just init installs the Node toolchain, the VS Code extension build tools, the locked Python generator environment, and the prek git hooks (pre-commit and pre-push) that run lint, type, format, and test checks automatically. The manual equivalent is:

npm install
uv sync --project tools --frozen --all-groups
uv run --project tools prek install --hook-type pre-commit --hook-type pre-push

Run the automated checks

The fastest way to verify logic is the command set used in CI:

npm run lint
npm run check-types
npm run test:unit
npm run test:extension
  • npm run lint runs ESLint over the TypeScript source.
  • npm run check-types runs tsc --noEmit.
  • npm run test:unit compiles the source and runs the Node unit tests in out/test/*.test.js.
  • npm run test:extension compiles, bundles dist/extension.js, downloads VS Code 1.90.2, installs the batisteo.vscode-django dependency, and runs the extension-host smoke suite.

To run the full test surface, including Python generator tests and snippet validation:

npm test

This also runs check-snippets and pytest under tools/.

Debug interactively with F5

For day-to-day development, run the extension inside a real Extension Development Host:

  1. Open the repository in VS Code.
  2. Press F5 (or choose Run → Start Debugging).
  3. Select the launch configuration named "Run Extension (F5)".

The existing .vscode/launch.json configuration loads the workspace at ${workspaceFolder}/examples in a new VS Code window with your local extension activated. You can set breakpoints in the TypeScript source, inspect variables, and watch the Output panel while the extension runs.

{
  "name": "Run Extension (F5)",
  "type": "extensionHost",
  "request": "launch",
  "args": [
    "--extensionDevelopmentPath=${workspaceFolder}",
    "${workspaceFolder}/examples"
  ],
  "outFiles": [
    "${workspaceFolder}/out/**/*.js"
  ],
  "preLaunchTask": "npm: compile"
}

Use this mode to iterate on activation, completions, hover, diagnostics, and Django partial behavior.

Test the packaged VSIX

A packaged VSIX is the artifact users install. Test it locally to catch missing files, packaging errors, or behavior that only works in the source tree:

npm run package
npx vsce ls --tree
code --install-extension htmx-django-intellisense-*.vsix --force

If you use VS Code profiles, this installs into the default profile's extension pool, not necessarily the profile your workspace is bound to. Check which profile is active (Status Bar → profile name) and, if it isn't "Default", reinstall with --profile "<your-profile-name>" so the extension shows up in that window's Extensions view.

Open the examples/ workspace (or any HTML/Django template project) and run through this smoke checklist:

  1. Open an HTML file and type <div hx. Confirm hx-get, hx-post, and other attributes appear.
  2. Type <div data-hx. Confirm data-hx-get aliases appear.
  3. Hover a known attribute such as hx-get. Confirm documentation, version badges, and HTMX doc links appear.
  4. Hover an ordinary HTML attribute such as class. Confirm no HTMX hover text appears.
  5. Type a misspelled attribute such as hx-methd. Confirm a diagnostic appears.
  6. Press Ctrl/Cmd+. on the diagnostic. Confirm quick fixes such as "Replace with 'hx-method'" and "Replace with 'data-hx-method'" are offered.
  7. Open a django-html file with {% partialdef card inline %} and {% partial card %}. Confirm completion and go-to-definition work for local partials.
  8. Try the partial rename with F2. Confirm both the definition and the call update.

Inspect extension output

When something behaves differently than expected, open Output → HTMX Django IntelliSense in the host VS Code window. The channel logs activation events, catalog loading, and runtime errors.

Common local-testing issues:

  • No completions or hover: confirm the document language mode is HTML or Django HTML. For Django templates, install and enable batisteo.vscode-django, then reload the window.
  • Django partials do not resolve: confirm the Django extension is installed and the file is recognized as django-html.
  • Extension does not activate: check the Output panel for a catalog-load error. If htmx.catalog.json is missing from the VSIX, reinstall the extension or rebuild with npm run package.

When you are done

After local testing passes, run the full CI verification checklist before pushing:

just verify