Optional HTTP request/response attachment in Allure Reports

[sethorpe]

Summary

This PR introduces a streamlined way for test authors to capture and attach full HTTP request/response details into Allure reports by simply passing a boolean flag (attach=True) on any client call. With this change, there's no need for manial allure.attach(...) calls in test code. Authors can focus on endpoint calls and assertions, and the framework handles the rest.

What's Changed

1. Per-Call "attach" Flag

• All HTTP methods (get, post, put, delete) in the core APIClient now accept a keyword-only parameter attach: bool = False.
• When attach=True, the framework will automatically record both the outgoing Request and incoming Response and push them as attachments into the Allure report.

2. Request/Response Recording & Attachment helpers

• Introduced private fields to hold the most recent Request and Response objects.

• Added a _record_request(request) helper that saves the built httpx.Request just before sending.

• Added a _attach_last_exchange_to_allure() helper that uses allure.attach(...) to add these details to the report, including:

  • Request line (method + URL)
  • Request headers
  • Request body (with JSON detection or fallback to text)
  • Request status (e.g. "200 OK")
  • Response headers
  • Response body (JSON vs. text)

3. Preserving Normal Behavior

• Client calls without attach=True remain unchanged. No attachments are produced, and the core API logic behaves identically to before.
• If a server returns a non-2xx status, the existing APIError is still raised; but if attach=True, the request/response will still be attached to Allure before the error propagates.

4. Updated Spotify-Specific Client

• Spotify client helper methods (get_new_releases, get_artist_top_tracks) now accept the attach flag and pass it through to the underlying get call. This lets integration tests capture those HTTP exchanges without additional code.

5. Test Coverage

• Existing unit tests were extended to cover the attach=True path:

  • Verifies that calling client.get(..., attach=True) still returns the expected JSON body without errors.
  • Verifies that a simulated error (500 response) with attach=True still raises APIError but does not crash during attachment.
  • Ensures repeated calls with attach=True continue to work as expected.

How to Verify Locally

1. Install dependencies

make install

(This runs poetry install, ensuring allure-pytest and httpx are available.)

2. Run Unit Tests

make test

• All existing tests should pass.
• New tests cover both attach=False (default) and attach=True cases.

3. Generate and Serve Allure Report

make report
make serve-report

• Choose or write a test that calls, for example, client.get("/some-endpoint", attach=True).

• In the Allure UI, open that test's details. Under Attachments, you should see:

  • HTTP Request (method + URL)
  • Request Headers
  • Request Body (if applicable)
  • HTTP Response Status
  • Response Headers
  • Response Body

4. Test Error Case

• Create or modify a dummy transport to simulate a 500 error.
• Call client.get("/error", attach=True) in a test. The test should raise APIError, and the Allure rpeort should show the recorded request and failing response under that test's attachments.

By adding the attach flag, test authors can now capture HTTP exhanges with a single boolean argument. No more manual allure.attach(...) calls scattered throughout test code. This simplifies debugging and accelerates development when diagnosing API issues. Let me know if you have any questions!