# Using catch\_response in Locust for Custom Response Validation

The `catch_response=True` parameter in Locust allows you to evaluate the response manually and decide if the request is successful or should be marked as failed. This is particularly useful when your test criteria go beyond simple status codes. For example, you may want to ensure specific content or conditions are met in the response.

### Example Code: Validating a Response Using `catch_response`

Here’s a simple example that demonstrates the usage of `catch_response` for validating a response. In this scenario, we are making a GET request to fetch a specific "todo" item from a REST API and ensuring that the item is owned by "Christian Adams."

```python
from locust import HttpUser, constant, task

class MyReqRes(HttpUser):
    wait_time = constant(1)
    host = "http://localhost:8001"

    @task
    def get_todos(self):
        # Sending a GET request and catching the response for custom validation
        with self.client.get("/todos/104", name="test todo", catch_response=True) as resp1:
            # Checking if the response JSON contains the expected owner name
            if resp1.status_code == 200 and "Christian Adams" in resp1.json().get("name", ""):
                resp1.success()  # Mark the response as successful
            else:
                resp1.failure("Expected owner 'Christian Adams' not found.")  # Mark it as a failure

```

### Breakdown of the Code

1. **Task Definition**:
   * The `@task` decorator marks `get_todos` as a task to be executed by the simulated users.
   * The task sends a GET request to `/todos/104`.
2. **Using `catch_response`**:
   * The `with self.client.get(..., catch_response=True)` block allows you to catch and evaluate the response manually.
   * The response is checked for:
     * A status code of 200.
     * The presence of "Christian Adams" in the `name` field of the JSON response.
3. **Marking Success or Failure**:
   * If the response meets the criteria, `resp1.success()` is called.
   * If the criteria are not met, `resp1.failure()` is invoked with a descriptive message.

### Why Use `catch_response`?

1. **Custom Validation**: Go beyond basic status code validation.
2. **Detailed Metrics**: Locust records the success and failure of each request, helping you identify bottlenecks and failed scenarios.
3. **Dynamic Logic**: Easily handle complex test cases, such as validating multi-step workflows or content checks.

### Sample Output

When running this Locust test, you'll see metrics categorized as `test todo` in the Locust web interface. Success or failure counts will reflect the validation logic you’ve implemented.

### When to Cache Responses?

In some scenarios, responses might need to be reused, such as retrieving a token or reusing a user ID for subsequent requests. However, in this particular example, the task fetches data on demand without the need for caching.

### Enhancements and Next Steps

* **Parameterized Testing**: Dynamically test multiple `todo` IDs by generating random or sequential IDs in the task.
* **Error Handling**: Add handling for scenarios like server timeouts or malformed JSON.
* **Post-Test Analysis**: Use Locust logs and metrics to pinpoint failures and improve your API performance.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://courses.parottasalna.com/locust/using-catch_response-in-locust-for-custom-response-validation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.