Bitbucket Helper

The Bitbucket Helper is a Visual Studio Code extension designed to streamline the management of API workspaces within Bitbucket repositories. It provides tools to create and manage API definitions, generate test cases, and interact with Git repositories hosted on Bitbucket. With a user-friendly interface, including a project visualizer, properties viewer, and wizards for API and test case creation, this extension enhances productivity for developers working on API-driven projects.

Features

Workspace Management:

• Create new workspaces by cloning Bitbucket repositories or open existing local repositories.
• Organize APIs into layers (e.g., camara, 3gpp) within a structured workspace.
• Save and publish workspace changes to Bitbucket using Git operations.

API Management:

• Add, edit, or delete Northbound (NB), Southbound (SB), and Directed Acyclic Graph (DAG) API definitions in YAML format.
• Use the API Wizard to import or create NB APIs and select SB APIs for integration.
• Visualize APIs in a tree view (Catalogue) with status indicators for unsaved, saved, or published changes.

Test Case Management:

• Create and edit unit test cases for APIs using the Unit Testcase Wizard.
• Run test cases and view execution results in an output channel.
• Organize test cases in a dedicated Testcases folder structure.

Git Integration:

• Perform Git operations (add, commit, push) directly from VS Code to manage repository changes.
• Generate patches for workspace changes and apply them via a server endpoint.

Properties Viewer:

• Inspect and edit workspace configurations (e.g., source branch, server address) and API metadata.

Change Tracking:

• Monitor file changes with visual indicators in the Catalogue view for unsaved or unpublished changes.
• Refresh the workspace to reflect the latest repository state.

Prerequisites

To use the Bitbucket Helper extension, ensure the following are installed and configured:

• Visual Studio Code: Version 1.98.0 or higher.
• Node.js: Version 20.x or higher (required for compiling the extension).
• Git: Installed and configured with access to your Bitbucket repositories.
• TypeScript: Installed globally (npm install -g typescript) or locally for compiling the extension.
• Bitbucket Account: A Bitbucket account with appropriate repository access permissions.
• Server Requirements:
  • A running server (e.g., at http://:5000) to handle API generation, test case verification, and patch application.
  • Ensure the server supports endpoints like /generate-multiple-southbounds, /generate-dag, /apply-patch, and /verify.
• Workspace Structure: A Git repository with a .metadata/config.json file containing sourceBranch, workspaceName, gitAddress, targetFolder, and serverAddress.

Installation

Install from VS Code Marketplace (if published):

1. Search for Bitbucket Helper in the VS Code Extensions view (Ctrl+Shift+X or Cmd+Shift+X).
2. Click Install.

Manual Installation (for development or testing):

1. Clone the extension repository from Bitbucket:

   git clone <your-bitbucket-repo-url>
   cd bitbucket-helper
   

2. Install dependencies:

   npm install
   

3. Compile the extension:

   npm run compile
   

4. Open the project in VS Code:

   code .
   

5. Press F5 to launch the extension in a VS Code Extension Development Host.

Compiling and Running Locally

To compile and run the Bitbucket Helper extension for development:

Set Up the Development Environment:

1. Ensure Node.js (20.x) and TypeScript are installed.
2. Clone the repository and navigate to the project folder:

   git clone <your-bitbucket-repo-url>
   cd bitbucket-helper
   

3. Install dependencies:

   npm install
   

Compile the Extension:

1. Run the compile script to transpile TypeScript to JavaScript:

   npm run compile
   

2. Alternatively, use watch mode to recompile on changes:

   npm run watch
   

Run the Extension:

1. Open the project in VS Code (code .).
2. Press F5 to start debugging. This opens a new VS Code window (Extension Development Host) with the extension loaded.
3. Alternatively, package the extension as a .vsix file for manual installation:

   npm install -g @vscode/vsce
   vsce package
   

4. Install the generated .vsix file in VS Code via the Extensions view (... > Install from VSIX).

Test the Extension:

1. Run the test suite to verify functionality:

   npm run test
   

2. Ensure your Bitbucket repository and server are accessible for testing workspace creation and API operations.

Using Bitbucket Helper

Follow these steps to use the Bitbucket Helper extension from start to end:

Open or Create a Workspace:

1. Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P) and select Bitbucket Helper: Open Workspace.
2. Choose to:
   • Create a New Workspace: Clones a Bitbucket repository, sets up a new branch, and initializes the workspace structure (NB, SB, DAG, Testcases folders).
   • Open an Existing Workspace: Select a local folder with a cloned Bitbucket repository.
3. The workspace appears in the Catalogue view under the API Workspace container in the Activity Bar.

Configure Workspace Settings:

1. In the Properties view, review or edit workspace settings (e.g., sourceBranch, serverAddress) stored in .metadata/config.json.
2. Ensure the serverAddress points to a running server for API generation and test case execution.

Manage APIs:

1. Add an API:

   • Right-click a layer in the Catalogue view and select Add API.
   • Use the API Wizard to:
     • Import a Northbound (NB) YAML file or create a new API definition.
     • Select Southbound (SB) APIs from the workspace's metadata (lookup.csv).
     • Generate DAG files if SB APIs are selected.
   • The wizard saves NB, SB, and DAG files to the appropriate folders (NB/, SB/, DAG/).

2. Edit an API:

   • Open NB, SB, or DAG files from the Catalogue view and modify them.
   • Changes are tracked as "unsaved" until saved to the repository.

3. Delete an API:

   • Right-click an API in the Catalogue view and select Delete API to remove its NB, SB, DAG, and test case files.

Create and Run Test Cases:

1. Create a Test Case:

   • Right-click an API in the Catalogue view, select Show API Actions, and choose Add Test Case.
   • Use the Unit Testcase Wizard to define:
     • Test case title, request body, and parameters.
     • Expected responses for SB APIs (auto-populated from server data if available).
     • Storage context and log level.
   • Save the test case to Testcases/<layer>/<apiName>/<testcase>.yaml.

2. Run a Test Case:

   • Right-click a test case file in the Catalogue view or use the Run Test Case icon in the editor title bar for .yaml files in the Testcases folder.
   • View execution results in the Testcase Runner output channel.

Save and Publish Changes:

1. Save Workspace:

   • Click the Save Workspace icon in the Catalogue view to commit changes to the local repository and push to Bitbucket.
   • A patch file is generated for the changes.

2. Publish Changes:

   • Click the Publish icon to send the patch to the configured server (/apply-patch endpoint).
   • Published changes clear the "saved but not published" status in the Catalogue view.

Refresh and Monitor Changes:

• Use the Refresh icon to update the Catalogue view with the latest repository state.
• The extension tracks file changes (.yaml, .yml, .json, .csv) and displays status indicators (orange for unsaved, green for saved, none for published).

Extension Settings

The Bitbucket Helper extension does not currently contribute user-configurable settings. All configurations are stored in the workspace's .metadata/config.json file, including:

• sourceBranch: The source branch for the workspace (e.g., main).
• workspaceName: The name of the workspace (used as the branch name).
• gitAddress: The Bitbucket repository URL.
• targetFolder: The local folder for the workspace.
• serverAddress: The server address for API generation and test case execution.

Edit these settings via the Properties view or directly in config.json.

Known Issues

• Server Dependency: The extension requires a running server for API generation, test case verification, and patch application. Ensure the server is accessible at the configured address.
• Git Authentication: Push operations may fail if Git credentials are not properly configured for Bitbucket.
• File Path Handling: Windows paths with backslashes may cause issues in some operations; ensure consistent use of forward slashes in configurations.
• Test Case Execution: Test cases require valid NB, SB, and DAG files and a compatible server setup (/verify endpoint).
• CSV Parsing: Malformed lookup.csv files may cause errors in the API Wizard; ensure the CSV follows the expected format.

Report issues or contribute fixes via the Bitbucket repository.

Release Notes

0.0.6 (Current)

• Enhanced API Wizard for importing and creating NB APIs with SB selection.
• Added Unit Testcase Wizard for creating and running test cases.
• Improved Git integration with patch generation and server-side patch application.
• Fixed issues with file change tracking and workspace refresh.
• Updated Catalogue view to show change status (unsaved, saved, published).

0.0.5

• Initial implementation of workspace creation and API management.
• Basic Git operations for saving and pushing changes.
• Introduced Catalogue and Properties views.

Privacy and Security

The Bitbucket Helper extension does not store Bitbucket credentials directly. Instead, it relies on Git for repository interactions, using your system's Git configuration (e.g., SSH keys or HTTPS credentials stored in .gitconfig or a credential manager). The extension communicates with a user-configured server for API generation and test case execution, sending only the necessary data (e.g., YAML content, patches) over HTTP. Ensure your server is secure and uses HTTPS in production environments.

No data is sent to third-party services, and all workspace configurations are stored locally in the .metadata folder.

Contributing

To contribute to the Bitbucket Helper extension:

1. Fork the repository on Bitbucket.
2. Create a feature branch (git checkout -b feature/my-feature).
3. Make changes and test locally (npm run compile and F5 in VS Code).
4. Commit changes (git commit -m "Add my feature") and push to your fork.
5. Create a pull request on Bitbucket.

Follow the coding style in the existing TypeScript files and ensure tests pass (npm run test).

Acknowledgments

This extension was inspired by the Visual Studio Code extension development guide (https://code.visualstudio.com/api/get-started/your-first-extension). Thanks to the VS Code team for their comprehensive documentation and tools.

Enjoy streamlined API development with Bitbucket Helper in VS Code!