Tests Laravel Package

Getting Started

Minimal Steps

1. Install the package via Composer (PHP) or NPM (Node.js):

   composer require mf2/tests
   

   or

   npm install microformats/tests --save-dev
   

2. Locate test files:

   • Tests are organized by version (v1, v2, experimental) and microformat type (h-card, h-entry, etc.).
   • Example path: vendor/mf2/tests/v2/h-card/test.html and test.json.

3. First use case:

   • Write a custom test loader to parse HTML/JSON pairs and compare against your parser’s output.
   • Example: Validate an h-card parser by loading v2/h-card/test.html and asserting its output matches test.json.

Implementation Patterns

Usage Patterns

1. Versioned Testing:

   • Group tests by microformat version (e.g., v1, v2) to avoid mixing rules.
   • Example: Skip v2 tests if your parser only supports v1.

2. Dynamic Test Loading:

   • Use a recursive directory loader to dynamically fetch all test cases:

     $testLoader = new MicroformatsTestLoader(base_path('vendor/mf2/tests'));
     $tests = $testLoader->load('v2/h-card'); // Returns [['html' => "...", 'expected' => [...]], ...]
     

3. PHPUnit DataProvider Integration:

   • Feed tests to PHPUnit for automated execution:

     public function hCardProvider() {
         return $this->testLoader->load('v2/h-card');
     }
     
     public function testHCard(array $test) {
         $actual = $this->parser->parse($test['html']);
         $this->assertEquals($test['expected'], $actual);
     }
     

4. Selective Test Execution:

   • Tag tests by microformat type (e.g., @h-entry) to run only relevant subsets in CI.

5. Date/Time Validation:

   • Enforce HTML5-compliant ISO8601 formatting in parser output (e.g., 2015-04-29 15:34Z).

Workflows

1. Parser Development:

   • Use the suite to validate incremental changes (e.g., add h-entry support by running v2/h-entry tests).

2. Regression Testing:

   • Run the full suite in CI to catch parser breaking changes.

3. Edge-Case Coverage:

   • Focus on experimental tests for cutting-edge microformats (e.g., h-payment).

Integration Tips

• Laravel Service Provider: Register the test loader as a singleton for global access:

  $this->app->singleton(MicroformatsTestLoader::class, function ($app) {
      return new MicroformatsTestLoader(base_path('vendor/mf2/tests'));
  });
  

• Artisan Command: Create a php artisan microformats:test command to run specific test groups:

  $tests = $this->loader->load('v2/h-card');
  $this->runTests($tests);
  

• JSON Schema Validation: Use spatie/array-to-xml or json_schema to validate parser output against the test suite’s schema.

Gotchas and Tips

Pitfalls

1. Version Mismatches:

   • Issue: Tests assume strict version rules (e.g., v2 implied properties don’t apply to v1).
   • Fix: Filter tests by version or document parser limitations.

2. Stale Tests:

   • Issue: Last updated in 2015; may miss newer microformats (e.g., h-payment).
   • Fix: Supplement with Microformats 2 wiki tests.

3. HTML5 Dependencies:

   • Issue: Tests expect textContent behavior; older PHP/JS environments may fail.
   • Fix: Polyfill textContent if needed (e.g., element.textContent || element.innerText).

4. False Positives:

   • Issue: Parser output may differ due to whitespace trimming or property ordering.
   • Fix: Use deepEquals (e.g., PHPUnit’s assertEquals with custom normalizers).

5. Performance:

   • Issue: Running 66+ tests in CI may slow builds.
   • Fix: Parallelize tests or run only critical subsets (e.g., @h-card).

Debugging

• Test Output Mismatch:

  • Compare parser output to expected JSON using dd() or var_dump().
  • Example:

    $actual = $this->parser->parse($html);
    dd(['actual' => $actual, 'expected' => $expected]);
    

• Parser-Specific Quirks:

  • Check if the parser trims whitespace or normalizes properties (tests use textContent).
  • Example fix:

    $normalizedOutput = array_map('trim', $actual);
    $this->assertEquals($expected, $normalizedOutput);
    

Config Quirks

• JSON File Naming:

  • Ensure HTML/JSON files have identical names (e.g., test.html + test.json).

• Date/Time Formatting:

  • Force parser output to match HTML5 profile rules:

    $this->parser->setDateFormat('Y-m-d H:i:sP'); // e.g., "2015-04-29 15:34+00:00"
    

Extension Points

1. Custom Test Formats:

   • Extend the suite by adding new HTML/JSON pairs to experimental/ and updating change-log.html.

2. Parser-Specific Adapters:

   • Write a thin layer to map test outputs to parser-specific formats (e.g., microformats2-php vs. custom parser).

3. CI Integration:

   • Use GitHub Actions to run tests on PRs:

     - name: Run Microformats Tests
       run: php artisan test --group microformats --filter "h-card"
     

4. Visual Regression Testing:

   • Combine with tools like Percy to visually validate parsed microformats in rendered HTML.