From f873393aab7c3aade2b12d7499a7b83bab3006b1 Mon Sep 17 00:00:00 2001
From: Alex Skrypnyk <alex@drevops.com>
Date: Thu, 22 Jan 2026 19:31:50 +1100
Subject: [PATCH] Added 2 steps to clear and debug API responses.

---
 .../BehatPhpServer/ApiServerContext.php       | 43 +++++++++++++++++++
 tests/behat/features/apiserver.feature        | 34 +++++++++++++++
 2 files changed, 77 insertions(+)

diff --git a/src/DrevOps/BehatPhpServer/ApiServerContext.php b/src/DrevOps/BehatPhpServer/ApiServerContext.php
index 8393771..33a8206 100644
--- a/src/DrevOps/BehatPhpServer/ApiServerContext.php
+++ b/src/DrevOps/BehatPhpServer/ApiServerContext.php
@@ -124,6 +124,49 @@ public function resetApi(): void {
     $this->debug('API server responses and requests have been reset.');
   }
 
+  /**
+   * Clear expected responses queue in the API server.
+   *
+   * @Given (the )API has no responses
+   *
+   * @code
+   * Given the API has no responses
+   * @endcode
+   *
+   * @see https://github.com/drevops/behat-phpserver/issues/33
+   */
+  public function apiHasNoResponses(): void {
+    $response = $this->client->request('DELETE', '/admin/responses');
+
+    if ($response->getStatusCode() !== 200) {
+      throw new \RuntimeException('Failed to delete the API responses.');
+    }
+
+    $this->debug('API server responses have been cleared.');
+  }
+
+  /**
+   * Fetch debug information about API requests made.
+   *
+   * @When I debug API requests
+   *
+   * @code
+   * When I debug API requests
+   * @endcode
+   */
+  public function debugApiRequests(): void {
+    $response = $this->client->request('GET', '/admin/requests');
+
+    if ($response->getStatusCode() !== 200) {
+      throw new \RuntimeException('Failed to fetch the API requests.');
+    }
+
+    $body = (string) $response->getBody();
+
+    $message = json_encode(json_decode($body, TRUE), JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);
+    fwrite(STDOUT, "\nAPI Requests Debug Info:\n" . $message . "\n");
+  }
+
   /**
    * Put expected response data to the API server.
    *
diff --git a/tests/behat/features/apiserver.feature b/tests/behat/features/apiserver.feature
index 9b6209c..3f7451d 100644
--- a/tests/behat/features/apiserver.feature
+++ b/tests/behat/features/apiserver.feature
@@ -237,3 +237,37 @@ Feature: API Server
     Then the response status code should be 200
     And the response should contain "sample text file in the secondary fixtures directory"
     And the response header "Content-Type" should contain "text/plain"
+
+  #
+  # Admin operations
+  #
+  Scenario: Clear only responses queue without affecting received requests count
+    Given API server is running
+    And API server is reset
+    And the API will respond with JSON:
+      """
+      {"test": "response1"}
+      """
+    And the API will respond with JSON:
+      """
+      {"test": "response2"}
+      """
+    # Make a request to increment received requests count
+    When I send a GET request to "/someurl" in the API server
+    Then the API server should have 1 received request
+    And the API server should have 1 queued response
+    # Clear only responses - requests count should remain unchanged
+    Given the API has no responses
+    Then the API server should have 1 received request
+    And the API server should have 0 queued responses
+
+  Scenario: Debug API requests shows request information
+    Given API server is running
+    And API server is reset
+    And the API will respond with JSON:
+      """
+      {"status": "ok"}
+      """
+    When I send a GET request to "/test/endpoint" in the API server
+    And I debug API requests
+    Then the API server should have 1 received request