Add HttpTestTrait. Distinguish it from GuzzleTestTrait.

[civicrm-core.git] / Civi / Test / HttpTestTrait.php

<?php

namespace Civi\Test;

use GuzzleHttp\HandlerStack;
use GuzzleHttp\Middleware;

/**
 * Class HttpTestTrait
 *
 * @package Civi\Test
 *
 * This trait provides helpers/assertions for testing Civi's HTTP interfaces, eg
 *
 * - createGuzzle() - Create HTTP client for sending requests to Civi.
 * - callApi4AjaxSuccess() - Use an HTTP client to send an AJAX-style request to APIv4
 * - callApi4AjaxError() - Use an HTTP client to send an AJAX-style request to APIv4
 * - assertStatusCode() - Check the status code. If it fails, output detailed information.
 * - assertContentType() - Check the content-type. If it fails, output detailed information.
 *
 * Use this in an E2E test for which you need to send inbound HTTP requests to Civi.
 * Alternatively, for a headless test which mocks outbound HTTP, see GuzzleTestTrait.
 */
trait HttpTestTrait {

  /**
   * List of HTTP requests that have been made by this test.
   *
   * @var array
   */
  protected $httpHistory = [];

  /**
   * Create an HTTP client suitable for simulating AJAX requests.
   *
   * @param array $options
   * @return \GuzzleHttp\Client
   */
  protected function createGuzzle($options = []) {
    $handler = HandlerStack::create();
    $handler->push(\CRM_Utils_GuzzleMiddleware::url(), 'civi_url');
    $handler->push(Middleware::history($this->httpHistory), 'history');

    $defaults = [
      'handler' => $handler,
      'base_uri' => 'auto:',
    ];

    $options = array_merge($defaults, $options);
    return new \GuzzleHttp\Client($options);
  }

  /**
   * @param string $entity
   * @param string $action
   * @param array $params
   *
   * @return mixed
   */
  protected function callApi4AjaxSuccess(string $entity, string $action, $params = []) {
    $method = \CRM_Utils_String::startsWith($action, 'get') ? 'GET' : 'POST';
    $response = $this->createGuzzle()->request($method, "civicrm/ajax/api4/$entity/$action", [
      'headers' => ['X-Requested-With' => 'XMLHttpRequest'],
      // This should probably be 'form_params', but 'query' is more representative of frontend.
      'query' => ['params' => json_encode($params)],
      'http_errors' => FALSE,
    ]);
    $this->assertContentType('application/json', $response);
    $this->assertStatusCode(200, $response);
    $result = json_decode((string) $response->getBody(), 1);
    if (json_last_error() !== JSON_ERROR_NONE) {
      $this->fail("Failed to decode APIv4 JSON.\n" . $this->formatFailure($response));
    }
    return $result;
  }

  /**
   * @param string $entity
   * @param string $action
   * @param array $params
   *
   * @return mixed
   */
  protected function callApi4AjaxError(string $entity, string $action, $params = []) {
    $method = \CRM_Utils_String::startsWith($action, 'get') ? 'GET' : 'POST';
    $response = $this->createGuzzle()->request($method, "civicrm/ajax/api4/$entity/$action", [
      'headers' => ['X-Requested-With' => 'XMLHttpRequest'],
      // This should probably be 'form_params', but 'query' is more representative of frontend.
      'query' => ['params' => json_encode($params)],
      'http_errors' => FALSE,
    ]);
    $this->assertContentType('application/json', $response);
    $this->assertTrue($response->getStatusCode() >= 400, 'Should return an error' . $this->formatFailure($response));
    $result = json_decode((string) $response->getBody(), 1);
    if (json_last_error() !== JSON_ERROR_NONE) {
      $this->fail("Failed to decode APIv4 JSON.\n" . $this->formatFailure($response));
    }
    return $result;
  }

  /**
   * @param $expectCode
   * @param \Psr\Http\Message\ResponseInterface|NULL $response
   *   If NULL, then it uses the last response.
   *
   * @return $this
   */
  protected function assertStatusCode($expectCode, $response = NULL) {
    $response = $this->resolveResponse($response);
    $actualCode = $response->getStatusCode();
    $fmt = $actualCode === $expectCode ? '' : $this->formatFailure($response);
    $this->assertEquals($expectCode, $actualCode, "Expected HTTP response $expectCode. Received HTTP response $actualCode.\n$fmt");
    return $this;
  }

  /**
   * @param $expectType
   * @param \Psr\Http\Message\ResponseInterface|NULL $response
   *   If NULL, then it uses the last response.
   *
   * @return $this
   */
  protected function assertContentType($expectType, $response = NULL) {
    $response = $this->resolveResponse($response);
    $actualType = $response->getHeader('Content-Type');
    $fmt = $actualType === $expectType ? '' : $this->formatFailure($response);
    $this->assertEquals([$expectType], $actualType, "Expected content-type $expectType. Received conte-tntype $actualType.\n$fmt");
    return $this;
  }

  /**
   * @param \Psr\Http\Message\ResponseInterface|NULL $response
   * @return \Psr\Http\Message\ResponseInterface
   */
  protected function resolveResponse($response) {
    return $response ?: $this->httpHistory[count($this->httpHistory) - 1]['response'];
  }

  /**
   * Given that an HTTP request has yielded a failed response, format a blurb
   * to summarize the details of the request+response.
   *
   * @param \Psr\Http\Message\ResponseInterface $response
   *
   * @return false|string
   */
  protected function formatFailure(\Psr\Http\Message\ResponseInterface $response) {
    $details = [];

    $condenseArray = function($v) {
      if (is_array($v) && count($v) === 1 && isset($v[0])) {
        return $v[0];
      }
      else {
        return $v;
      }
    };

    /** @var \Psr\Http\Message\RequestInterface $request */
    $request = NULL;
    foreach ($this->httpHistory as $item) {
      if ($item['response'] === $response) {
        $request = $item['request'];
        break;
      }
    }

    if ($request) {
      $details['request'] = [
        'uri' => (string) $request->getUri(),
        'method' => $request->getMethod(),
        // Most headers only have one item. JSON pretty-printer adds several newlines. This output is meant for dev's reading the error-log.
        'headers' => array_map($condenseArray, $request->getHeaders()),
        'body' => (string) $request->getBody(),
      ];
    }

    $details['response'] = [
      'status' => $response->getStatusCode() . ' ' . $response->getReasonPhrase(),
      // Most headers only have one item. JSON pretty-printer adds several newlines. This output is meant for dev's reading the error-log.
      'headers' => array_map($condenseArray, $response->getHeaders()),
      'body' => (string) $response->getBody(),
    ];

    // If we get a full HTML document, then it'll be hard to read the error messages. Give an alternate rendition.
    if (preg_match(';\<(!DOCTYPE|HTML);', $details['response']['body'])) {
      // $details['bodyText'] = strip_tags($details['body']); // too much <style> noise
      $details['response']['body'] = \CRM_Utils_String::htmlToText($details['response']['body']);
    }

    return json_encode($details, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);
  }

}