Tests Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: This package is a validation-focused test suite for Microformats parsers, not a runtime library. For a Laravel/PHP project, it serves as a compliance layer to ensure custom or third-party parsers (e.g., microformats2-php) adhere to Microformats 1/2 standards. Ideal for projects requiring structured data extraction (e.g., h-card for profiles, h-entry for posts) with verifiable accuracy.
• Laravel Synergy: Integrates seamlessly with Laravel’s testing ecosystem (PHPUnit/Pest) via data-driven assertions. The JSON/HTML test format maps cleanly to Laravel’s structured test patterns, enabling modular test execution (e.g., by microformat type or version).
• Limitation: Not a parser—requires an existing Microformats parser (PHP/JS) to validate against. Without one, this is a test-only dependency with no runtime value.

Integration Feasibility

• PHP Compatibility: Despite NPM listing, the package is PHP-compatible. Install via Composer (composer require mf2/tests) and load static files programmatically. No PHP runtime dependencies.
• Test Runner Integration:
  • PHPUnit/Pest: Use DataProvider to dynamically load test cases from the suite’s directory structure (e.g., tests/v2/h-card/*.html).
  • Custom Assertions: Compare parser output (JSON) with expected results using assertEquals or deep comparison libraries (e.g., spatie/array-sorter).
• Tooling Gaps:
  • No Built-in PHP Runner: Requires custom glue code to map HTML/JSON to PHPUnit test cases.
  • Version Awareness: Tests lack metadata for versioned parsers (e.g., v1 vs. v2). May need to filter tests manually or add version tags.

Technical Risk

• Stale Test Coverage: Last release in 2015 risks missing:
  • Microformats v2+ features (e.g., h-payment, h-resume).
  • HTML5/Modern Browser Quirks (e.g., textContent behavior in PHP vs. JS).
• Maintenance Overhead:
  • Custom integration code may fracture if the test suite format evolves (e.g., new JSON schema).
  • Forking Required: To add PHP-specific test runners or update test cases for newer microformats.
• False Positives/Negatives:
  • Parsers may fail tests due to version mismatches (e.g., v1 tests on a v2 parser).
  • Edge Cases: Tests for overlapping properties (e.g., value vs. content) may not align with modern parser logic.

Key Questions

1. Parser Strategy:
   • Which Microformats parser (PHP/JS) will this validate? Does it support the test suite’s version requirements (e.g., v1 vs. v2 rules)?
   • Example: If using microformats2-php, ensure it handles the test suite’s HTML5 textContent and date formatting rules.
2. Test Scope:
   • Should tests cover all versions (v1, v2, experimental) or a subset (e.g., only h-card for profiles)?
   • How will version conflicts be handled (e.g., v1 tests failing on a v2 parser)?
3. CI/CD Impact:
   • Will test failures block deployments or trigger manual review?
   • How will test flakiness (e.g., timing-sensitive assertions) be mitigated?
4. Performance:
   • Running ~66 tests per CI job: Will this add significant overhead (e.g., >1 minute)?
   • Can tests be parallelized (e.g., by microformat type)?
5. Long-Term Maintenance:
   • Should the project fork this repo to add PHP-specific test runners or updates?
   • How will new microformats (e.g., h-payment) be incorporated into testing?

Integration Approach

Stack Fit

• PHP/Laravel:
  • Primary Use Case: Validate custom or third-party Microformats parsers in Laravel’s test suite.
  • Tooling:
    • Composer: Install via composer require mf2/tests.
    • PHPUnit/Pest: Leverage DataProvider to load tests dynamically.
    • Custom Loader: Write a service (e.g., MicroformatsTestLoader) to recursively parse the suite’s directory structure (tests/vX.X/*/*.{html,json}).
• Alternatives:
  • Node.js: If using a JS parser (e.g., microformats.js), run tests via NPM (but adds polyglot complexity).
  • Docker: Containerize test execution if parser dependencies are complex (e.g., PHP + JS parsers).

Migration Path

1. Phase 1: Proof of Concept (1–2 Days)

   • Install the package and implement a minimal test loader:

     composer require mf2/tests
     

     // app/Services/MicroformatsTestLoader.php
     class MicroformatsTestLoader {
         public function load(string $version, string $type): array {
             $tests = [];
             $path = __DIR__ . "/../../vendor/mf2/tests/{$version}/{$type}";
             foreach (glob("{$path}/*.html") as $htmlFile) {
                 $jsonFile = str_replace('.html', '.json', $htmlFile);
                 $tests[] = [
                     'html' => file_get_contents($htmlFile),
                     'expected' => json_decode(file_get_contents($jsonFile), true),
                 ];
             }
             return $tests;
         }
     }
     

   • Run a subset of tests (e.g., h-card) against an existing parser to validate integration.

2. Phase 2: Full Integration (3–5 Days)

   • Pre-process Tests: Convert test files into Laravel’s test structure (optional, for IDE support):

     # Example script to generate test files
     php artisan make:microformats-tests
     

   • Add Test Groups: Tag tests by version/type (e.g., @microformats-v1, @h-entry) for selective execution.
   • Integrate with Parser: Ensure the parser’s output format matches the test suite’s JSON schema (e.g., textContent vs. innerText).

3. Phase 3: CI/CD (1–2 Days)

   • Add to Laravel’s phpunit.xml or Pest config:

     <!-- phpunit.xml -->
     <group name="microformats">
         <directory>tests/Feature/Microformats</directory>
     </group>
     

   • Configure CI to fail builds on test failures (or warn if parser is optional):

     # .github/workflows/tests.yml
     - name: Run Microformats Tests
       run: php artisan test --group microformats --strict
     

Compatibility

• Parser Versioning:
  • Critical Risk: Tests assume specific Microformats versions. For example:
    • v1 tests may fail on a v2 parser due to implied rules (e.g., overlapping properties).
    • Mitigation: Filter tests by version or use versioned test groups.
• HTML5 Dependencies:
  • Tests assume HTML5 textContent behavior. Modern Laravel apps (PHP 8+) should have no issues, but legacy parsers may need adjustments.
• JSON Schema:
  • Expected outputs are JSON with specific keys (e.g., rel-urls, value). Validate the parser’s output matches this schema:

    $this->assertArrayHasKey('rel-urls', $actual);
    $this->assertEqualsCanonicalizing($expected['value'], $actual['value']);
    

Sequencing

1. Dependency Installation:

   composer require mf2/tests
   

2. Test Loader Implementation:
   • Create a service to load HTML/JSON pairs (e.g., MicroformatsTestLoader).
   • Example usage:

     $loader = new MicroformatsTestLoader();
     $hCardTests = $loader->load('v2', 'h-card');
     

3. Test Execution:
   • Use PHPUnit’s DataProvider:

     use Tests\MicroformatsTestLoader;
     
     class MicroformatsTest extends TestCase {
         public function hCardProvider() {
             return (new MicroformatsTestLoader())->load('v2', 'h-card');
         }
     
         /**
          * @dataProvider hCardProvider
          */
         public function testHCardParsing(string $html, array $expected) {
             $actual = $this->parser->parse($html);
             $this->assertEquals($expected, $actual);
         }
     }
     

4. CI Setup:
   • Add to .github/workflows/tests.yml:

     jobs:
       test:
         steps:
           - run: php artisan test --group microformats --strict