fix: use urlPath for query parameter matching in WireMock requests (#2)

When queryParameters are specified in request matchers, WireMock requires
'urlPath' instead of 'url' to match the path separately from query params.

This fix:
- Adds determineUrlKey() method to automatically select correct URL matcher
- Eliminates code duplication across haveHttpStubFor, seeHttpRequest, dontSeeHttpRequest
- Respects explicit user overrides for urlPath/urlPattern
- Adds comprehensive unit tests with data provider using generators
- Updates documentation to replace docker-compose with docker run commands

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>

Author: JasonBenett

CLAUDE.md

@@ -62,9 +62,10 @@ composer cs-fix                # Fix code style issues
 
 ### WireMock Server
 ```bash
-docker-compose up -d           # Start WireMock server on port 8080
-docker-compose down            # Stop WireMock server
-docker-compose logs wiremock   # View WireMock logs
+docker run -d -p 8080:8080 wiremock/wiremock:latest   # Start WireMock server on port 8080
+docker ps | grep wiremock                             # Check if WireMock is running
+docker logs <container-id>                            # View WireMock logs
+docker stop <container-id>                            # Stop WireMock server
 ```
 
 ## Development Workflow & Conventions
@@ -249,13 +250,13 @@ modules:
 
 1. Start WireMock server:
    ```bash
-   docker-compose up -d
+   docker run -d -p 8080:8080 wiremock/wiremock:latest
    ```
 
-2. Wait for WireMock to be healthy:
+2. Wait for WireMock to be ready:
    ```bash
-   docker-compose ps
-   # Should show "healthy" status
+   curl http://localhost:8080/__admin/health
+   # Should return: {"status":"OK"}
    ```
 
 3. Run unit tests (don't require WireMock):
@@ -277,7 +278,7 @@ modules:
 
 - Use `grabAllRequests()` to see all requests made
 - Use `grabUnmatchedRequests()` to see requests that didn't match any stub
-- Check WireMock logs: `docker-compose logs wiremock`
+- Check WireMock logs: `docker logs <container-id>`
 - Near-miss analysis is automatically included in verification error messages
 
 ## Common Patterns

CONTRIBUTING.md

@@ -53,7 +53,7 @@ composer install
 ### Start WireMock Server
 
 ```bash
-docker-compose up -d
+docker run -d -p 8080:8080 wiremock/wiremock:latest
 ```
 
 Verify WireMock is running:
@@ -93,7 +93,7 @@ composer test
 Functional tests require WireMock to be running:
 
 ```bash
-docker-compose up -d
+docker run -d -p 8080:8080 wiremock/wiremock:latest
 composer test:functional
 ```
 

README.md

@@ -473,22 +473,22 @@ class ShoppingCartCest
 
 ## Local Development
 
-### Using Docker Compose
+### Using Docker
 
-The project includes a `docker-compose.yml` for easy local development:
+You can run WireMock using Docker:
 
 ```bash
 # Start WireMock
-docker-compose up -d
+docker run -d -p 8080:8080 wiremock/wiremock:latest
 
 # Check status
-docker-compose ps
+docker ps | grep wiremock
 
 # View logs
-docker-compose logs -f wiremock
+docker logs <container-id>
 
 # Stop WireMock
-docker-compose down
+docker stop <container-id>
 ```
 
 ### Running Tests
@@ -501,7 +501,7 @@ composer install
 composer test
 
 # Start WireMock
-docker-compose up -d
+docker run -d -p 8080:8080 wiremock/wiremock:latest
 
 # Build Codeception support classes
 vendor/bin/codecept build

src/JasonBenett/CodeceptionModuleWiremock/Module/Wiremock.php

@@ -138,10 +138,12 @@ public function haveHttpStubFor(
         array        $headers = [],
         array        $requestMatchers = [],
     ): string {
+        $urlKey = $this->determineUrlKey($requestMatchers);
+
         $mapping = [
             'request' => array_merge([
                 'method' => strtoupper($method),
-                'url' => $url,
+                $urlKey => $url,
             ], $requestMatchers),
             'response' => [
                 'status' => $status,
@@ -187,9 +189,11 @@ public function seeHttpRequest(
         string $url,
         array  $additionalMatchers = [],
     ): void {
+        $urlKey = $this->determineUrlKey($additionalMatchers);
+
         $pattern = array_merge([
             'method' => strtoupper($method),
-            'url' => $url,
+            $urlKey => $url,
         ], $additionalMatchers);
 
         $count = $this->grabRequestCount($pattern);
@@ -227,9 +231,11 @@ public function dontSeeHttpRequest(
         string $url,
         array  $additionalMatchers = [],
     ): void {
+        $urlKey = $this->determineUrlKey($additionalMatchers);
+
         $pattern = array_merge([
             'method' => strtoupper($method),
-            'url' => $url,
+            $urlKey => $url,
         ], $additionalMatchers);
 
         $count = $this->grabRequestCount($pattern);
@@ -608,4 +614,30 @@ private function initStreamFactory(): void
 
         $this->streamFactory = $streamFactory;
     }
+
+    /**
+     * Determine whether to use 'url' or 'urlPath' based on request matchers
+     *
+     * When queryParameters are specified in request matchers, WireMock requires
+     * 'urlPath' instead of 'url' to match the path separately from query params.
+     *
+     * @param array<string, mixed> $matchers Request matcher array
+     *
+     * @return string Either 'url' or 'urlPath'
+     */
+    private function determineUrlKey(array $matchers): string
+    {
+        // If queryParameters are present and user hasn't explicitly set urlPath/urlPattern,
+        // use 'urlPath' for path-only matching (allowing separate query param matching)
+        if (
+            isset($matchers['queryParameters'])
+            && !isset($matchers['urlPath'])
+            && !isset($matchers['urlPattern'])
+        ) {
+            return 'urlPath';
+        }
+
+        // Default to 'url' for exact URL matching
+        return 'url';
+    }
 }

tests/unit/Codeception/Module/WiremockTest.php

@@ -6,6 +6,7 @@
 
 use Codeception\Lib\ModuleContainer;
 use Codeception\Test\Unit;
+use Generator;
 use GuzzleHttp\Client;
 use GuzzleHttp\Handler\MockHandler;
 use GuzzleHttp\HandlerStack;
@@ -270,4 +271,82 @@ public function testSendClearRequestsCallsClearEndpoint(): void
         // Should not throw exception
         $this->assertTrue(true);
     }
+
+    /**
+     * Test determineUrlKey method for proper url vs urlPath selection
+     *
+     * @dataProvider urlKeyDataProvider
+     */
+    public function testDetermineUrlKey(array $matchers, string $expectedKey): void
+    {
+        $reflection = new ReflectionClass($this->module);
+        $method = $reflection->getMethod('determineUrlKey');
+
+        $result = $method->invoke($this->module, $matchers);
+
+        $this->assertSame($expectedKey, $result);
+    }
+
+    /**
+     * Data provider for testDetermineUrlKey
+     *
+     * @return Generator<string, array{matchers: array<string, mixed>, expectedKey: string}>
+     */
+    public static function urlKeyDataProvider(): Generator
+    {
+        yield 'no matchers - uses url' => [
+            'matchers' => [],
+            'expectedKey' => 'url',
+        ];
+
+        yield 'only method matcher - uses url' => [
+            'matchers' => ['method' => 'GET'],
+            'expectedKey' => 'url',
+        ];
+
+        yield 'with queryParameters - uses urlPath' => [
+            'matchers' => [
+                'queryParameters' => ['q' => ['equalTo' => 'London']],
+            ],
+            'expectedKey' => 'urlPath',
+        ];
+
+        yield 'with queryParameters and other matchers - uses urlPath' => [
+            'matchers' => [
+                'queryParameters' => ['q' => ['equalTo' => 'London']],
+                'headers' => ['Content-Type' => ['equalTo' => 'application/json']],
+            ],
+            'expectedKey' => 'urlPath',
+        ];
+
+        yield 'explicit urlPath overrides - uses url (respects user choice)' => [
+            'matchers' => [
+                'queryParameters' => ['q' => ['equalTo' => 'London']],
+                'urlPath' => '/api/weather',
+            ],
+            'expectedKey' => 'url',
+        ];
+
+        yield 'explicit urlPattern overrides - uses url (respects user choice)' => [
+            'matchers' => [
+                'queryParameters' => ['q' => ['equalTo' => 'London']],
+                'urlPattern' => '/api/.*',
+            ],
+            'expectedKey' => 'url',
+        ];
+
+        yield 'only bodyPatterns - uses url' => [
+            'matchers' => [
+                'bodyPatterns' => [['equalToJson' => '{"name":"test"}']],
+            ],
+            'expectedKey' => 'url',
+        ];
+
+        yield 'only headers - uses url' => [
+            'matchers' => [
+                'headers' => ['Authorization' => ['matches' => 'Bearer .*']],
+            ],
+            'expectedKey' => 'url',
+        ];
+    }
 }