HttpTestTrait - Define helper methods for E2E tests of Civi's HTTP routes

[totten]

Overview

This introduces some programmatic helpers to facilitate end-to-end testing of Civi's HTTP routes.

Technical Details

Here's a basic example which attempts to fetch the civicrm/dashboard route -- and which asserts

/**
 * @group e2e
 */
class MyTest extends \PHPUnit\Framework\TestCase implements EndToEndInterface {

  use HttpTestTrait;

  public function testGetDashboardAnon403() {
    $http = $this->createGuzzle(['http_errors' => FALSE]);
    $r =$http->get('civicrm/dashboard');
    $this->assertStatusCode(403, $r);
  }
}

There are a couple of main helpers being used in this example:

• URI Helper: The Guzzle instance has URI handling that understands Civi routing. So a call to $http->get('civicrm/dashboard') will resolve to a full URL like http://localhost:8001/drupal/civicrm/dashboard. It specifically supports these URL schemes:
  • route://ROUTE_NAME (aka) route:ROUTE_NAME
  • var://PATH_EXPRESSION (aka) var:PATH_EXPRESSION
  • ext://EXTENSION/FILE (aka) ext:EXTENSION/FILE
  • assetBuilder://ASSET_NAME?PARAMS (aka) assetBuilder:ASSET_NAME?PARAMS
  • auto://ROUTE_NAME_OR_PATH_EXPRESSION
  • If you use a relative path (ie no URL scheme), then it will use auto://. More details in CRM_Utils_GuzzleMiddleware::url().
• Assertions: The test class has extra assertions (e.g. assertStatusCode() or assertContentType()). These assertions are more informative than the typical assertEquals(). If you use assertEquals(), then it only reports one datum in isolation (eg the status code). With the extended assertion, the failure will report more detailed context (ie the HTTP request and HTTP response).

A few more notes:

• This is required for some other pending PRs (eg AuthX - Extended authentication support (portable and router-friendly) #19590 and Afform - Allow public submission (PUB-CONTACT). Expand E2E test coverage. #19579).
• There is a similar-sounding class, GuzzleTestTrait. My understanding is that it HttpTestTrait and GuzzleTestTrait serve different purposes:
  • GuzzleTestTrait is used for cases like payment-processing -- wherein Civi acts as a client to some remote service. Civi makes outbound requests through Guzzle. One instruments mocking into Guzzle to see that outbound requests meet assertions and to simulate their responses.
  • HttpTestTrait is used for E2E-style tests of authx and afform public form-submissions -- wherein Civi acts as a server. Our test needs to send real HTTP requests to Civi. These requests also go through Guzzle, but we don't want to mock them. We just want to reduce some tedium in sending them.

Comments

Anything else you would like the reviewer to note

[civibot]

(Standard links)

• If this is your first pull-request for CiviCRM, please browse CONTRIBUTING.md for information about the development and testing processes.
• If you are reviewing this pull-request, you may wish to consult the test sites and the Review Standards (long template, short template).