crosshair-vscode

Crosshair-vscode is an extension for Visual Studio Code (VS Code) that allows you to statically test your Python code using CrossHair.

Installation

Crosshair-vscode has two dependencies:

• The Python extension ms-python.python for VS Code, and
• The Python packages crosshair-tool and pygls.

ms-python.python. Use the Visual Studio marketplace to install the extension ms-python.python by following this link.

crosshair-tool. The easiest way to install the crosshair-tool and pygls packages is to open the terminal tab and run pip3:

pip3 install crosshair-tool pygls

These packages must be installed in each Python environment that you wish to use. (the environment is displayed and can be changed in the status bar)

crosshair-vscode. Use the Visual Studio marketplace to install the extension by following this link.

Usage

The extension can be accessed from the status bar. When editing Python files, you'll see a new item labeled "CH off" (or "CH on" if the background watcher is already running).

Click on this item to open a menu and perform various commands.

Most importantly, you'll want to start the background watcher; by default, it does not auto-start. Once started, CrossHair will attempt to detect contract counterexamples in the background. When it finds something, you'll see it highlighted like this:

NOTE: To reduce wasteful computation, the background watcher only checks contracts in files that are open. You may decide to leave some files open to ensure some contracts continue to be checked as you work.

If you want to be even more targeted by just checking an individual file, use the "watch in terminal" command.

Commands

The extension defines the following commands:

• crosshair-vscode.pick. Show a quick pick that allows you to select a command to execute.

  This is handy if you do not want to memorize individual commands, and want to set up a single keyboard shortcut to invoke crosshair-vscode.

• crosshair-vscode.start. Start the background watcher process.

• crosshair-vscode.stop. Start the background watcher process.

• crosshair-vscode.watch. Open a new terminal watching a file with crosshair.

  There is an optional argument indicating the path to a file. If no path is given, watch the current active file in the editor.

• crosshair-vscode.gentests. Produce tests for the function at the current cursor position.

Settings

Search your VSCode settings for "crosshair" to see the options that you can configure. Here, you can do things like set project-specific contract types (icontract vs asserts) and change whether the background watcher automatically starts.

Known Issues

It is hard to control terminals in VS Code (see this issue). We wait for a short delay (~1 second) till we send commands to the terminal. This might cause racing conditions in some rare cases.

Contributing

Please see [CONTRIBUTING.md] for how to help us with development of the extension.

Credits

This plugin was authored by Marko Ristin and is now maintained by Phillip Schanely.

Versioning

We follow a bit unusual semantic versioning schema:

• X is the oldest supported major version of crosshair-tool,
• Y is the minor version (odd numbers are pre-release versions), and
• Z is the patch version (only bug fixes).

Release Notes

0.0.1

Initial release of crosshair-vscode.

0.0.2

CrossHair now runs transparently in the background and highlights counterexamples directly in your code, just like a typechecker or linter would. You can stop or start CrossHair in the status bar. Some of the more specialized check commands have been removed, as background execution is the recommended way to use CrossHair.

0.2.0

A non-pre-release release of 0.0.2; there are no changes. (We're moving to the VSCode recommendation of using even minor version numbers for release versions)

0.2.1

Removes the possibility for leaked CrossHair workers when closing the editor window without explicitly stopping the background runner.