From 19fb55a83886968222a3fba85a5306912810daa6 Mon Sep 17 00:00:00 2001 From: Michael Noah <92764374+mnoah1@users.noreply.github.com> Date: Thu, 13 Jun 2024 15:17:24 -0400 Subject: [PATCH 1/3] Create getting_started.md --- docs/getting_started.md | 125 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 docs/getting_started.md diff --git a/docs/getting_started.md b/docs/getting_started.md new file mode 100644 index 0000000..c7d14e6 --- /dev/null +++ b/docs/getting_started.md @@ -0,0 +1,125 @@ +# Getting Started Guide + +## Core Functionality +- Download, install, and launch of Bazel BSP (https://github.com/JetBrains/bazel-bsp) +- Syncing Bazel targets and browsing test cases within source files +- Executing test runs, with filtering by test case +- Code coverage overlay via VS Code's new Coverage API +- Test failure display and overlay on the code +- Browsing run history + +## Overall Extension Structure +The BSP extension consists of two parts: + +1. The VS Code extension, considered the "client", which integrates directly with VS Code's extension API. +2. The "server" process (Bazel BSP), which is a separate locally running process that handles most of the Bazel interaction. + +As you interact with the VS Code UI, the client sends requests to this server over Build Server Protocol, which standardizes the interaction between IDE's and build tooling. +- The client extension will download and install a copy of the server when launched for the first time in a repo. +- A file, ./.bsp/bazelbsp.json is placed at the root of the repo with instructions for the client to launch the server as needed. +- Only the extension ("client") needs to be installed directly in VS Code. The client then includes logic to download, install, and launch the server as necessary. + +## Supported Languages +- Python (via Pylance language server) +- Java (via basic text discovery) +- _Others to be added in the future_ + +## Getting Started +### Extension Installation +- Download a recent release of this extension +- Install it via the "Install from VSIX..." option + + ![image](https://github.com/uber/vscode-bazel-bsp/assets/92764374/8f5f746a-2a33-4c19-87b4-269052c18879) + +### Setup Process +1. Launch a workspace that contains .py or .java files, which will trigger extension activation. +2. Accept the prompt to install the build server in the repo +3. Go to the "Testing" ![image](https://github.com/uber/vscode-bazel-bsp/assets/92764374/536205bd-6908-4184-9620-292aa2dfe7f6) panel in VS Code +4. Adjust the project scope. See "Adjusting Project Scope" section below. +5. Let the sync process complete. See "Sync Process" section below. + +### Adjusting Project Scope +1. Open Project View file: click on the file icon next to the "Bazel Test Targets" root test item + ![image](https://github.com/uber/vscode-bazel-bsp/assets/92764374/795baab9-ec42-4b7d-9b1a-2e4033731b64) +2. Adjust Targets: In the .bazelproject file that launches, specify one or more target patterns to be included in the sync scope +3. Click the "Refresh Tests" Button: Wait for the sync process to complete. + + ![image](https://github.com/uber/vscode-bazel-bsp/assets/92764374/bdbf80ad-485f-464b-b728-cdd86c42f0e5) + +### Sync Process +1. Expand root test item: When the root item is initially expanded, the sync process will begin. + + ![image](https://github.com/uber/vscode-bazel-bsp/assets/92764374/555c29b5-2f47-4e24-b24b-f6dea4f0df85) + +3. Wait for sync: Give the initial sync time to complete, during which the message below will be displayed. + + ![image](https://github.com/uber/vscode-bazel-bsp/assets/92764374/6fdd8643-bf53-42f2-8075-b312f00dfd30) + +3. View progress: Check on sync progress via the output channel + + ![image](https://github.com/uber/vscode-bazel-bsp/assets/92764374/deb6491d-3b74-4e0a-a38e-2ea68b544f70) + +### Resync Process +1. Make modifications: Examples of actions that will require a resync include... + - Creating and removing targets + - Adding/deleting files + - Moving files between targets + - Switching between branches where the above are different +2. Click "Refresh Tests" button: Wait for the sync process to complete. + +### Browsing Test Cases +1. Ensure sync process is completed above. +2. Expand a test target + + ![image](https://github.com/uber/vscode-bazel-bsp/assets/92764374/354ef789-31fa-4113-975f-b262c10302e3) + + +4. Give the test cases a moment to load, then browse through individual test cases in the tree + + ![image](https://github.com/uber/vscode-bazel-bsp/assets/92764374/36efcc43-30ba-4a78-9032-0db38a51ce80) ![image](https://github.com/uber/vscode-bazel-bsp/assets/92764374/01f52a36-3833-486f-9bde-c9ec9fdb110d) + +6. Hover over a test item, and click the file icon to jump to the corresponding location in the file + + ![image](https://github.com/uber/vscode-bazel-bsp/assets/92764374/f3dfe88f-c8b8-4468-bee2-45549c53a4fb) + + +8. Run arrow is also available within the test file +9. Jump to the test item in the tree by right clicking on the run arrow and clicking "Reveal in Test Explorer" + + ![image](https://github.com/uber/vscode-bazel-bsp/assets/92764374/e13d4d45-f101-4ca4-94f1-6b69a26c583e) + +### Modifying Test Cases (within a file) +1. Make changes in the file and save +2. Test arrow will appear next to the new or renamed item + +### Running a Test +Run a test case via one of the following available locations: +- Test Document Gutter: arrow next to each test case +- Test Explorer Tree: arrow next to teach test item +- Right-click context menu: options vary based on location in document + +To run with coverage, use the "Run with Coverage" option appearing next to the run arrow. + +### Key Settings +- `bazelBinaryPath`: If you have a specific Bazel binary to be used, set it here. This will only be used when generating a new .bazelproject file to set the bazel_binary field. +- `bazelProjectFilePath`: If you already have an existing project view file that you would prefer to use, point this setting to that location instead. Be sure to reinstall the BSP server (Cmd+Shift+P → Install BSP Server) and reload the window to begin indexing based on the updated file. +- `serverInstallMode`: Can be set to 'Auto' to install automatically in a new repo. +- `serverVersion`: Determines which version of Bazel BSP will be installed. + +## FAQ +### I tried to sync, but no targets have been loaded. +- Ensure you have completed the steps in the "Getting Started" section above. +- Check your .bazelproject file. Ensure that the targets: field matches a valid Bazel target pattern, and that the bazel_binary value matches the accurate path to the repo's Bazel binary. + +### How do I ensure that I'm running tests via this extension, and not via some other extension (e.g. the main Python extension)? +- Multiple extensions may contribute to VS Code's test explorer. To ensure you're looking at tests from this specific extension, look for the "Bazel Test Targets" root item, which appears as below: + + ![image](https://github.com/uber/vscode-bazel-bsp/assets/92764374/fc353fc7-d130-45aa-b8d9-5ddb3cf32445) + +- If you see multiple root nodes, ensure you are looking at "Bazel BSP Tests". + + ![image](https://github.com/uber/vscode-bazel-bsp/assets/92764374/d9c376b8-74e8-4981-a400-ae2fb70ec2ae) + +- If a test is located under a different root node, or none, it may be coming a different extension. + + From 6ff6ec4b8a20422f9a44e96a402ff61cf0896608 Mon Sep 17 00:00:00 2001 From: Michael Noah <92764374+mnoah1@users.noreply.github.com> Date: Thu, 13 Jun 2024 15:24:53 -0400 Subject: [PATCH 2/3] Update README.md --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 287d0fe..064fc95 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# vscode-bazel-bsp README +# VS Code Bazel Build Server Protcol (BSP) Extension This extension is designed to provide integration between VS Code and Bazel BSP. It is inspired by the [New Bazel Plugin](https://lp.jetbrains.com/new-bazel-plugin/) for JetBrains products, allowing VS Code to leverage a subset of Bazel BSP as well. @@ -11,14 +11,16 @@ The initial focus will be to build out several core workflows for to integrate B - Execution of test targets and parsing/display of test results and run history - Support for debugging test targets and overlay of code coverage -In the future, we may consider exploring other areas of the Build Server Protocol and integrating them with VS Code. If you have ideas, feel free to start a discussion. +In the future, we may consider exploring other areas of the Build Server Protocol and integrating them with VS Code. We are looking for others who are interested in VS Code + BSP integration. Please feel free to reach out if you have an idea or would like to contribute. + +## Current Status +The extension is still under active development, but initial development releases are now available for install from this repo. Please see the [Getting Started](https://github.com/uber/vscode-bazel-bsp/blob/main/docs/getting_started.md) for instructions. ## Building/installing the extension 1. On the latest main branch, run `yarn package`. This will produce an extension artifact (.vsix file). 2. In VS Code's Extensions panel, navigate to the context menu (small ... at the top right of the panel), and select "Install Extension from VSIX..." 3. Select the location of the .vsix file, install it, and reload. 4. The "Testing" panel will become enabled once you open a supported file type. See activation events in the package.json for current list. -The extension is still under development - once it is end-user ready, we will offer versioned releasees on this repo and the VS Code Extension Marketplace. ## Getting Started 1. Launch this extension and open a supported file type. From 5ecc99033379c0012298705d3ceb14109c29a623 Mon Sep 17 00:00:00 2001 From: Michael Noah <92764374+mnoah1@users.noreply.github.com> Date: Thu, 13 Jun 2024 15:25:26 -0400 Subject: [PATCH 3/3] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 064fc95..8755d44 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# VS Code Bazel Build Server Protcol (BSP) Extension +# Bazel Build Server Protcol (BSP) VS Code Extension This extension is designed to provide integration between VS Code and Bazel BSP. It is inspired by the [New Bazel Plugin](https://lp.jetbrains.com/new-bazel-plugin/) for JetBrains products, allowing VS Code to leverage a subset of Bazel BSP as well.