Gauge Python Build Plugin

A comprehensive Python build plugin for Gauge testing framework, inspired by the Gauge Gradle Plugin. This plugin provides seamless integration with UV, Poetry, setuptools, and standalone CLI functionality for running Gauge specifications in Python projects.

Quick Start

# Install from PyPI
pip install gauge-pybuild-plugin

# Run your Gauge specs
gauge-py run

# Or use with UV for faster performance
uv pip install gauge-pybuild-plugin
uv run gauge-py run --parallel --nodes=4

Features

🚀 Multiple Integration Options: UV, Poetry plugin, setuptools commands, and standalone CLI
⚡ Parallel Execution: Run specs in parallel with configurable worker nodes
🏷️ Tag-based Filtering: Execute specific specs using tag expressions
🌍 Environment Support: Run against different environments (dev, test, prod, etc.)
⚙️ Flexible Configuration: TOML-based configuration with sensible defaults
🔧 Validation & Formatting: Built-in project validation and spec formatting
📦 Plugin Management: Install and manage Gauge plugins
🎯 Gradle-like Experience: Similar API and workflow as the Gradle plugin
🦀 Modern Tools: Support for UV (Rust-based, 10-100x faster than pip)

Prerequisites

Before using this plugin, you need:

Gauge Framework installed on your system:

# macOS
brew install gauge

# Windows (using Chocolatey)
choco install gauge

# Linux
curl -SsL https://downloads.gauge.org/stable | sh

Verify installation: gauge version

Gauge Python Plugin installed:
```
gauge install python
```

An existing Gauge project or create a new one:

# Create new Gauge project
gauge init python

# This creates:
# - manifest.json (Gauge project metadata)
# - specs/ (test specifications directory)
# - step_impl/ (step implementations)

⚠️ Important: This plugin must be run from within a Gauge project directory (one containing manifest.json and specs/). It enhances existing Gauge projects with build tool integration.

Installation

Quick Install from PyPI 📦

# Using pip (works everywhere)
pip install gauge-pybuild-plugin

# Using UV (recommended - 10-100x faster!)
uv pip install gauge-pybuild-plugin

# Using Poetry
poetry add gauge-pybuild-plugin

Using UV (Recommended - Fast!) ⚡

UV is a modern, Rust-based Python package manager that's 10-100x faster than pip.

# Install UV first (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install the plugin from PyPI
uv pip install gauge-pybuild-plugin

# Or add to your project
uv add gauge-pybuild-plugin

Using Poetry

poetry add gauge-pybuild-plugin

Using pip

pip install gauge-pybuild-plugin

Development Installation

# Clone the repository
git clone https://github.com/lirany1/gauge-pybuild-plugin.git
cd gauge-pybuild-plugin

# Option 1: Using UV (recommended - faster)
uv pip install -e ".[dev]"

# Option 2: Using Poetry
poetry install

Verify Installation

After installation, verify the plugin is working:

# Check if CLI is available
gauge-py --help

# In a Gauge project directory, try:
gauge-py validate

Quick Start

1. UV Integration (Modern & Fast) ⚡

UV automatically manages virtual environments and dependencies:

# Run Gauge specs
uv run gauge-py run

# Run with options
uv run gauge-py run --parallel --nodes=4 --env=dev --tags="smoke"

# Validate and format
uv run gauge-py validate
uv run gauge-py format

# Install Gauge plugins
uv run gauge-py install python

2. Poetry Integration

Add the plugin to your pyproject.toml:

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

[tool.poetry]
name = "my-gauge-project"
version = "0.1.0"
description = "My Gauge project"

[tool.poetry.dependencies]
python = "^3.8"
getgauge = "^0.3.7"
gauge-pybuild-plugin = "^0.1.0"

# Gauge configuration
[tool.gauge]
specs_dir = "specs"
in_parallel = false
nodes = 1
env = "default"
additional_flags = "--verbose"

[tool.gauge.environment_variables]
gauge_reports_dir = "reports"
logs_directory = "logs"

Run Gauge through Poetry:

# Run all specs
poetry gauge run

# Run specific specs
poetry gauge run spec1.spec spec2.spec

# Run with options
poetry gauge run --parallel --nodes=4 --env=dev --tags="smoke"

# Validate project
poetry gauge validate

# Format specs
poetry gauge format

# Install plugins
poetry gauge install python

3. Setuptools Integration

Add to your setup.py:

from setuptools import setup

setup(
    name="my-gauge-project",
    version="0.1.0",
    install_requires=[
        "getgauge>=0.3.7",
        "gauge-pybuild-plugin>=0.1.0",
    ],
    entry_points={
        "distutils.commands": [
            "gauge = gauge_pybuild_plugin.setuptools_command:GaugeCommand",
            "gauge_validate = gauge_pybuild_plugin.setuptools_command:GaugeValidateCommand",
            "gauge_format = gauge_pybuild_plugin.setuptools_command:GaugeFormatCommand",
        ]
    }
)

Run through setuptools:

# Run specs
python setup.py gauge

# Run with options
python setup.py gauge --parallel --nodes=4 --env=dev

# Validate and format
python setup.py gauge_validate
python setup.py gauge_format

4. Standalone CLI

Install the plugin and use the CLI directly:

# Run specs
gauge-py run

# Run with configuration
gauge-py run --specs-dir=specs --parallel --nodes=4 --env=dev

# Other commands
gauge-py validate
gauge-py format
gauge-py install python
gauge-py config --init

Configuration Options

The plugin supports all the configuration options from the Gradle plugin, with Python-friendly naming:

Option	CLI Flag	Description	Default
`specs_dir`	`--specs-dir`	Gauge specs directory path	`"specs"`
`tags`	`--tags`	Filter specs by tags expression	`None`
`in_parallel`	`--parallel`	Execute specs in parallel	`false`
`nodes`	`--nodes`	Number of parallel execution streams	`1`
`env`	`--env`	Gauge environment to run against	`None`
`additional_flags`	`--additional-flags`	Additional gauge flags	`None`
`project_dir`	`--project-dir`	Path to gauge project directory	Current directory
`gauge_root`	`--gauge-root`	Path to gauge installation root	Auto-detected
`environment_variables`	N/A	Additional environment variables	`{}`

Configuration File Examples

Basic Configuration

[tool.gauge]
specs_dir = "specs"
in_parallel = false
nodes = 1
env = "default"

Advanced Configuration

[tool.gauge]
specs_dir = "specifications"
in_parallel = true
nodes = 4
env = "ci"
additional_flags = "--simple-console --verbose"
gauge_root = "/opt/gauge"

[tool.gauge.environment_variables]
gauge_reports_dir = "custom/reports"
logs_directory = "custom/logs"
screenshot_on_failure = "true"

Multiple Environment Configurations

# Default configuration
[tool.gauge]
specs_dir = "specs"
in_parallel = false
nodes = 1

# Development environment
[tool.gauge.environments.dev]
env = "dev"
additional_flags = "--verbose"

# CI environment  
[tool.gauge.environments.ci]
env = "ci"
in_parallel = true
nodes = 4
additional_flags = "--simple-console"

Usage Examples

UV Examples (Fast & Modern) ⚡

# Basic execution
uv run gauge-py run

# Parallel execution
uv run gauge-py run --parallel --nodes=4

# Tag-based execution
uv run gauge-py run --tags="smoke & !slow"

# Environment-specific execution
uv run gauge-py run --env=dev

# Specific specs
uv run gauge-py run specs/login.spec specs/checkout.spec

# Combined options
uv run gauge-py run --parallel --nodes=8 --env=ci --tags="regression"

Poetry Examples

# Basic execution
poetry gauge run

# Parallel execution
poetry gauge run --parallel --nodes=4

# Tag-based execution
poetry gauge run --tags="smoke & !slow"

# Environment-specific execution
poetry gauge run --env=dev

# Specific specs
poetry gauge run specs/login.spec specs/checkout.spec

# Combined options
poetry gauge run --parallel --nodes=8 --env=ci --tags="regression" --additional-flags="--simple-console"

CLI Examples

# Initialize configuration
gauge-py config --init

# Show current configuration
gauge-py config --show

# Run with verbose output
gauge-py --verbose run --parallel --nodes=4

# Run specific specs
gauge-py run specs/api/*.spec

# Install and manage plugins
gauge-py install python --version=0.3.7
gauge-py install html-report

Setuptools Examples

# Basic execution
python setup.py gauge

# With options
python setup.py gauge --parallel --nodes=4 --env=test

# Validation and formatting
python setup.py gauge_validate
python setup.py gauge_format

Comparison with Gradle Plugin

Feature	Gradle Plugin	Python Plugin
Build Tool Integration	✅ Gradle	✅ Poetry, setuptools
Parallel Execution	✅	✅
Tag Filtering	✅	✅
Environment Support	✅	✅
Custom Tasks	✅	✅ (via CLI/API)
Configuration	`build.gradle`	`pyproject.toml`
CLI Interface	`gradle gauge`	`gauge-py run`

Gradle vs Python Syntax

Gradle Plugin:

// build.gradle
gauge {
    specsDir = 'specs'
    inParallel = true
    nodes = 2
    env = 'dev'
    tags = 'tag1'
    additionalFlags = '--verbose'
}

// Command line
gradle gauge -PspecsDir="specs" -PinParallel=true -Pnodes=4

Python Plugin:

# pyproject.toml
[tool.gauge]
specs_dir = "specs"
in_parallel = true
nodes = 2
env = "dev"
tags = "tag1"
additional_flags = "--verbose"

# Command line
poetry gauge run --specs-dir=specs --parallel --nodes=4
gauge-py run --specs-dir=specs --parallel --nodes=4

API Reference

Core Classes

`GaugeConfig`

Configuration management class with validation and command generation.

from gauge_pybuild_plugin import GaugeConfig

config = GaugeConfig(
    specs_dir="specs",
    in_parallel=True,
    nodes=4,
    env="dev"
)

# Generate command arguments
args = config.to_command_args()
# ['--parallel', '--n', '4', '--env', 'dev', 'specs']

# Get environment variables
env = config.get_environment()

`GaugeTask`

Task execution wrapper for running Gauge commands.

from gauge_pybuild_plugin import GaugeTask, GaugeConfig

config = GaugeConfig(in_parallel=True, nodes=4)
task = GaugeTask(config)

# Run specs
success = task.run()
success = task.run(["spec1.spec", "spec2.spec"])

# Validate project
success = task.validate()

# Format specs
success = task.format_specs()

# Install plugin
success = task.install_plugin("python", "0.3.7")

`GaugePlugin`

Main plugin orchestrator with configuration loading.

from gauge_pybuild_plugin import GaugePlugin

# Load from config file
plugin = GaugePlugin("pyproject.toml")

# Create tasks
task = plugin.create_task()
task = plugin.create_task({"in_parallel": True})

# High-level operations
plugin.run_specs(in_parallel=True, nodes=4)
plugin.validate_project()
plugin.format_specs()

Contributing

Fork the repository
Create a feature branch: git checkout -b feature-name
Make your changes
Add tests: pytest tests/
Run linting: ruff check . && ruff format .
Submit a pull request

Development Setup

Using UV (Recommended - 10-100x faster):

git clone https://github.com/lirany1/gauge-pybuild-plugin.git
cd gauge-pybuild-plugin

# Install UV first
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies with dev extras
uv pip install -e ".[dev]"

# Run tests
uv run pytest

# Run linting (using Ruff - modern & fast)
uv run ruff check .
uv run ruff format .
uv run mypy src/

# Install pre-commit hooks
uv run pre-commit install

Using Poetry:

git clone https://github.com/lirany1/gauge-pybuild-plugin.git
cd gauge-pybuild-plugin

# Install dependencies
poetry install

# Run tests
poetry run pytest

# Run linting
poetry run ruff check .
poetry run ruff format .
poetry run mypy src/

# Install pre-commit hooks
poetry run pre-commit install

Troubleshooting

Common Issues

"Failed to find Gauge project directory. Missing manifest.json file"

Cause: You're not in a Gauge project directory.

Solution:

Navigate to a directory containing a Gauge project (with manifest.json)
Or create a new Gauge project: gauge init python

"specs directory 'specs' does not exist"

Cause: The Gauge project doesn't have a specs directory.

Solution:

Create the specs directory: mkdir specs
Or initialize a Gauge project properly: gauge init python

"poetry: command not found"

Cause: Poetry is not installed.

Solution:

Recommended: Use UV instead: uv run gauge-py run
Or install Poetry: curl -sSL https://install.python-poetry.org | python3 -
Or use the standalone CLI: gauge-py run

"Slow dependency installation"

Cause: Using pip or Poetry for package installation.

Solution:

Switch to UV for 10-100x faster installs:

# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh

# Use UV instead
uv pip install gauge-pybuild-plugin

"python: command not found" (when running Gauge)

Cause: Gauge expects python but your system has python3.

Solution:

# Create a symlink
sudo ln -s $(which python3) /usr/local/bin/python

# Or modify env/default/python.properties in your Gauge project

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Acknowledgments

Inspired by the Gauge Gradle Plugin
Built for the Gauge testing framework
Thanks to the Gauge community for their awesome work

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
.github		.github
examples		examples
src/gauge_pybuild_plugin		src/gauge_pybuild_plugin
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
DEVELOPMENT.md		DEVELOPMENT.md
LICENSE		LICENSE
README.md		README.md
UV_SUPPORT.md		UV_SUPPORT.md
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

Gauge Python Build Plugin

Quick Start

Features

Prerequisites

Installation

Quick Install from PyPI 📦

Using UV (Recommended - Fast!) ⚡

Using Poetry

Using pip

Development Installation

Verify Installation

Quick Start

1. UV Integration (Modern & Fast) ⚡

2. Poetry Integration

3. Setuptools Integration

4. Standalone CLI

Configuration Options

Configuration File Examples

Basic Configuration

Advanced Configuration

Multiple Environment Configurations

Usage Examples

UV Examples (Fast & Modern) ⚡

Poetry Examples

CLI Examples

Setuptools Examples

Comparison with Gradle Plugin

Gradle vs Python Syntax

API Reference

Core Classes

GaugeConfig

GaugeTask

GaugePlugin

Contributing

Development Setup

Troubleshooting

Common Issues

"Failed to find Gauge project directory. Missing manifest.json file"

"specs directory 'specs' does not exist"

"poetry: command not found"

"Slow dependency installation"

"python: command not found" (when running Gauge)

License

Acknowledgments

Support

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`GaugeConfig`

`GaugeTask`

`GaugePlugin`