BranchIQ

Demo

See BranchIQ in action:

▶️ Watch the BranchIQ Demo

BranchIQ is a VS Code extension that analyzes a Python file's structure and control-flow branches and generates a real pytest test file for it — right-click a Python file, click BranchIQ: Generate Tests, and get a starting test suite in seconds.

BranchIQ is deterministic, AST-based static analysis — not AI. It uses Python's built-in ast module to understand a file's functions, branches, loops, and exceptions, and applies a fixed set of rules to turn that structure into pytest code.

It does not call any language model, cloud service, or external API, and it never sends your code anywhere. Everything runs locally on your machine.

What it does

• Parses a Python source file with ast.parse() — no regex-based guessing.
• Detects functions, classes, methods, parameters, return statements, if/elif/else branches, loops, try/except blocks, and raised exceptions.
• Generates a pytest file with:
  • A baseline smoke test per function.
  • Targeted tests for branches whose conditions it can solve deterministically.
  • pytest.raises(...) tests for exceptions it can find a valid triggering input for.
  • Exact == assertions for trivial, side-effect-free functions where the result can be safely computed.
  • Clearly marked # TODO assertions when an expected value cannot be safely inferred.
  • Explicit @pytest.mark.skip(reason=...) scaffolds when it cannot confidently infer a triggering input.
• Writes the result to <source_directory>/tests/test_<filename>.py and opens it for you.

How it works

BranchIQ has two parts:

1. Python engine (engine/main.py, engine/analyzer.py, engine/generator.py) — performs the static analysis and test generation.

2. VS Code extension (src/extension.ts) — provides the user interface, locates a Python interpreter, runs the engine, and displays the result.

Right-click a .py file
        │
        ▼
VS Code extension (src/extension.ts)
        │
        │ finds Python interpreter
        │ locates bundled engine
        ▼
engine/main.py
        │
        ├── analyzer.py
        │
        └── generator.py
        │
        ▼
tests/test_<filename>.py

Requirements

• Python 3.10+ available on your system as python3, python, or through the interpreter selected by the Python extension.
• pytest installed in the Python environment used to run the generated tests.

BranchIQ can generate tests without pytest installed, but pytest is required to execute them.

No API keys, accounts, or paid services are required.

Installation

From a .vsix file

Once a .vsix package has been created:

1. Open VS Code.
2. Open the Extensions view.
3. Click the ... menu.
4. Select Install from VSIX...
5. Select the branch-iq-<version>.vsix file.

From the Marketplace

Once published, search for BranchIQ in the VS Code Extensions view.

Usage

1. Open a Python project in VS Code.
2. Open or right-click a .py file.
3. Run BranchIQ: Generate Tests.

You can run the command either by:

• Right-clicking the Python file in the Explorer and selecting BranchIQ: Generate Tests, or
• Opening the Command Palette with Ctrl+Shift+P and searching for BranchIQ: Generate Tests.

BranchIQ analyzes the file, generates a pytest file in a tests/ directory, and opens the generated file.

Review generated tests before relying on them, especially anything marked # TODO or @pytest.mark.skip.

Run generated tests with:

python -m pytest path/to/tests/test_yourfile.py -v

Example

Starting project:

myproject/
└── calculator.py

Right-click calculator.py and select:

BranchIQ: Generate Tests

BranchIQ generates:

myproject/
├── calculator.py
└── tests/
    └── test_calculator.py

Current limitations

BranchIQ V1 has several intentional limitations:

• Instance methods: Methods requiring construction of an object with non-trivial constructor arguments may be skipped. Static methods and class methods are supported.
• Complex conditions: Only certain simple, deterministic conditions are solved automatically. Compound conditions such as if a > 0 and b < 0 may generate a skipped test scaffold instead of a guessed input.
• Control-flow visualization: A graphical control-flow visualization is not currently included.
• Python only: BranchIQ currently analyzes Python source files.
• No symbolic execution: BranchIQ intentionally does not attempt to solve arbitrary logical expressions. It uses a fixed set of recognizable patterns so it does not fabricate inputs or expected results.

Architecture

branch-iq/
├── src/
│   └── extension.ts
│       VS Code extension
│
├── engine/
│   ├── main.py
│   │   CLI entry point and orchestration
│   │
│   ├── analyzer.py
│   │   AST-based static analysis
│   │
│   └── generator.py
│       pytest test generation
│
├── examples/
│   └── calculator.py
│       Example Python file
│
├── package.json
│   Extension manifest
│
├── tsconfig.json
│   TypeScript configuration
│
├── esbuild.js
│   Production build configuration
│
└── README.md

The Python engine has no dependency on VS Code and can also be run directly from the terminal:

python3 engine/main.py examples/calculator.py

Generated tests can then be executed with:

python3 -m pytest examples/tests/test_calculator.py -v

The TypeScript extension does not contain the analysis logic. It acts as the user-facing layer that locates and runs the Python engine.

Development

Clone the repository:

git clone https://github.com/azmi-adan/branch-iq.git
cd branch-iq

Install dependencies:

npm install

Compile the extension:

npm run compile

Run the development build:

npm run watch

Type-check the project:

npm run typecheck

You can press F5 in VS Code to launch an Extension Development Host with BranchIQ loaded for manual testing.

Packaging

The VS Code Extension Manager @vscode/vsce is included as a development dependency.

From the project root:

npm install
npx @vscode/vsce package

This runs the vscode:prepublish script, which performs the production build.

A package such as the following will be created:

branch-iq-0.0.1.vsix

The packaged extension includes the Python engine and compiled extension files required at runtime.

Build-time files such as node_modules/ and source files excluded by .vscodeignore are not included in the final VSIX package.

Publishing

To publish BranchIQ to the VS Code Marketplace:

1. Create a Marketplace publisher.
2. Configure the publisher ID in package.json.
3. Create a Personal Access Token through Azure DevOps.
4. Authenticate with vsce.
5. Publish the extension.

The repository is:

https://github.com/azmi-adan/branch-iq

The Marketplace publishing process is separate from the GitHub repository.

Icon

For Marketplace publishing, add a square PNG icon named:

icon.png

Place it in the project root:

branch-iq/
├── icon.png
├── package.json
├── README.md
└── ...

A 128×128 or larger square PNG is recommended.

Contributing

Issues and contributions are welcome.

Repository:

https://github.com/azmi-adan/branch-iq

Issues:

https://github.com/azmi-adan/branch-iq/issues

License

MIT License.

See LICENSE for the full license text.