Анатомия тестового проекта на Python: раскладываем всё по полочкам для новичков

Устали хардкодить URL’ы и дублировать запросы? Разбираемся, как правильно организовать свой первый проект по автоматизации API на Pytest + Requests, чтобы он был красивым и расширяемым.

Привет, Хабровчане!

Меня зовут Кирилл, и я, как и многие здесь, иду по пути автоматизации тестирования. Сейчас будет немного лирики (совсем немного, чтобы как‑то подвести к сути:). Наверное, каждый «ручной» QA рано или поздно задумывается о том, что пора куда‑то расти. Такой момент настал и у меня и я выбрал автоматизацию тестирования. Самым приятным и реально доставляющим удовольствие от работы для меня стал ЯП Python. Помню свой первый успешный API‑тест, отправленный с помощью requests. Получил 200 OK в ответ, распарсил JSON и почувствовал себя настоящим хакером. Казалось, что теперь я могу проверить любую часть бэкенда, следующая остановка — Google 🙂

Я начал писать тесты. Много тестов. Сначала всё шло хорошо, но со временем мой код начал превращаться в то, что называют на проектах «техническим долгом»:

• Магия копипасты: Логика авторизации, одинаковые заголовки, базовые URL’ы — всё это кочевало из одного тестового файла в другой.

• Смешение всего со всем: Логика отправки HTTP-запроса была тесно переплетена с логикой самой проверки (ассертами). Тесты становились трудночитаемыми.

• Хрупкость: Стоило разработчикам поменять базовый URL с v1 на v2, и мне приходилось лезть в десятки файлов, чтобы всё исправить. Неприятненько и нудно.

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

Шаг 0: Наш инструментарий

Не будем усложнять. Для старта нам понадобится проверенный временем набор:

• pytest: Мощный и гибкий фреймворк для тестирования на Python. Его фикстуры и простой синтаксис — это просто подарок.

• requests: Стандартная библиотека для выполнения HTTP-запросов. Простая, но очень мощная.

• python-dotenv: Для хранения переменных окружения (базовые URL’ы, логины, токены) отдельно от кода.

Создадим файл requirements.txt в корне нашего будущего проекта:

pytest requests python-dotenv

После чего, установим все, что перечислили в файле, одной командой:

pip install -r requirements.txt

Шаг 1: Скелет API-проекта

Хороший проект начинается с хорошей организации. Вот базовый и, достаточно простой на мой взгляд скелет, который мы будем использовать:

my_api_tests/ ├── api/ │   ├── __init__.py │   ├── base_api_client.py   # Базовый класс для работы с API │   ├── auth_api.py          # Класс для работы с эндпоинтами аутентификации │   └── users_api.py         # Класс для работы с эндпоинтами пользователей │ ├── tests/ │   ├── __init__.py │   ├── conftest.py          # Фикстуры для тестов (клиенты, данные) │   └── test_auth.py         # Тесты для API аутентификации │   └── test_users.py        # Тесты для API пользователей │ ├── .env                    # Всяческие переменные окружения (логины, пароли и т.д. лучше держать здесь) ├── .gitignore               # Сюда записываем все, что не должно попасть в GIT (.env обязательно сюда) ├── pytest.ini               # Конфигурация pytest └── requirements.txt         # Уже знакомый нам файл с инструментарием

Тут постараюсь кратко объяснить что есть что в этой структуре:

• директория api/ — это «сердце» нашего фреймворка. Здесь мы будем описывать, как взаимодействовать с различными частями нашего API. Каждая «сущность» (пользователи, продукты, заказы) получит свой класс.

  • base_api_client.py — это наш фундамент для всех API-клиентов. Он будет содержать общую логику отправки запросов (GET, POST и т.д.), обработку базового URL и заголовков.

  • auth_api.py, users_api.py — это конкретные классы-клиенты. Они наследуются от base_api_client и содержат методы для работы с конкретными эндпоинтами (например, /login или /users).

• директория tests/ — папка, где живут наши тесты. pytest будет автоматически находить их здесь.

  • conftest.py — Всё, что мы в нём определим (фикстуры), будет доступно во всех тестах. Идеальное место, чтобы создавать API-клиентов или подготавливать тестовые данные.

• .env — файл для хранения секретных данных (URL, логины, пароли). Важно: никогда не добавляйте его в Git! Это ОЧЕНЬ важно, поэтому в самой структуре я также оставил коммент с упоминанием о том, что этот файл всегда должен быть добавлен в .gitignore (если мы, конечно, не хотим, чтобы наши логопассы утекли к посторонним лицам).

• .gitignore — стандартный файл для Git, который поможет игнорировать ненужные файлы (.env, pycache/ и т.д.) и не грузить их в удаленный репозиторий.

• pytest.ini — конфигурационный файл для pytest. Здесь можно задать маркеры, пути к тестам и другие настройки.

Шаг 2: Наполняем скелет жизнью

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

Конфигурация

1. Файл .env (в корне проекта)

BASE_URL="http://localhost:5000/api/v1" # Пример базового URL TEST_USERNAME="user" TEST_PASSWORD="password123"

2. Файл pytest.ini (в корне проекта)

[pytest] markers =     auth: authentication testing     users: users management testing testpaths =     tests

API-клиенты

1. Файл api/base_api_client.py

Этот класс будет содержать requests.Session() для поддержания сессии (что полезно для cookies и заголовков) и общие методы для всех HTTP-запросов.

import requests import json  class BaseApiClient:     def __init__(self, base_url: str):         self.base_url = base_url         self.session = requests.Session()      def _send_request(self, method: str, endpoint: str, **kwargs) -> requests.Response:         url = f"{self.base_url}{endpoint}"         try:             response = self.session.request(method, url, **kwargs)             response.raise_for_status() # Выбросит исключение для 4xx/5xx ответов             return response         except requests.exceptions.HTTPError as e:             print(f"HTTP Error: {e.response.status_code} - {e.response.text}")             raise      def get(self, endpoint: str, **kwargs) -> requests.Response:         return self._send_request("GET", endpoint, **kwargs)      def post(self, endpoint: str, **kwargs) -> requests.Response:         return self._send_request("POST", endpoint, **kwargs)

Методы _send_request и raise_for_status() — это мощный инструмент для централизованной обработки ошибок. Подсмотрел это у своего более опытного коллеги (Спасибо, Женя!:)

2. Файл api/auth_api.py

Это класс-клиент, который знает всё об эндпоинтах аутентификации.

from api.base_api_client import BaseApiClient  class AuthApi(BaseApiClient):     AUTH_LOGIN_ENDPOINT = "/auth/login"      def login(self, username, password) -> dict:         """Выполняет вход пользователя и возвращает JSON ответа."""         payload = {"username": username, "password": password}         response = self.post(self.AUTH_LOGIN_ENDPOINT, json=payload)         return response.json()

3. Файл api/users_api.py

А этот класс отвечает за работу с пользователями.

from api.base_api_client import BaseApiClient  class UsersApi(BaseApiClient):     USERS_ENDPOINT = "/users"      def get_users(self, token: str) -> dict:         """Получает список пользователей, требуя токен авторизации."""         headers = {"Authorization": f"Bearer {token}"}         response = self.get(self.USERS_ENDPOINT, headers=headers)         return response.json()

Тесты и Фикстуры

1. Файл tests/conftest.py

Здесь мы создадим фикстуры, которые будут «собирать» наши API-клиенты и предоставлять их тестам.

import pytest import os from dotenv import load_dotenv from api.auth_api import AuthApi from api.users_api import UsersApi  load_dotenv()                       @pytest.fixture(scope="session") def base_url():     """Фикстура, возвращающая базовый URL из .env."""     return os.getenv("BASE_URL")  @pytest.fixture(scope="function") def auth_api(base_url):     """Фикстура для создания клиента AuthApi."""     return AuthApi(base_url)  @pytest.fixture(scope="function") def users_api(base_url):     """Фикстура для создания клиента UsersApi."""     return UsersApi(base_url)  @pytest.fixture(scope="function") def auth_token(auth_api) -> str:     """Фикстура, которая логинится и возвращает токен авторизации."""     username = os.getenv("TEST_USERNAME")     password = os.getenv("TEST_PASSWORD")     response_data = auth_api.login(username, password)     return response_data.get("token")

Фикстура auth_token — это наш ключ к чистому коду. Она сама логинится и отдает токен. Тестам, требующим авторизации, больше не нужно об этом беспокоиться.

2. Файл tests/test_auth.py

А вот и сами тесты. Обратите внимание, какими они стали лаконичными! Мне кажется, даже ваш project manager, который не сильно шарит в коде, разберется что тут к чему)

import pytest import os import requests  @pytest.mark.auth def test_successful_login(auth_api):     """Проверяет успешный вход в систему."""     username = os.getenv("TEST_USERNAME")     password = os.getenv("TEST_PASSWORD")          response_data = auth_api.login(username, password)          assert response_data["status"] == "success"     assert "token" in response_data  @pytest.mark.auth def test_login_with_invalid_credentials(auth_api):     """Проверяет, что система вернет ошибку на неверные данные."""     with pytest.raises(requests.exceptions.HTTPError) as excinfo:         auth_api.login("wrong_user", "wrong_password")      assert excinfo.value.response.status_code == 401

3. Файл tests/test_users.py

Тест, использующий фикстуру с токеном.

import pytest  @pytest.mark.users def test_get_users_list_is_successful(users_api, auth_token):     """Проверяет получение списка пользователей после авторизации."""     users_list_data = users_api.get_users(token=auth_token)      assert users_list_data["status"] == "success"     assert isinstance(users_list_data.get("users"), list)

Вот, в принципе и все! Что мы имеем в итоге?
А в итоге мы с вами построили крепкий, но простой фундамент для API-автоматизации. Приведу очевидные на мой взгляд плюсы такого подхода:

1. Чистота и читаемость тестов: Тесты описывают бизнес-сценарии (auth_api.login()), а не детали HTTP.

2. Централизованное управление API: Если изменится эндпоинт, мы поправим его в одном месте — в соответствующем классе api/ (в этом моменте чуть не прослезился, почему я не знал это раньше..)

3. Переиспользование кода: Фикстуры pytest и базовый API-клиент избавляют нас от тонн дублирования.

4. Простота масштабирования: Появился новый сервис API? Просто создаем new_service_api.py и test_new_service.py — структура уже готова.

Конечно, это только начало. Дальше можно добавлять валидацию JSON-схем, генерацию тестовых данных с помощью Faker, data-driven тесты и многое другое. Но предложенная структура — это та самая крепкая база, с которой не стыдно начинать и которую легко развивать.

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

Буду рад услышать ваши мысли, критику и советы в комментариях. Всем добра!