Download the PHP package crdesign8/laratest-advisor without Composer

LaraTestAdvisor

Ultra-fast, 100% offline, AST-based (Abstract Syntax Tree) static analysis for Laravel/PHP classes that identifies and recommends robust test scenarios.

Unlike automatic generators that suffer from LLM hallucinations and incorrect mocking, LaraTestAdvisor acts as a Test Scenario Advisor. It tells you (or an AI agent) what to test, why to test it, which risk to protect against, and provides the exact anti-hallucination AI prompt signature to create the correct Pest PHP test.

Key Features

• Offline & AST-Only: No Laravel framework booting, no database access, and no side effects. Uses nikic/php-parser v5 to purely analyze the file structure.
• Multi-Candidate Classification: Scores the likelihood of a PHP class fitting into major Laravel patterns (Actions, Form Requests, Policies, Controllers, Models, etc.) with confidence scoring.
• Double-Risk Assessment Model: Evaluates both the overall class risk (Complexity, Coupling, Dependencies) and each individual scenario's risk independently.
• Top 8 Rules Engine: Focused analysis on:
  • Happy Path (basic flow)
  • Sad Path (throw exceptions and try/catch)
  • Boundary Conditions (logical limits <= or >=)
  • Form Requests (robust validation)
  • Authorization (Policies and Gates)
  • Database Transactions (DB::transaction and rollback)
  • Events & Queues (dispatched events and jobs)
  • Database Writes (Eloquent/Query Builder persistence)
• Suppressions Engine: Ignore recommendations using native PHP 8 attributes (#[TestAdvisorIgnore]), inline comments (// laratest-advisor-ignore), or local YAML configuration profiles.
• Anti-Hallucination Prompting: Generates a tailored structured AI prompt containing the original source code and mapped scenarios, forcing the AI to create bulletproof Pest tests.
• Multiple Output Formats: Styled terminal output via Termwind, structured JSON with official Schema validation, or detailed Markdown reports.

Technical Documentation

The advisor's internal architecture, rules engine, risk model, suppressions, and scenario consolidation are documented in docs/architecture.md. The official contract for creating and evolving rules is documented in docs/rules-contract.md.

Installation & Setup

Prerequisites

• PHP >= 8.2
• Composer

Step by Step

1. Clone the project and install dependencies:

2. Make the CLI executable executable:

Usage

To analyze any class or PHP file from your Laravel application:

1. Default Terminal Output (Styled)

Terminal output:

2. Export as Structured JSON (Per Official Schema)

You can specify a destination file using -o or --output-file:

3. Export Detailed Markdown Report

4. Generate the Ideal Prompt for AI to Create Tests

Configuring Suppressions

LaraTestAdvisor supports three ways to granularly silence warnings or irrelevant scenarios:

1. Native PHP 8 Attribute

Use the #[TestAdvisorIgnore] attribute passing the rule ID at class or method scope:

2. Inline Comment

Insert an inline comment immediately before or inside the method:

3. YAML Configuration Profile (laratest-advisor.yaml)

Create a laratest-advisor.yaml file at the root of your project to disable rules on specific files:

Running the Project's Tests

The official local validation commands are centralized in the Makefile:

• make test runs the Pest test suite.
• make analyse runs PHPStan with the phpstan.neon configuration.
• make check runs the full local gate: tests, static analysis, and architecture validation when tests exist in tests/Architecture.
• make precommit is an alias for make check for use in local hooks.

Suite organization

• tests/Unit/Parser/ covers parsing, classification, and metadata extraction.
• tests/Unit/Inference/ covers suppressions and scenario consolidation.
• tests/Unit/Scorer/ covers the risk model.
• tests/Unit/Formatter/ covers output serialization.
• tests/Feature/CLI/ covers the analyze command.
• tests/Fixtures/ contains the input files used by the suite.

To run LaraTestAdvisor's internal quality tests directly with Pest:

All tests validate real engine scenarios against complex fixture files (including compliance tests against the official JSON Schema located at resources/schema/analysis-result.schema.json).

License

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

Changelog

See CHANGELOG for the release history.

Contributing

See CONTRIBUTING for development setup and guidelines.