PHP Test Collections Explorer

A powerful VS Code extension for exploring, organizing, and executing PHP test collections with comprehensive Docker support. ⚠️ IMPORTANT: This extension ONLY works with workspace settings. User settings are ignored.

✨ Features

• 📁 Collection Organization - Group your tests by folders (Unit, Feature, Integration...)
• 🏷️ Group by Tags - Accordion view grouped by PHPUnit @group annotations, with one-click toggle
• 🎯 Granular Execution - Run individual tests, files, groups, or complete collections
• 🔗 Direct Navigation - Click on any test to open the file at the exact line
• 🐳 Native Docker Support - Seamless execution in containers with automatic command transformation
• 📊 Visual Status - Icons for passed/failed/running tests with detailed error information
• 🔍 Error Details - Complete visualization of PHP failures and errors
• ⚡ Smart Cache - Optimized scanning with automatic updates
• 📋 Complete Logging - All commands tracked in dedicated Output tab
• 🖥️ Terminal Management - Intelligent terminal reuse and cleanup

🚀 Quick Start

1. Install: Download php-test-collections-explorer-0.1.0.vsix
2. VS Code: Ctrl+Shift+P → Extensions: Install from VSIX...
3. Open a PHP project with tests
4. View: "PHP Test Collections" appears automatically in the Test tab

Install by script

#Run in your terminal
chmod +x install.sh
./install.sh

🎮 Usage

Intuitive Tree View

Default: grouped by @group tags

📚 Unit Tests
├── 🏷️ auth                     ▶ Run group
│   └── UserTest.php
│       ├── ✅ testLogin         👈 Click to jump to test line
│       └── ❌ testFailedLogin
├── 🏷️ database                  ▶ Run group
│   └── DatabaseTest.php
│       └── ⚪ testQuery
└── 🏷️ Ungrouped                 ▶ Run group
    └── GenericTest.php
        └── ⚪ testSomething

Toggle off ($(list-tree) button): flat file view

📚 Unit Tests
├── UserTest.php
│   ├── ✅ testLogin
│   └── ❌ testFailedLogin
└── DatabaseTest.php
    └── ⚪ testQuery

Quick Navigation: Click any test method to open the file and jump directly to the test's line!

Simple Configuration

{
  "phpTestCollections.collections": [
    {
      "name": "Unit Tests",
      "path": "tests/Unit",
      "command": "vendor/bin/phpunit tests/Unit",
      "useDocker": false
    },
    {
      "name": "Docker Integration",
      "path": "tests/Integration",
      "command": "vendor/bin/phpunit tests/Integration", 
      "useDocker": true,
      "dockerImage": "my-app"
    }
  ],
  "phpTestCollections.logLevel": "info"
}

Execution Types

Action	Result	Generated Command
👆 Click test name	Opens file at test line	Direct navigation
▶️ Individual test	testLogin only	--filter "UserTest::testLogin"
▶️ Complete file	All tests in file	--filter "UserTest"
▶️ Group	All tests in @group	--group "auth"
▶️ Collection	Entire test suite	Full command

🐳 Docker Support

Automatic command transformation:

• Local: vendor/bin/phpunit --filter "UserTest" tests/Unit/UserTest.php
• Docker: docker exec my-app vendor/bin/phpunit --filter "UserTest" tests/Unit/UserTest.php

📊 Test Status

Icon	Status	Description
✅	Passed	Test successful
❌	Failed	Assertion failed
💥	Error	PHP error
🔄	Running	Executing
⚪	Unknown	Not tested

🔧 Advanced Configuration

Group by Tags

The tree view groups tests by their PHPUnit @group annotations by default. Add @group tags to your test methods:

/**
 * @test
 * @group auth
 */
public function testLogin() { ... }

/**
 * @group database
 * @group slow
 */
public function testComplexQuery() { ... }

The toolbar shows two states:

• $(tag) active — grouping ON, click to disable
• $(list-tree) inactive — grouping OFF, click to enable

Persist the preference in your workspace settings:

{
  "phpTestCollections.groupTestsByGroups": true
}

Test File Detection: Pattern vs. Inheritance

By default, the extension detects test files by filename pattern (e.g., *Test.php). For more flexible detection, enable inheritance-based detection using testBaseClasses:

{
  "phpTestCollections.collections": [
    {
      "name": "Unit Tests",
      "path": "tests/Unit",
      "command": "vendor/bin/phpunit tests/Unit",
      "pattern": "*Test.php",
      "testBaseClasses": ["TestCase", "CustomBaseTest"]
    }
  ]
}

How it works:

• ✅ Files matching the pattern are detected first (optimized)
• ✅ Files NOT matching the pattern are scanned for inheritance from specified base classes
• ✅ Both pattern and inheritance results are merged (no duplicates)
• ✅ Default frameworks (PHPUnit, Laravel, Symfony) are auto-detected

Examples:

// Detected by pattern
class UserTest extends TestCase { }

// Detected by inheritance (even without "Test" in filename!)
class GetSubscribersFlow extends TestCase { }

// Detected by inheritance from custom base
class PaymentProcessing extends CustomBaseTest { }

Laravel Project

{
  "phpTestCollections.collections": [
    {
      "name": "Feature Tests",
      "path": "tests/Feature",
      "command": "vendor/bin/phpunit --testsuite=Feature"
    },
    {
      "name": "Unit Tests", 
      "path": "tests/Unit",
      "command": "vendor/bin/phpunit --testsuite=Unit"
    }
  ]
}

Docker Compose

{
  "name": "Tests Container",
  "path": "tests",
  "command": "vendor/bin/phpunit",
  "useDocker": true,
  "dockerImage": "my-project_app"
}

Symfony Project

{
  "phpTestCollections.collections": [
    {
      "name": "Unit Tests",
      "path": "tests/Unit",
      "command": "vendor/bin/phpunit tests/Unit"
    },
    {
      "name": "Integration Tests",
      "path": "tests/Integration", 
      "command": "vendor/bin/phpunit tests/Integration"
    }
  ]
}

📋 Logs and Debugging

Output System

• Output Tab: "PHP Test Collections"
• Configurable Levels: error | warn | info | debug
• Real-time Filtering: Only relevant messages displayed
• Traced Commands with timestamps
• Detailed Docker errors

Logging Levels

• 🔴 Error: Critical failures only
• 🟡 Warning: + Configuration issues
• 🔵 Info: + Test execution (default)
• 🟣 Debug: + Internal operations

Logging Configuration

Control the verbosity of extension output with configurable logging levels:

{
  "phpTestCollections.logLevel": "info"
}

Level	Description	Output
"error"	Critical errors only	❌ Fatal errors, crashes
"warn"	Errors + warnings	❌ + ⚠️ Configuration issues, missing files
"info"	Standard output (default)	❌ + ⚠️ + ℹ️ Test execution, cache operations
"debug"	Verbose development mode	❌ + ⚠️ + ℹ️ + 🔍 Internal operations, parsing details

Examples:

• Production: "error" - Only critical issues
• Development: "debug" - Full diagnostic information
• CI/CD: "warn" - Balanced output for automation
• Default: "info" - Perfect for daily usage

Quick Actions

• Force refresh: 🔄 Button
• Change log level: VS Code Settings → "PHP Test Collections"
• View logs: Output → "PHP Test Collections"

🛠️ Development

# Clone the repo
git clone [your-repo]
cd Tests-vs-ext

# Install dependencies
npm install

# Compile
npm run compile

# Launch dev mode
F5 (Extension Development Host)

# Create package
vsce package

#Generate your own package
npx @vscode/vsce package

🚀 Release Management

The project includes automated CI/CD for seamless releases:

🤖 Automated Releases

# Automatic release (uses CHANGELOG.md version)
./scripts/auto-release.sh

# Or specify version manually
./scripts/auto-release.sh 1.2.3

What happens automatically:

1. ✅ Validates Git repository state
2. 📝 Updates package.json version
3. 🔨 Builds extension locally
4. 🏷️ Creates Git tag v1.2.3
5. 📤 Pushes tag to GitHub
6. 🤖 Triggers GitHub Actions CI/CD
7. 🚀 Creates GitHub release with .vsix file

📋 Manual Process

# Build package locally
./scripts/release.sh 1.2.3

# Then create and push tag
git tag v1.2.3 && git push origin v1.2.3

🔍 Monitoring

• CI/CD Status: GitHub Actions
• Releases: GitHub Releases

For complete release documentation, see RELEASE-GUIDE.md.

🎯 Use Cases

✅ PHP Developers working with PHPUnit
✅ Laravel/Symfony projects with organized tests
✅ Docker environments for integration
✅ E2E testing with complex configurations
✅ Teams needing consistency in test execution

📞 Support

• 📋 Logs: Output → "PHP Test Collections"
• 🔍 Debugging: Check the usage guide
• 🐛 Issues: Create an issue

🏗️ Architecture

Modular Design (6 Services)

• 📁 types/: Centralized TypeScript interfaces
• 📝 LoggingService: Configurable logging system with 4 levels (113 lines)
• 💾 CacheService: JSON cache management (228 lines)
• 🚀 TestRunner: PHPUnit execution engine (492 lines)
• 🔍 TestParser: PHP parsing with dual detection (190 lines)
• 👁️ FileWatcher: Real-time file monitoring (202 lines)

Performance Metrics

• Code Reduction: 68% (1877 → 595 lines in main file)
• Bundle Size: 85.3 KiB (optimized)
• Cache System: Workspace-specific JSON persistence
• Compilation: Zero TypeScript errors

📚 Documentation

• Complete User Guide
• Docker Configuration
• Troubleshooting

🔗 Requirements

• VS Code ^1.105.0
• PHP project with PHPUnit tests
• Optional: Docker for containerized execution

---

🚀 Transform your PHP testing workflow with a powerful visual interface!