PythonTA VS Code Extension

This project is an extension for running PythonTA within VS Code.

Developers

Requirements

1. VS Code
2. Python extension for VS Code
3. uv
4. Node.js
5. pnpm

Setup

1. Install the extension's dependencies into the bundled libraries directory:

   uv pip install --target bundled/libs -r pyproject.toml

2. Install Javascript dependencies: pnpm install.

Testing the Extension Locally

1. To start the extension, use the Debug Extension and Python (shortcut F5) configuration in VS Code.
2. In the new VS Code window that appears, open a folder containing Python files, or create a new file.
3. Open a file with a snippet or write a snippet of Python code that violates standard PythonTA rule. For example:

   def add_numbers(a, b):
       return a + c

4. Save the file, and look for the diagnostic messages and rule codes generated by PythonTA.
5. You can view the extension output under the Output tab, and select "PythonTA VS Code Extension"

Troubleshooting: Server Crashes on File Reload

If you are actively testing the extension using the debugger (F5), you may notice that closing and reopening a Python file causes the server to crash repeatedly with a ConnectionRefusedError.

This is expected behavior in the development environment and will not happen in the published extension. It occurs because the VS Code Extension Development Host wraps the language server in a debugpy instance that fails to cleanly release its port when the file reloads.

If you want to avoid this during testing, and you do not need breakpoints, launch the Extension Development Host using Debug Extension Only (via the dropdown in the Run and Debug menu) instead of F5.

Running tests

To run the Python (language server) tests, run uv run pytest src/test/python_tests.

To run the extension's TypeScript tests, run pnpm test. This compiles the extension and its tests, downloads a copy of VS Code (cached under .vscode-test/ after the first run), installs the ms-python.python extension dependency into that test profile, and runs the suite in a real (headless-capable) Extension Development Host. On Linux, this requires a display server, e.g. run it as xvfb-run -a pnpm test.

Both test suites also run automatically in CI on every pull request and push to main; see .github/workflows/test.yml.

Coverage

Coverage is opt-in and not part of the default test commands above. Both sides write their reports under a single .coverage/ directory (gitignored).

For Python, add --cov to the normal pytest invocation, e.g. uv run pytest src/test/python_tests --cov=bundled/tool --cov-report=term-missing (add --cov-report=html for an HTML report at .coverage/python/html/index.html). This also measures coverage inside the LSP server subprocess that the test client spawns, not just the test process itself.

For the extension's TypeScript tests, run pnpm run test:coverage. This runs the same suite as pnpm test under c8 and writes a report to .coverage/typescript/reports/index.html (a text summary is also printed to the console).

In CI, both suites run with coverage enabled and upload their results to Coveralls as a single combined build (one job per language, reported under separate flags, merged in a final job); see .github/workflows/test.yml. This requires the repository to be enabled on Coveralls; no extra secrets are needed for public GitHub repos using Coveralls' GitHub App integration, but a private repo (or one not using that integration) will need a COVERALLS_REPO_TOKEN secret set and passed via github-token:/repo-token: in the workflow.

Linting

To lint the Typescript code, run pnpm run lint.

Linting for the Python code has not been set up yet.

Template information

This repository is based on a Template for VS Code python tools extensions. See the template README.md for more information.