Web

Retrieve HTTP Response Code in Codeception Without Verification

Learn how to use grabResponseCode() method in Codeception to handle API endpoints returning either 200 or 409 status codes without triggering verification.

1 answer• 1 view

How to retrieve HTTP response code in Codeception without triggering verification when testing API endpoints that can return either 200 or 409?

In Codeception, you can retrieve HTTP response codes without triggering verification by using the grabResponseCode() method or by accessing the response object directly. This approach is particularly useful when testing API endpoints that might return either 200 (success) or 409 (conflict) status codes based on business logic. Understanding how to properly handle multiple response scenarios is crucial for robust API testing with Codeception.

Contents

Understanding HTTP Response Codes in Codeception

When working with HTTP response codes in Codeception, it’s essential to understand the difference between verification and retrieval. The seeResponseCodeIs() method not only checks the response code but also fails the test if the expected code isn’t found. However, there are situations where you need to retrieve the response code without triggering this verification, especially when dealing with API endpoints that can return different codes based on conditions.

In API testing scenarios, particularly with RESTful services, you might encounter endpoints that return 200 when a resource is successfully created, but 409 when the resource already exists. This common pattern in API design requires a testing approach that can handle both possibilities without immediately failing the test.

The Codeception framework provides several methods to work with HTTP response codes. The most common approach involves using the REST module’s capabilities, but there are specific techniques you should employ when you need to retrieve the response code without triggering verification.

According to the official Codeception documentation, you can use various methods to handle response codes in your tests. The key is knowing when to use verification methods like seeResponseCodeIs() versus retrieval methods like grabResponseCode().

Using grabResponseCode Method

The grabResponseCode() method is specifically designed to retrieve the HTTP response code without triggering verification. This method returns the actual response code as an integer, allowing you to implement custom logic to handle different scenarios.

Here’s how you can use it in your Codeception test:

php
<?php
$I = new ApiTester($scenario);

$I->sendPOST('/api/users', ['name' => 'John Doe']);

// Retrieve the response code without triggering verification
$responseCode = $I->grabResponseCode();

// Now implement custom logic based on the response code
if ($responseCode === 200) {
 // Handle success case
 $I->seeResponseContainsJson(['message' => 'User created']);
} elseif ($responseCode === 409) {
 // Handle conflict case (user already exists)
 $I->seeResponseContainsJson(['error' => 'User already exists']);
}

This approach gives you full control over how your test responds to different HTTP status codes. The grabResponseCode() method simply retrieves the code, allowing you to implement conditional logic that makes your tests more robust and realistic.

One important thing to note is that grabResponseCode() should be called after sending the request but before any verification methods that might fail the test. This ensures you’re working with the actual response from the server.

For more complex scenarios, you might want to combine this method with other response-related methods. For instance, you could retrieve the response code and then use other methods to inspect the response body:

php
<?php
$responseCode = $I->grabResponseCode();
$responseBody = $I->grabResponse();

// Process both the code and body together
if ($responseCode === 200) {
 // Success logic
} elseif ($responseCode === 409) {
 // Conflict logic
}

This pattern is particularly useful when the response body contains additional information that helps you understand why a particular status code was returned.

Alternative Approaches for Multiple Response Codes

While grabResponseCode() is the primary method for retrieving HTTP response codes without triggering verification, there are alternative approaches you can use depending on your testing requirements and the specific modules you’re working with.

Using the REST Module’s Response Object

When using the REST module, you can access the underlying response object directly. This approach gives you more granular control over response handling:

php
<?php
$I->sendPOST('/api/users', ['name' => 'John Doe']);

// Access the response object directly
$response = $I->grabResponseObject();

// Extract the status code
$responseCode = $response->getStatusCode();

// Implement custom logic
if ($responseCode === 200) {
 // Success handling
} elseif ($responseCode === 409) {
 // Conflict handling
}

This method is particularly useful when you need additional information from the response object, such as headers or other metadata.

Using Conditional Logic with seeResponseCodeIs()

In some cases, you might want to use the standard seeResponseCodeIs() method but with conditional logic. While this approach does trigger verification, you can structure your tests to handle multiple expected codes:

php
<?php
$I->sendPOST('/api/users', ['name' => 'John Doe']);

// Try to see 200, if it fails, check for 409
try {
 $I->seeResponseCodeIs(200);
} // If it fails, catch the exception and check for 409
catch (\Exception $e) {
 $I->seeResponseCodeIs(409);
 // Handle the 409 case
}

However, this approach is less efficient than using grabResponseCode() because it requires sending an additional exception and handling it, which can make your tests slower and more complex.

Using Multiple Test Scenarios

For more complex scenarios, consider structuring your tests to handle different response codes in separate scenarios:

php
<?php
$I->sendPOST('/api/users', ['name' => 'John Doe']);

$responseCode = $I->grabResponseCode();

if ($responseCode === 200) {
 // Success scenario
 $I->seeResponseContainsJson(['message' => 'User created']);
} elseif ($responseCode === 409) {
 // Conflict scenario
 $I->seeResponseContainsJson(['error' => 'User already exists']);
}

This approach keeps your test logic clean and focused on the specific response you’re handling.

Using Custom Helper Methods

For projects that frequently test endpoints with multiple possible response codes, you can create custom helper methods to streamline your test code:

php
<?php
// In your Helper or Abstract class
public function seeResponseCodeIsOneOf($codes) {
 $actualCode = $this->grabResponseCode();
 if (!in_array($actualCode, $codes)) {
 $this->fail("Response code {$actualCode} is not one of " . implode(', ', $codes));
 }
}

// In your test
$I->sendPOST('/api/users', ['name' => 'John Doe']);
$I->seeResponseCodeIsOneOf([200, 409]);

This custom method allows you to verify that the response code is within a set of expected codes without immediately failing on the first mismatch.

Best Practices for API Testing

When implementing HTTP response code retrieval in Codeception, following best practices ensures your tests are reliable, maintainable, and effective. These practices become especially important when dealing with API endpoints that can return multiple response codes.

Use Specific Response Codes

Always use specific HTTP status codes rather than generic ones. For example, instead of checking for a generic “success” code, explicitly check for 200 (OK) or 201 (Created). Similarly, instead of a generic “error” code, check for specific codes like 409 (Conflict), 400 (Bad Request), or 422 (Unprocessable Entity).

php
<?php
// Good - specific codes
if ($responseCode === 201) {
 // Resource created
} elseif ($responseCode === 409) {
 // Conflict - resource already exists
}

// Avoid - generic codes
if ($responseCode >= 200 && $responseCode < 300) {
 // Success (too generic)
}

Combine Response Code with Response Body Validation

HTTP status codes alone don’t always tell the whole story. Always combine response code validation with response body validation to ensure you’re handling the correct scenario:

php
<?php
$responseCode = $I->grabResponseCode();
$responseBody = json_decode($I->grabResponse(), true);

if ($responseCode === 200 && isset($responseBody['user']['id'])) {
 // Success with valid user data
} elseif ($responseCode === 409 && isset($responseBody['error'])) {
 // Conflict with error message
}

This approach makes your tests more robust and ensures you’re handling the right scenarios.

Implement Proper Error Handling

When retrieving response codes, implement proper error handling to catch unexpected responses:

php
<?php
try {
 $I->sendPOST('/api/users', ['name' => 'John Doe']);
 $responseCode = $I->grabResponseCode();
 
 if ($responseCode === 200 || $responseCode === 409) {
 // Expected codes
 } else {
 // Unexpected code
 $I->fail("Unexpected response code: {$responseCode}");
 }
} catch (\Exception $e) {
 $I->fail("Request failed: " . $e->getMessage());
}

This pattern ensures that unexpected responses don’t cause your tests to fail silently.

Use Meaningful Test Names

When testing endpoints with multiple response codes, use descriptive test names that clearly indicate what you’re testing:

php
<?php
$I->wantTo("create user and handle both success (200) and conflict (409) responses");

This makes your test suite more readable and helps other developers understand the purpose of each test.

Organize Tests by Response Scenarios

Consider organizing your tests by response scenarios rather than by HTTP method. This approach groups related tests together and makes it easier to understand the expected behavior:

php
<?php
// Group tests by scenario
$I->wantTo("handle user creation with various scenarios");

// Test successful creation
$I->sendPOST('/api/users', ['name' => 'New User']);
$I->seeResponseCodeIs(200);

// Test duplicate creation
$I->sendPOST('/api/users', ['name' => 'Existing User']);
$I->seeResponseCodeIs(409);

Use Environment-Specific Testing

Different environments might return different response codes. Use environment-specific testing to handle these variations:

php
<?php
// In your suite configuration
if ($this->config['env'] === 'production') {
 // Production-specific response handling
} else {
 // Development/staging-specific response handling
}

This approach ensures your tests work correctly across different environments.

Implement Response Code Assertions

Create custom assertions for response codes to make your tests more readable and maintainable:

php
<?php
// In your custom helper
public function assertResponseCodeIs($expectedCode, $message = null) {
 $actualCode = $this->grabResponseCode();
 $this->assertEquals($expectedCode, $actualCode, $message ?: "Expected response code {$expectedCode}, got {$actualCode}");
}

// In your test
$I->assertResponseCodeIs(200); // or 409, etc.

This custom assertion provides more meaningful error messages and makes your tests more readable.

Common Issues and Solutions

When working with HTTP response codes in Codeception, you might encounter several common issues. Understanding these issues and their solutions will help you create more robust and reliable tests.

Response Code Returns N/A

One common issue is when the response code returns “N/A” instead of an actual HTTP status code. This typically happens when the request fails or when there’s a problem with the connection.

Solution:
Verify that your request is being sent correctly and that the server is responding. You can add additional checks to handle this scenario:

php
<?php
$I->sendPOST('/api/users', ['name' => 'John Doe']);
$responseCode = $I->grabResponseCode();

if ($responseCode === 'N/A') {
 // Handle connection or request failure
 $I->fail("Request failed - no response code received");
} elseif ($responseCode === 200) {
 // Handle success
} elseif ($responseCode === 409) {
 // Handle conflict
}

Response Code Not Retrieved Before Verification

Another common issue occurs when you try to retrieve the response code after calling a verification method like seeResponseCodeIs(). This can lead to inconsistent results or unexpected behavior.

Solution:
Always retrieve the response code before performing any verifications:

php
<?php
// Correct order
$I->sendPOST('/api/users', ['name' => 'John Doe']);
$responseCode = $I->grabResponseCode();

// Now perform verifications based on the code
if ($responseCode === 200) {
 $I->seeResponseContainsJson(['message' => 'User created']);
} elseif ($responseCode === 409) {
 $I->seeResponseContainsJson(['error' => 'User already exists']);
}

Handling Multiple Response Codes in Sequence

When testing endpoints that can return multiple response codes in sequence (like creating the same user multiple times), you might need to handle these scenarios in a specific order.

Solution:
Structure your tests to handle the sequence of responses appropriately:

php
<?php
// First request - should return 200 (success)
$I->sendPOST('/api/users', ['name' => 'John Doe']);
$I->seeResponseCodeIs(200);

// Second request - should return 409 (conflict)
$I->sendPOST('/api/users', ['name' => 'John Doe']);
$I->seeResponseCodeIs(409);

Response Code Changes Based on Request Parameters

In some cases, the response code might change based on the parameters sent with the request. This can make testing more complex.

Solution:
Test different parameter combinations and their expected response codes:

php
<?php
// Test with valid parameters
$I->sendPOST('/api/users', ['name' => 'John Doe', 'email' => 'john@example.com']);
$I->seeResponseCodeIs(200);

// Test with missing required parameters
$I->sendPOST('/api/users', ['name' => 'John Doe']);
$I->seeResponseCodeIs(400); // Bad Request

Handling Asynchronous Responses

For APIs that return asynchronous responses (where the initial request returns a 202 Accepted but the actual processing happens in the background), you need special handling.

Solution:
Use polling or callback mechanisms to check the final status:

php
<?php
// Initial request - returns 202 Accepted
$I->sendPOST('/api/users', ['name' => 'John Doe']);
$I->seeResponseCodeIs(202);

// Poll for completion
$attempts = 0;
$maxAttempts = 10;
while ($attempts < $maxAttempts) {
 $I->sendGET('/api/users/123/status');
 $responseCode = $I->grabResponseCode();
 
 if ($responseCode === 200) {
 // Processing complete
 break;
 } elseif ($responseCode === 202) {
 // Still processing
 sleep(2);
 $attempts++;
 } else {
 // Unexpected response
 $I->fail("Unexpected response code: {$responseCode}");
 }
}

Dealing with Rate Limiting

APIs often implement rate limiting, which can result in 429 Too Many Requests responses. This can interfere with your testing.

Solution:
Implement retry logic with exponential backoff:

php
<?php
$retries = 0;
$maxRetries = 3;
$delay = 1; // Start with 1 second delay

do {
 $I->sendPOST('/api/users', ['name' => 'John Doe']);
 $responseCode = $I->grabResponseCode();
 
 if ($responseCode === 429) {
 // Rate limited, wait and retry
 sleep($delay);
 $delay *= 2; // Exponential backoff
 $retries++;
 } else {
 break; // Success or other response
 }
} while ($retries < $maxRetries);

if ($responseCode === 429) {
 $I->fail("Rate limited even after {$maxRetries} retries");
}

Handling Authentication Issues

When authentication fails, APIs typically return 401 Unauthorized or 403 Forbidden responses. These need special handling in your tests.

Solution:
Implement proper authentication checks and handle authentication errors gracefully:

php
<?php
$I->sendPOST('/api/users', ['name' => 'John Doe']);
$responseCode = $I->grabResponseCode();

if ($responseCode === 401 || $responseCode === 403) {
 // Handle authentication error
 $I->seeResponseContainsJson(['error' => 'Authentication required']);
 // Potentially re-authenticate or adjust test setup
} elseif ($responseCode === 200) {
 // Handle success
} elseif ($responseCode === 409) {
 // Handle conflict
}

By understanding and addressing these common issues, you can create more robust and reliable tests for your API endpoints that handle various response codes effectively.

Sources

  1. HttpCode - Codeception Documentation
  2. REST - Codeception Documentation
  3. How can I retrieve the HTTP response code without actual verification? - Stack Overflow
  4. Testing 2 different status codes - Codeception GitHub Issue
  5. Codeception API testing response comes back as ‘N/A’ - Stack Overflow

Conclusion

Retrieving HTTP response codes in Codeception without triggering verification is a crucial technique for testing API endpoints that can return multiple status codes like 200 or 409. By using the grabResponseCode() method, you can implement flexible testing logic that handles different response scenarios without immediately failing on unexpected codes.

The key to effective API testing with multiple response codes lies in understanding the difference between verification and retrieval methods, implementing proper error handling, and following best practices for organizing and structuring your tests. When combined with response body validation and meaningful test organization, these techniques create robust test suites that accurately reflect the behavior of your API endpoints.

Whether you’re testing user creation endpoints that might return 200 for new users and 409 for existing users, or any other API scenario with multiple possible responses, the approaches outlined in this guide provide the foundation for reliable and maintainable Codeception tests.

Authors
NeuroAnswers
Author
Verified by moderation
NeuroAnswers
Moderation
Retrieve HTTP Response Code in Codeception Without Verification