Тестирование API с RAML

 /albums/{id}/tracks 

Метод addRoute() принимает в качестве третьего аргумента имя функции, предназначенной для обработки маршрута. Обычно вы определяете отдельные функции для соответствующей обработки каждого маршрута. Однако, поскольку мы собираемся обрабатывать все маршруты с использованием одного и того же кода, мы слегка переопределяем это поведение, а вместо имени функции добавляем путь во второй раз. Таким образом, мы можем извлечь путь в нашем обработчике, чтобы определить, какой ответ нам нужно отправить.

Давайте создадим метод dispatch() .

 /** * Dispatch a route * * @param string $method The HTTP verb (GET, POST etc) * @param string $url The URL * @param array $data An array of data (Note, not currently used) * @param array $headers An array of headers (Note, not currently used) * @return Response */ public function dispatch($method, $url, $data = array(), $headers = array()) { // Parse the URL $parsedUrl = parse_url($url); $path = $parsedUrl['path']; // Attempt to obtain a matching route $routeInfo = $this->dispatcher->dispatch($method, $path); // Analyse the route switch ($routeInfo[0]) { case \FastRoute\Dispatcher::NOT_FOUND: // Return a 404 return new Response(404); break; case \FastRoute\Dispatcher::METHOD_NOT_ALLOWED: // Method not allows (405) $allowedMethods = $routeInfo[1]; // Create the response... $response = new Response(405); // ...and set the Allow header $response->headers['Allow'] = implode(', ', $allowedMethods); return $response; break; case \FastRoute\Dispatcher::FOUND: $handler = $routeInfo[1]; $vars = $routeInfo[2]; $signature = sprintf('%s %s', $method, $handler); $route = $this->routes[$signature]; // Get any query parameters if (isset($parsedUrl['query'])) { parse_str($parsedUrl['query'], $queryParams); } else { $queryParams = []; } // Check the query parameters $errors = $this->checkQueryParameters($route, $queryParams); if (count($errors)) { $response = new Response(400); $response->setBody(json_encode(['errors' => $errors])); return $response; } // If we get this far, is a successful response return $this->handleRoute($route, $vars); break; } } 

Так что здесь происходит?

Мы начинаем с разбора URL и извлечения пути, затем используем FastRoute, чтобы попытаться найти подходящий маршрут.

RouteCollection dispatch() RouteCollection возвращает массив, первый элемент которого сообщает нам, является ли это действительным маршрутом, является ли он действительным, но недопустимым методом или просто не найден.

Если мы не можем найти соответствующий маршрут, мы генерируем 404 Not Found . Если метод не поддерживается, мы генерируем 405 Method Not Allowed , помещая разрешенные методы в соответствующий заголовок.

Третий случай, когда это становится интересным. Мы генерируем «сигнатуру», объединяя метод и путь, так что это выглядит примерно так:

 GET /account 

или:

 GET /albums/{id}/tracks 

Затем мы можем использовать это, чтобы получить определение маршрута из свойства $routes routs, которое, как вы помните, мы извлекли из нашего файла RAML.

Следующим шагом является создание массива параметров запроса, а затем вызов функции, которая проверяет их — мы вскоре перейдем к этой конкретной функции. Поскольку разные API могут обрабатывать ошибки совершенно по-разному, вы можете захотеть изменить это в соответствии с вашим API — в этом примере я просто возвращаю 400 Bad Request с телом, содержащим JSON-представление конкретных ошибок проверки.

На этом этапе вы можете добавить некоторые дополнительные проверки или проверки. Вы можете, например, проверить, есть ли в запросе соответствующие учетные данные безопасности. Мы собираемся реализовать это с помощью обязательного параметра запроса accessToken, который мы определили как признак в файле RAML.

Наконец, мы вызываем метод handleRoute() , передавая определение маршрута и любые параметры URI. Прежде чем мы рассмотрим это, давайте вернемся к проверке параметров нашего запроса.

 /** * Checks any query parameters * @param array $route The current route definition, taken from RAML * @param array $params The query parameters * @return boolean */ public function checkQueryParameters($route, $params) { // Get this route's available query parameters $queryParameters = $route['response']->getQueryParameters(); // Create an array to hold the errors $errors = []; if (count($queryParameters)) { foreach($queryParameters as $name => $param) { // If the display name is set then great, we'll use that - otherwise we'll use // the name $displayName = (strlen($param->getDisplayName())) ? $param->getDisplayName() : $name; // If the parameter is required but not supplied, add an error if ($param->isRequired() && !isset($params[$name])) { $errors[$name] = sprintf('%s is required', $displayName); } // Now check the format if (isset($params[$name])) { switch ($param->getType()) { case 'string': if (!is_string($params[$name])) { $errors[$name] = sprintf('%s must be a string'); } break; case 'number': if (!is_numeric($params[$name])) { $errors[$name] = sprintf('%s must be a number'); } break; case 'integer': if (!is_int($params[$name])) { $errors[$name] = sprintf('%s must be an integer'); } break; case 'boolean': if (!is_bool($params[$name])) { $errors[$name] = sprintf('%s must be a boolean'); } break; // date and file are omitted for brevity } } } } // Finally, return the errors return $errors; } 

Это довольно простые вещи — и обратите внимание, что я упустил некоторые типы параметров, чтобы не усложнять ситуацию, — но это можно использовать, чтобы поиграться с параметрами запросов и отклонить запросы, когда эти параметры не соответствуют спецификациям, изложенным в нашем RAML файл.

Наконец, handleRoute() :

 /** * Return a response for the given route * * @param array $route The current route definition, taken from RAML * @param array $vars An optional array of URI parameters * @return Response */ public function handleRoute($route, $vars) { // Create a reponse $response = new Response(200); // Return an example response, from the RAML $response->setBody($route['response']->getResponse(200)->getExampleByType('application/json')); // And return the result return $response; } 

Здесь мы извлекаем пример из соответствующего маршрута, а затем возвращаем его в качестве ответа с кодом состояния 200.

На этом этапе вы можете использовать RamlApiMock в своих модульных тестах. Однако, с помощью простого добавления, мы также можем предоставить этот компонент для имитации в качестве веб-службы, просто добавив к нему вызов с помощью простой логики маршрутизации.

Для этого создайте файл index.php со следующим содержимым:

 <?php require_once 'vendor/autoload.php'; use Sitepoint\RamlApiMock; // The RAML library is currently showing a deprecated error, so ignore it error_reporting(E_ERROR | E_WARNING | E_PARSE | E_NOTICE); // Create the router $router = new RamlApiMock('./test/fixture/api.raml'); // Handle the route $response = $router->dispatch($_SERVER['REQUEST_METHOD'], $_SERVER['REQUEST_URI']); // Set the HTTP response code http_response_code($response->status); // Optionally set some response headers if (count($response->headers)) { foreach ($response->headers as $name => $value) { header(sprintf('%s: %s', $name, $value)); } } // Print out the body of the response print $response->body; 

Надеюсь, это довольно очевидно; мы создаем наш «маршрутизатор», обрабатываем запрошенную комбинацию URL-адреса и метода, затем отправляем ответ с соответствующим кодом состояния и любыми заголовками.

Теперь запустите сервер со следующим:

 php -S localhost:8000 

Поскольку API-интерфейсы значительно различаются, вероятно, вам придется изменить этот пример в соответствии с вашей реализацией. Надеюсь, это даст вам достаточно, чтобы начать.

Резюме

В этой статье я рассмотрел RAML в контексте API тестирования и насмешек.

Поскольку RAML предоставляет однозначное и исчерпывающее заявление о том, как должен функционировать API, это очень полезно как для тестирования, так и для предоставления ложных ответов.

С RAML вы можете сделать гораздо больше, и эти примеры только касаются того, как RAML можно использовать в тестировании, но, надеюсь, я предоставил вам несколько идей.