Jsonpath Compliance Test Suite Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation Add the package via Composer:

   composer require --dev jsonpath-standard/jsonpath-compliance-test-suite
   

   Ensure your project uses PHP 8.0+ (check composer.json constraints).

2. First Use Case: Validate JSONPath Implementation Run the test suite against your JSONPath library (e.g., league/json-query, mtdowling/jsonpath, or a custom implementation):

   ./vendor/bin/jsonpath-compliance-test-suite
   

   • The CLI tool generates a report comparing your library’s output against the JSONPath Internet Draft.
   • Focus on the "Compliance" section of the output to identify gaps.

3. Quick Check for Laravel Projects If using a JSONPath library in Laravel (e.g., for API responses or Eloquent queries), test it with:

   use JsonPath\JsonPath; // Example library
   $json = json_decode('{"store": {"book": [{"title": "Foo"}, {"title": "Bar"}]}}');
   $result = JsonPath::search($json, '$..book[?(@.title=="Foo")]');
   

   Run the compliance suite to ensure $..book[?(@.title=="Foo")] behaves as expected.

Implementation Patterns

Workflows for Laravel Developers

1. Integration with Testing

   • Unit Tests: Use the suite in phpunit.xml as a pre-test hook:

     <phpunit>
         <listeners>
             <listener class="JsonPathComplianceTestSuite\Listener" file="vendor/jsonpath-standard/jsonpath-compliance-test-suite/src/Listener.php"/>
         </listeners>
     </phpunit>
     

   • CI/CD: Add to GitHub Actions or GitLab CI to block non-compliant PRs:

     - name: Run JSONPath Compliance Tests
       run: ./vendor/bin/jsonpath-compliance-test-suite --format=json > compliance.json
     

2. Debugging JSONPath Queries

   • Interactive Debugging: Use the --verbose flag to see step-by-step execution:

     ./vendor/bin/jsonpath-compliance-test-suite --verbose
     

   • Focused Testing: Target specific draft sections (e.g., filters, wildcards):

     ./vendor/bin/jsonpath-compliance-test-suite --filter="filter"
     

3. Custom JSONPath Libraries

   • Mock Implementation: Create a minimal adapter for your library:

     use JsonPathComplianceTestSuite\JsonPathInterface;
     
     class LaravelJsonPathAdapter implements JsonPathInterface {
         public function search($json, $expression) {
             return json_decode(json_encode(\JsonPath::search($json, $expression)));
         }
     }
     

   • Register the adapter in composer.json autoload or via a service provider.

4. Laravel-Specific Use Cases

   • API Response Validation: Ensure JSONPath queries in routes/api.php or controllers comply:

     $response = Http::get('https://api.example.com/data');
     $filtered = jsonpath($response->json(), '$..active'); // Test with suite
     

   • Eloquent Relationships: Validate queries used in Model::whereJsonContains() or custom accessors.

Gotchas and Tips

Pitfalls

1. False Positives in Wildcard Tests

   • The suite may flag edge cases like $..* (deep search) as "non-compliant" if your library doesn’t handle circular references. Ignore these if your use case doesn’t require them.
   • Fix: Use --ignore="circular" to skip irrelevant tests.

2. PHP Type Mismatches

   • The suite expects strict type compliance (e.g., null vs. false). Libraries like league/json-query may return false for missing paths, while the draft expects null.
   • Workaround: Normalize output in your adapter:

     return is_false($result) ? null : $result;
     

3. Performance Over Compliance

   • Some draft features (e.g., recursive descent with $..) are computationally expensive. Disable them if not needed:

     ./vendor/bin/jsonpath-compliance-test-suite --exclude="recursive-descent"
     

4. Laravel Caching Quirks

   • If using JsonPath::search() in cached views or jobs, ensure the compliance suite tests the same environment (e.g., same PHP version, extensions like json).

Debugging Tips

• Isolate Failing Tests: Use --filter="expression" to narrow down issues:

  ./vendor/bin/jsonpath-compliance-test-suite --filter="$.store.book[0].title"
  

• Compare Outputs: Redirect output to files for diffing:

  ./vendor/bin/jsonpath-compliance-test-suite --format=json > my-output.json
  ./vendor/bin/jsonpath-compliance-test-suite --format=json --library=league > league-output.json
  diff my-output.json league-output.json
  

• Draft Version Mismatches: The suite defaults to the latest draft. Specify a version if your library targets an older spec:

  ./vendor/bin/jsonpath-compliance-test-suite --draft-version=02
  

Extension Points

1. Custom Test Cases Add project-specific JSONPath queries to tests/JsonPathComplianceTest.php:

   public function testCustomQuery() {
       $json = ['user' => ['roles' => ['admin', 'editor']]];
       $this->assertEquals(['admin'], $this->jsonPath->search($json, '$..roles[0]'));
   }
   

2. Hook into Laravel Events Run compliance checks on Model::saved or Job::handled:

   use JsonPathComplianceTestSuite\Runner;
   
   Event::listen('eloquent.saved', function ($model) {
       $runner = new Runner();
       $runner->runTests(); // Validate any JSONPath queries used in model logic
   });
   

3. Visual Studio Code Integration Add a task to .vscode/tasks.json for quick compliance checks:

   {
     "label": "Run JSONPath Compliance",
     "type": "shell",
     "command": "./vendor/bin/jsonpath-compliance-test-suite --format=compact",
     "problemMatcher": []
   }