Files
api-checker/AIProjectCard.md
T
Black_Raven 3b39701453 docs: Add AIProjectCard.md
Project specification with architecture, phases, and MVP requirements
2026-08-24 15:47:14 +03:00

1086 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Контекст проекта
Мы разрабатываем стартап/проект для **автоматизированного end-to-end тестирования пользовательских API через GitHub Actions**.
## Главная идея
Продукт должен позволять разработчику проверить, что его backend-приложение действительно работает целиком с точки зрения пользователя.
Это НЕ API monitoring и НЕ сервис, который постоянно проверяет API.
Тест запускается **один раз** в рамках CI/CD pipeline.
Основной сценарий:
```text
GitHub Actions Job
│
├── Checkout repository
│
├── Build application
│
├── Start application
│
├── Wait until application is ready
│
├── Run API E2E tests
│
├── Generate report
│
└── Cleanup
```
Например:
```text
POST /register
↓
POST /login
↓
GET /profile
↓
POST /posts
↓
GET /posts/{id}
↓
DELETE /posts/{id}
```
Если любой шаг ломается, GitHub Actions Job должен завершиться с ошибкой.
---
# Главная ценность продукта
Продукт должен проверять не отдельные endpoints, а **полноценные пользовательские сценарии**.
Например:
```text
Register user
↓
получить user_id
↓
Login
↓
получить JWT
↓
Get profile с JWT
↓
Create post
↓
получить post_id
↓
Get post
↓
Delete post
```
Данные между запросами должны автоматически передаваться.
Пример:
```text
login.response.token
↓
Authorization: Bearer {{token}}
create.response.id
↓
GET /posts/{{post_id}}
```
---
# Важное отличие от обычного API monitoring
Не нужно постоянно проверять:
```text
GET /health
GET /health
GET /health
```
Нас интересует одноразовая проверка:
> "Я только что поднял приложение. Может ли реальный пользователь пройти через основной сценарий и работает ли API целиком?"
---
# Основной execution environment
Основной execution environment — **GitHub Actions**.
Очень важно:
Тестируемое приложение должно запускаться **в рамках того же GitHub Actions Job**, в котором выполняется API E2E test.
Например:
```yaml
jobs:
e2e:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Start application
run: docker compose -f docker-compose.test.yml up -d
- name: API E2E
uses: our-org/api-e2e@v1
with:
spec: tests/api.yaml
base-url: http://localhost:8080
- name: Cleanup
if: always()
run: docker compose -f docker-compose.test.yml down -v
```
В будущем желательно, чтобы сам Action мог запускать Docker Compose и выполнять cleanup автоматически.
---
# Требование к Docker
Основной вариант для MVP:
```text
Docker
Docker Compose
```
Типичное приложение:
```text
docker-compose.test.yml
api
postgres
redis
etc.
```
Продукт должен уметь:
1. запустить приложение;
2. дождаться readiness;
3. проверить healthcheck;
4. выполнить тесты;
5. собрать результаты;
6. удалить контейнеры;
7. выполнить cleanup даже при падении тестов.
---
# API Test Engine
Главное ядро проекта — собственный API Test Engine.
Он должен поддерживать:
```text
GET
POST
PUT
PATCH
DELETE
HEAD
OPTIONS
```
Каждый request должен иметь:
```text
Method
URL
Headers
Query parameters
Body
Timeout
Variables
Assertions
Extraction
```
---
# Variables
Нужны обычные переменные:
```yaml
variables:
email: test@example.com
password: Test123!
```
Использование:
```yaml
url: /api/users/{{user_id}}
```
---
# Dynamic variables
Нужна генерация тестовых данных:
```text
{{random.uuid}}
{{random.email}}
{{random.username}}
{{random.string}}
{{random.number}}
{{timestamp}}
```
Это необходимо для сценариев регистрации и создания ресурсов.
---
# Extraction
Один request должен уметь извлекать данные из response и передавать их следующим request.
Например:
```yaml
- name: Login
request:
method: POST
url: /api/login
extract:
token: "$.token"
```
Следующий request:
```yaml
- name: Profile
request:
method: GET
url: /api/profile
headers:
Authorization: "Bearer {{token}}"
```
Для JSON желательно использовать JSONPath или совместимый механизм.
---
# Assertions
Минимально необходимы:
```text
HTTP status
JSON field exists
JSON value
Header
Response time
Regex
Contains
Equals
Not equals
Exists
```
Например:
```yaml
expect:
status: 200
json:
user.id:
exists: true
user.email:
equals: "{{email}}"
```
---
# OpenAPI
Продукт обязательно должен поддерживать:
```text
OpenAPI 3.0
OpenAPI 3.1
YAML
JSON
```
OpenAPI должен использоваться для:
* импорта API;
* обнаружения endpoints;
* определения HTTP methods;
* определения parameters;
* определения request body;
* определения response schemas;
* генерации базовых тестов;
* schema validation.
Например:
```text
OpenAPI
↓
Parser
↓
Internal Test Model
↓
API Test Engine
```
---
# Postman
Продукт должен поддерживать импорт:
```text
Postman Collection v2
Postman Collection v2.1
```
Нужно поддержать:
* requests;
* methods;
* URLs;
* headers;
* query parameters;
* body;
* variables;
* environments;
* authentication;
* request chains;
* basic assertions;
* extracted variables.
Очень важно:
OpenAPI и Postman **не должны напрямую использоваться Test Engine**.
Оба формата должны преобразовываться во внутреннюю модель.
```text
Postman ────────┐
↓
Internal Test Model
↑
OpenAPI ────────┘
↓
Test Engine
```
Это позволит позже добавлять другие форматы.
---
# Authentication
Минимально:
```text
None
Basic Auth
Bearer Token
API Key
OAuth 2.0
```
Особенно важен сценарий:
```text
POST /login
↓
extract JWT
↓
Bearer {{token}}
↓
GET /profile
```
---
# Reporting
После теста должны создаваться:
```text
Console report
JUnit XML
JSON
HTML
GitHub Step Summary
```
Пример:
```text
API E2E Tests
✓ Register 184ms
✓ Login 92ms
✓ Profile 61ms
✓ Create post 142ms
✗ Delete post 83ms
5 / 6 passed
FAILED:
Delete post
Expected: 204
Received: 500
```
GitHub Actions должен получать корректный exit code:
```text
0 = success
1 = failure
```
Также нужны GitHub annotations:
```text
::error
::warning
::notice
::group
```
---
# Local CLI
Хотя основное выполнение происходит через GitHub Actions, Test Engine должен работать локально.
Например:
```bash
api-e2e run tests/api.yaml
```
или:
```bash
api-e2e run \
--spec tests/api.yaml \
--base-url http://localhost:8080
```
Также нужны:
```bash
api-e2e validate
api-e2e import
api-e2e report
```
Локальный запуск нужен для debugging.
Один и тот же тест должен работать:
```text
Local
↓
api-e2e CLI
CI
↓
GitHub Action
```
---
# Будущая SaaS-часть
После создания рабочего Test Engine можно сделать веб-платформу.
Frontend:
```text
Dashboard
Projects
Test scenarios
Scenario editor
Request editor
Assertions editor
Run history
Test results
Logs
Reports
GitHub integration
```
Backend:
```text
Users
Projects
Repositories
Test scenarios
Test runs
Results
GitHub integrations
```
Backend НЕ должен выполнять пользовательские API-тесты напрямую.
Основное выполнение должно происходить в GitHub Actions.
---
# GitHub App
В дальнейшем желательно сделать полноценный GitHub App вместо ручного PAT.
Пользователь:
```text
Connect GitHub
↓
Install GitHub App
↓
Select repository
↓
Select tests
```
GitHub integration должна позволять запускать тесты:
```text
Pull Request
Push
Manual
Release
Schedule
```
---
# Рекомендуемый стек
Мы остановились на TypeScript.
## Test Engine
```text
TypeScript
Node.js
```
## CLI
```text
TypeScript
Commander или аналог
```
## GitHub Action
```text
TypeScript
Node.js
```
## Backend
```text
TypeScript
Node.js
Fastify
```
## Database
```text
PostgreSQL
```
## ORM
```text
Drizzle или Prisma
```
## Frontend
```text
Next.js
React
TypeScript
Tailwind
```
## Infrastructure
```text
Docker
Docker Compose
GitHub Actions
```
---
# Предполагаемая архитектура
```text
GitHub Actions
│
▼
┌─────────────────┐
│ API E2E CLI │
│ / Action │
└────────┬────────┘
│
┌──────────────┼──────────────┐
▼ ▼ ▼
OpenAPI Parser Postman Parser Config
│ │ │
└──────────────┼──────────────┘
▼
Internal Test Model
│
▼
Test Engine
│
┌──────────────┼──────────────┐
▼ ▼ ▼
HTTP Variables Assertions
│ │ │
└──────────────┼──────────────┘
▼
Reports
```
---
# Структура репозитория
Предполагаемая структура:
```text
api-e2e/
│
├── packages/
│ ├── engine/
│ │ ├── http/
│ │ ├── assertions/
│ │ ├── variables/
│ │ ├── extraction/
│ │ ├── runner/
│ │ └── reports/
│ │
│ ├── openapi/
│ │ └── parser/
│ │
│ ├── postman/
│ │ └── parser/
│ │
│ ├── config/
│ └── cli/
│
├── action/
│ ├── action.yml
│ └── src/
│
├── backend/
├── frontend/
│
├── examples/
│ ├── basic/
│ ├── docker-compose/
│ ├── openapi/
│ └── postman/
│
├── tests/
│
├── docker-compose.yml
├── package.json
└── README.md
```
---
# Очередность разработки
Очень важно: **не начинать сразу с SaaS/frontend/backend**.
Разработка должна идти в следующем порядке.
## Phase 1 — Test Engine
Сначала сделать полностью автономный CLI.
Цель:
```bash
api-e2e run tests/api.yaml
```
Он должен:
```text
Load config
↓
Execute requests
↓
Pass variables
↓
Extract values
↓
Run assertions
↓
Return result
↓
Exit code
```
После этой фазы можно локально протестировать полноценный E2E workflow.
---
## Phase 2 — Variables + Extraction + Assertions
Добавить:
* static variables;
* environment variables;
* random data;
* JSON extraction;
* JSONPath;
* status assertions;
* JSON assertions;
* header assertions;
* response-time assertions;
* regex;
* contains;
* equals;
* exists.
---
## Phase 3 — Docker
Добавить:
* Docker Compose;
* startup;
* readiness;
* healthcheck;
* timeout;
* logs;
* cleanup;
* cleanup on failure.
Цель:
```bash
api-e2e run \
--compose docker-compose.test.yml \
--spec tests/api.yaml
```
Должно происходить:
```text
Start containers
↓
Wait for API
↓
Run tests
↓
Generate report
↓
Cleanup
```
---
## Phase 4 — GitHub Action
После того как CLI работает локально:
* action.yml;
* inputs;
* outputs;
* exit codes;
* GitHub annotations;
* GitHub Step Summary;
* JUnit;
* artifacts.
Цель:
```yaml
- uses: our-org/api-e2e@v1
with:
spec: tests/api.yaml
compose: docker-compose.test.yml
```
---
## Phase 5 — OpenAPI
Добавить:
* OpenAPI 3.0;
* OpenAPI 3.1;
* YAML;
* JSON;
* endpoint discovery;
* request generation;
* response schema validation;
* authentication;
* test generation.
---
## Phase 6 — Postman
Добавить:
* Collection v2;
* Collection v2.1;
* environments;
* variables;
* headers;
* authentication;
* body;
* assertions;
* extracted variables;
* chained requests.
---
## Phase 7 — Web UI
Только после рабочего CLI и GitHub Action.
Добавить:
* authentication;
* projects;
* GitHub integration;
* test scenario editor;
* request editor;
* assertions editor;
* run history;
* results;
* logs;
* reports.
---
## Phase 8 — GitHub App
Добавить:
* GitHub App;
* repository selection;
* workflow integration;
* permissions;
* webhooks;
* automatic PR integration.
---
## Phase 9 — SaaS
После появления рабочего продукта:
* accounts;
* teams;
* projects;
* usage limits;
* billing;
* plans;
* cloud storage;
* test history.
---
# MVP
Первый MVP должен содержать только:
* GitHub Action;
* CLI;
* YAML test specification;
* HTTP requests;
* variables;
* extraction;
* assertions;
* Docker Compose;
* startup;
* readiness;
* cleanup;
* JUnit;
* GitHub Summary;
* OpenAPI import;
* Postman import.
Не делать в MVP:
* API monitoring;
* browser testing;
* load testing;
* Kubernetes;
* собственные CI runners;
* AI;
* десятки интеграций;
* сложную SaaS-платформу.
---
# Безопасность
Это критически важная часть.
Тесты могут содержать:
```text
API keys
Passwords
JWT
Cookies
Database credentials
Production secrets
```
Поэтому:
* secrets нельзя писать в logs;
* Authorization headers должны маскироваться;
* passwords нельзя сохранять;
* secrets должны передаваться через GitHub Secrets;
* response body не должен отправляться на наш сервер без явного разрешения;
* необходимо ограничивать размеры response;
* необходимо ограничивать timeout;
* необходимо валидировать URLs;
* необходимо предотвращать SSRF;
* нельзя выполнять произвольные shell-команды из пользовательской конфигурации;
* выполнение тестов должно происходить в изолированном GitHub Actions environment.
Особенно важно:
**Backend SaaS не должен напрямую выполнять произвольные HTTP-запросы пользователей.**
---
# Главный принцип разработки
Не пытаться сразу создать огромную платформу.
Сначала должно работать:
```text
Docker Compose
↓
Application
↓
API E2E Engine
↓
Assertions
↓
Report
↓
Cleanup
```
Потом:
```text
CLI
↓
GitHub Action
```
Потом:
```text
OpenAPI
+
Postman
```
И только потом:
```text
Frontend
+
Backend
+
GitHub App
+
SaaS
```
---
# Конечная концепция продукта
Продукт должен отвечать на простой вопрос:
> **«Если я только что поднял своё приложение, может ли реальный пользователь пройти через основной API-сценарий от начала до конца?»**
Пример:
```text
Application started
↓
Healthcheck
↓
Register
↓
Login
↓
Get profile
↓
Create resource
↓
Get resource
↓
Update resource
↓
Delete resource
↓
PASS
```
В идеале пользователь должен иметь возможность взять существующий:
```text
OpenAPI
```
или:
```text
Postman Collection
```
и практически сразу получить готовый E2E-тест, который можно запускать локально и в GitHub Actions.
Главная конкурентная идея продукта:
> **Не заменять Postman или OpenAPI, а превращать существующие API-описания в воспроизводимые E2E CI-тесты, которые проверяют реальный пользовательский сценарий на только что запущенном приложении.**