PHPackages                             akdr/behat-github-annotations - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Testing & Quality](/categories/testing)
4. /
5. akdr/behat-github-annotations

ActiveExtension[Testing & Quality](/categories/testing)

akdr/behat-github-annotations
=============================

Extension for enabling Github action annotations for Behat

02PHP

Since Aug 19Pushed 9mo ago1 watchersCompare

[ Source](https://github.com/Akdr/behat-github-annotations)[ Packagist](https://packagist.org/packages/akdr/behat-github-annotations)[ RSS](/packages/akdr-behat-github-annotations/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)DependenciesVersions (1)Used By (0)

Behat GitHub Annotations Extension
==================================

[](#behat-github-annotations-extension)

[![PHP Version](https://camo.githubusercontent.com/6da9704adc310b64eea60cc463a5e5c8dd738da86ba6c3e2af0cfd4600621755/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253545382e302d626c75652e737667)](https://php.net)[![Behat Version](https://camo.githubusercontent.com/e72b0ff66e679be15fdb80fa485d1f718ea7006af9614842a59dd6be4c46b0f5/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f62656861742d253545332e31302d677265656e2e737667)](https://behat.org)[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)

Extension for enabling GitHub Action annotations for Behat test failures.

Automatically converts failed Behat steps into GitHub annotation format, providing inline code review feedback directly in your GitHub Actions workflow.

Features
--------

[](#features)

- 🎯 **Automatic Error Annotation**: Failed Behat steps automatically appear as GitHub annotations
- 📍 **Precise Location**: Annotations point to exact file and line where step failed
- 🔍 **Rich Context**: Includes feature, scenario, and step information
- 📊 **Verbosity Control**: Configurable detail levels including stack traces
- ⚙️ **Easy Integration**: Simple configuration with existing Behat setups
- 🚀 **GitHub Actions Ready**: Works seamlessly in CI/CD pipelines

Example Output
--------------

[](#example-output)

When a Behat step fails, this extension generates GitHub annotations like:

```
::error file=features/user_login.feature,line=12,title=Failed: I enter invalid credentials (in Invalid Login: User Authentication)::Invalid username or password provided
```

This appears in your GitHub Actions workflow as inline annotations on the failing lines.

Installation
------------

[](#installation)

Install via Composer:

```
composer require --dev akdr/behat-github-annotations
```

### Requirements

[](#requirements)

- PHP 8.2 or higher
- Behat 3.10 or higher
- GitHub Actions environment (for annotation display)
- Mago 0.26 (for linting)

Quick Start
-----------

[](#quick-start)

### 1. Basic Configuration

[](#1-basic-configuration)

Add to your `behat.yml`:

```
default:
  formatters:
    github: ~
  extensions:
    Akdr\BehatGithubAnnotations\GitHubAnnotationsExtension: ~
```

### 2. GitHub Actions Integration

[](#2-github-actions-integration)

Update your `.github/workflows/test.yml`:

```
name: Tests
on: [push, pull_request]

jobs:
  behat-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.4'
          extensions: mbstring

      - name: Install Dependencies
        run: composer install --no-dev --prefer-dist

      - name: Run Behat Tests
        run: ./vendor/bin/behat --format=github
```

### 3. Run Tests

[](#3-run-tests)

```
# Local testing
./vendor/bin/behat --format=github

# In GitHub Actions (automatic annotation display)
./vendor/bin/behat --format=github
```

Configuration
-------------

[](#configuration)

### Basic Configuration

[](#basic-configuration)

```
# behat.yml
default:
  formatters:
    github: ~
  extensions:
    Akdr\BehatGithubAnnotations\GitHubAnnotationsExtension: ~
```

### Advanced Configuration

[](#advanced-configuration)

```
# behat.yml
default:
  formatters:
    github:
      parameters:
        annotation_type: error        # error, warning, notice
        include_trace: false          # Include stack traces
        file_relative_path: true      # Use relative file paths
  extensions:
    Akdr\BehatGithubAnnotations\GitHubAnnotationsExtension: ~
```

### Output to File

[](#output-to-file)

```
# behat.yml
default:
  formatters:
    github:
      output: annotations.txt        # Save annotations to file
```

### Verbosity Levels

[](#verbosity-levels)

```
# Basic output
./vendor/bin/behat --format=github

# Verbose output (enhanced error details)
./vendor/bin/behat --format=github -v

# Very verbose output (includes stack traces)
./vendor/bin/behat --format=github -vv
```

Examples and Integration Guides
-------------------------------

[](#examples-and-integration-guides)

### 📁 Complete Examples

[](#-complete-examples)

This repository includes comprehensive examples in the [`examples/`](examples/) directory:

- **[Example Configuration](examples/behat.yml)** - Complete Behat configuration with multiple profiles
- **[Sample Features](examples/features/)** - Real-world test scenarios demonstrating the formatter
- **[GitHub Actions Workflows](examples/.github/workflows/)** - Production-ready CI/CD examples
- **[Step-by-Step Guide](examples/README.md)** - Detailed integration instructions

### 🚀 Quick Integration

[](#-quick-integration)

Copy the example configuration to get started quickly:

```
# Copy example configuration
cp examples/behat.yml your-project/behat.yml

# Copy GitHub Actions workflow
cp examples/.github/workflows/basic-behat.yml .github/workflows/tests.yml
```

### Integration Patterns

[](#integration-patterns)

#### With Multiple Formatters

[](#with-multiple-formatters)

```
# behat.yml - Use alongside other formatters
default:
  formatters:
    pretty: ~                       # Standard console output
    junit:                          # JUnit XML for CI
      filename: test-results.xml
    github: ~                       # GitHub annotations
```

#### With Different Environments

[](#with-different-environments)

```
# behat.yml
default:
  # Default configuration for local development

ci:
  # CI-specific configuration
  formatters:
    github: ~
  extensions:
    Akdr\BehatGithubAnnotations\GitHubAnnotationsExtension: ~
```

#### GitHub Actions Matrix Testing

[](#github-actions-matrix-testing)

See [examples/.github/workflows/advanced-testing.yml](examples/.github/workflows/advanced-testing.yml) for a complete workflow that includes:

- Multi-PHP version testing
- Test artifact collection
- Coverage reporting
- Deployment simulation

Troubleshooting
---------------

[](#troubleshooting)

### Common Issues

[](#common-issues)

#### Annotations Not Appearing

[](#annotations-not-appearing)

**Problem**: GitHub annotations not visible in Actions

**Solutions**:

- Ensure you're using `--format=github` in your command
- Verify the extension is properly loaded in `behat.yml`
- Check that tests are actually failing (annotations only show for failures)

#### Deprecation Warnings

[](#deprecation-warnings)

**Problem**: PHP deprecation warnings in output

**Explanation**: These warnings come from Behat core when running on PHP 8.4, not from this extension

**Solutions**:

- Warnings don't affect functionality
- Consider suppressing warnings in CI: `php -d error_reporting="E_ALL & ~E_DEPRECATED"`

#### File Path Issues

[](#file-path-issues)

**Problem**: Incorrect file paths in annotations

**Solutions**:

- Use `file_relative_path: true` in configuration
- Ensure working directory is set correctly in CI
- Check file permissions and accessibility

### Debug Mode

[](#debug-mode)

Enable debug output to troubleshoot issues:

```
# Debug mode with maximum verbosity
./vendor/bin/behat --format=github -vvv --debug
```

### Validation

[](#validation)

Verify extension is loaded correctly:

```
# List available formatters (should include 'github')
./vendor/bin/behat --help

# Test configuration
./vendor/bin/behat --config-reference
```

API Reference
-------------

[](#api-reference)

### Configuration Parameters

[](#configuration-parameters)

ParameterTypeDefaultDescription`annotation_type`string`error`GitHub annotation type (`error`, `warning`, `notice`)`include_trace`boolean`false`Always include stack traces regardless of verbosity`file_relative_path`boolean`true`Use relative file paths in annotations### GitHub Annotation Format

[](#github-annotation-format)

This extension generates annotations in the format:

```
::type file=path,line=number,title=title::message

```

**Components**:

- `type`: Annotation type (`error`, `warning`, `notice`)
- `file`: File path where the failure occurred
- `line`: Line number of the failed step
- `title`: Descriptive title including step, scenario, and feature context
- `message`: Error message with optional stack trace

### Escaping Rules

[](#escaping-rules)

Special characters are URL-encoded according to GitHub's requirements:

- `%` → `%25`
- `\r` → `%0D`
- `\n` → `%0A`
- `,` → `%2C`

Contributing
------------

[](#contributing)

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

### Development Setup

[](#development-setup)

```
# Clone the repository
git clone https://github.com/your-org/behat-github-annotations.git
cd behat-github-annotations

# Install dependencies
composer install

# Run tests
./vendor/bin/behat

# Run with the extension itself
./vendor/bin/behat --format=github
```

### Testing

[](#testing)

The extension includes comprehensive tests:

```
# Run all tests
./vendor/bin/behat

# Run specific test features
./vendor/bin/behat tests/Behat/Features/github_annotations_formatter.feature

# Test different scenarios
./vendor/bin/behat tests/Behat/Features/background_failures.feature
./vendor/bin/behat tests/Behat/Features/multiple_failures.feature
```

License
-------

[](#license)

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

Related Projects
----------------

[](#related-projects)

- [Behat](https://behat.org/) - Behavior-driven development framework
- [GitHub Actions](https://docs.github.com/en/actions) - CI/CD platform

---

⭐ If this project helped you, please consider giving it a star on GitHub!

###  Health Score

16

—

LowBetter than 5% of packages

Maintenance42

Moderate activity, may be stable

Popularity2

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity13

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/2013e05104447568a25b58b2de04d2b64be9f8b861633363a9adb4915aab9118?d=identicon)[Akdr](/maintainers/Akdr)

---

Top Contributors

[![Akdr](https://avatars.githubusercontent.com/u/606573?v=4)](https://github.com/Akdr "Akdr (6 commits)")

### Embed Badge

![Health badge](/badges/akdr-behat-github-annotations/health.svg)

```
[![Health](https://phpackages.com/badges/akdr-behat-github-annotations/health.svg)](https://phpackages.com/packages/akdr-behat-github-annotations)
```

###  Alternatives

[phpspec/prophecy

Highly opinionated mocking framework for PHP 5.3+

8.5k551.7M682](/packages/phpspec-prophecy)[brianium/paratest

Parallel testing for PHP

2.5k118.8M754](/packages/brianium-paratest)[beberlei/assert

Thin assertion library for input validation in business models.

2.4k96.9M570](/packages/beberlei-assert)[mikey179/vfsstream

Virtual file system to mock the real file system in unit tests.

1.4k108.0M2.7k](/packages/mikey179-vfsstream)[orchestra/testbench

Laravel Testing Helper for Packages Development

2.2k39.1M32.1k](/packages/orchestra-testbench)[phpspec/phpspec

Specification-oriented BDD framework for PHP 7.1+

1.9k36.7M3.1k](/packages/phpspec-phpspec)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)