Yandex.Disk API Test Framework

Фреймворк автоматизированного тестирования REST API Яндекс.Диска на Python 3 + pytest.

🎯 Цель проекта

Демонстрация подхода к интеграционному тестированию внешнего API:

• Слоистая архитектура (BaseClient → доменные клиенты → тесты).
• Валидация контрактов ответов через Pydantic-модели.
• Асинхронные операции (polling статуса).
• Ретраи с учётом идемпотентности HTTP-методов.
• Структурированное логирование с маскировкой секретов.
• CI/CD с отчётом Allure.

📋 Требования

• Python 3.10+
• OAuth-токен Яндекс.Диска (см. раздел «Получение токена»)

🚀 Установка

1. Клонирование репозитория

git clone https://github.com/<username>/yandex-disk-api-tests.git
cd yandex-disk-api-tests

2. Установка зависимостей

python -m venv .venv
source .venv/bin/activate          # Linux/macOS
# .venv\Scripts\activate           # Windows

pip install -r requirements.txt
pip install -r requirements-dev.txt

3. Настройка окружения

Скопируйте .env.example в .env и заполните токен:

cp .env.example .env

Содержимое .env:

API_TOKEN=your_yandex_oauth_token_here

Дополнительные переменные (опционально, если нужно переопределить дефолты из config/settings.py):

# BASE_URL=https://cloud-api.yandex.net
# API_VERSION=v1

🔑 Получение токена

1. Зарегистрируйте приложение на oauth.yandex.ru.

2. Укажите Redirect URI: https://oauth.yandex.ru/verification_code.

3. Выберите права доступа: cloud_api:disk.read, cloud_api:disk.write, cloud_api:disk.info.

4. После регистрации скопируйте Client ID.

5. Перейдите по ссылке (подставив свой client_id):

   https://oauth.yandex.ru/authorize?response_type=token&client_id=<YOUR_CLIENT_ID>
   

6. Подтвердите доступ. Из адресной строки скопируйте значение access_token.

7. Вставьте его в .env как API_TOKEN.

⚠️ Важно: используйте изолированный тестовый аккаунт, а не личный.

🧪 Запуск тестов

# Все тесты
pytest

# Конкретный файл
pytest tests/test_post_upload.py

# Конкретный тест
pytest tests/test_post_upload.py::TestPostUploadFromUrl::test_upload_from_url_success

# С Allure-отчётом
pytest --alluredir=allure-results
allure serve allure-results

Makefile

make install    # установить зависимости
make test       # запустить тесты
make lint       # запустить ruff
make allure     # сгенерировать и открыть Allure-отчёт

📁 Структура проекта

.
├── api
│   ├── base_client.py                  # Базовый клиент, управляет сессией и ретраями
│   ├── clients
│   │   └── disk_client.py              # Кастомный клиент, реализует методы API
│   ├── hooks.py                        # хуки для логгирования запросов и ответов
│   └── routes
│       └── disk_routes.py              # Маршруты кастомного клиента, предполагается, что клиентов может быть несколько
├── config
│   └── settings.py
├── conftest.py                         # фикстуры общего назначения
├── env.example
├── Makefile
├── pyproject.toml
├── README.md
├── requirements-dev.txt
├── requirements.txt
├── schemas
│   ├── base.py
│   └── models.py
└── tests
    ├── conftest.py                     # фикстуры для тестов
    └── test_disk                       # тесты на API YADisk 
        └── test_disk_general.py

🏗️ Архитектура

Три слоя

1. BaseClient — транспортный слой. Отвечает только за HTTP: сессия, URL, авторизация, таймауты, ретраи, логирование. Не знает про домены.
2. DiskClient — доменный слой. Знает маршруты и модели Яндекс.Диска. Инкапсулирует polling асинхронных операций.
3. Тесты — слой проверок. Используют доменный клиент, валидируют модели и семантику.

Принципы

• Сквозные заботы в одном месте. Ретраи, логирование, таймауты — в BaseClient.
• Идемпотентность. GET/PUT/DELETE ретраят 5xx, POST/PATCH — нет.
• Композиция, не наследование. DiskClient(base_client).
• Явное лучше неявного. Ожидаемый статус передаётся в метод, а не угадывается.

🔧 Переменные окружения

Переменная	Обязательна	Дефолт	Описание
API_TOKEN	✅	—	OAuth-токен Яндекс.Диска
BASE_URL	❌	https://cloud-api.yandex.net	Базовый URL API
API_VERSION	❌	v1	Версия API

Секреты хранятся только в .env (локально) или в GitHub Secrets (CI). .env в .gitignore.

🎨 Логирование

Все запросы логируются через хук requests в JSON-совместимом формате:

• Метод, URL, статус, длительность.
• Заголовки запроса с маскировкой Authorization, Cookie.
• Тело запроса/ответа с маскировкой access_token, password, secret.
• Усечение длинных тел (500 символов).

🤖 CI/CD

GitHub Actions workflow .github/workflows/checks.yml запускается на каждый push и PR:

1. Устанавливает зависимости.
2. Запускает pytest с Allure-отчётом.
3. Публикует отчёт на GitHub Pages.

📊 Allure-отчёт

Установка Allure CLI

allure-pytest (Python-плагин) генерирует JSON-результаты, но для просмотра HTML-отчёта нужен Allure Commandline — отдельная Java-утилита, которая не устанавливается через pip.

macOS

brew install allure

Проверка:

allure --version

Ubuntu / Debian

В официальных репозиториях Ubuntu пакета allure нет (одноимённый пакет — это игра). Установи вручную:

# 1. Java (если ещё нет)
sudo apt install default-jre

# 2. Скачать последний релиз
wget https://github.com/allure-framework/allure2/releases/download/2.32.0/allure-2.32.0.tgz

# 3. Распаковать и переместить
tar -xzf allure-2.32.0.tgz
sudo mv allure-2.32.0 /opt/allure

# 4. Симлинк в PATH
sudo ln -s /opt/allure/bin/allure /usr/local/bin/allure

Проверка:

allure --version

Установка Python-плагина

pip install allure-pytest

Или через зависимости проекта:

pip install -r requirements-dev.txt

Запуск тестов с отчётом

# 1. Сгенерировать JSON-результаты
uv run pytest --alluredir=allure-results

# 2. Построить и открыть HTML-отчёт в браузере
allure serve allure-results

⚠️ allure serve запускается напрямую, без uv — это внешняя Java-утилита, а не Python-пакет.

Генерация статического HTML

Если нужно сохранить отчёт как папку с HTML (например, для публикации):

allure generate allure-results -o allure-report --clean

Открыть результат:

allure open allure-report

Через Makefile

make allure

В CI — отчёт публикуется автоматически на https://<username>.github.io/<repo>/.

⚠️ Ограничения

• Тесты не идемпотентны в части использования Диска: создают и удаляют файлы. Не запускайте против продакшн-аккаунта с важными данными.
• Троттлинг загрузки: Яндекс ограничивает скорость для неофициальных клиентов. Если тесты начнут тормозить — см. User-Agent в BaseClient.
• Токен долгоживущий, но при смене пароля Яндекс-аккаунта — отзывается.