diff --git a/README.md b/README.md index 3752f55..abafac3 100644 --- a/README.md +++ b/README.md @@ -1,140 +1,163 @@ -# OTUS HW8: Jenkins + Ansible + JJB + Docker Slaves +# OTUS HW8: Jenkins + Ansible + JJB + Docker -Полностью автоматизированный проект для ДЗ8: -- Jenkins в Docker; -- reverse proxy (Nginx); +Полностью автоматизированная раскатка ДЗ8: +- Jenkins controller в Docker; +- reverse proxy Nginx; - локальный Docker Registry; -- docker-slaves (агенты Jenkins); -- Jenkins Job Builder (JJB) для автоматического создания/обновления job; -- Ansible playbook для раскатки всего с нуля; -- 6 готовых job, включая runner с параллельным запуском тестов; -- Allure-отчеты для Selenium и Appium job. +- Jenkins agents (docker slaves); +- Jenkins Job Builder (JJB), без ручного создания job; +- Ansible для полного подъема/сноса стенда; +- 6 job (runner + uploader + 3 тестовые + infra check); +- Allure отчеты для UI и mobile. -Проект использует локальные домашки из корня: -- `C:/Users/spawn/IdeaProjects/otus-autotests/homework_4` (Selenium + Citrus); -- `C:/Users/spawn/IdeaProjects/otus-autotests/hw7` (Appium). +Тестовые проекты всегда берутся из Git в runtime: +- `homework_4` (Selenium + API Citrus); +- `homework_7` (Appium, APK скачивается автоматически через `APP_URL`). -## Что развертывается +## Что поднимается -### Сервисы (Docker Compose) -- `registry` (`localhost:5005`) — хранение образов тестов и слейвов. -- `jenkins` (`localhost:8081`) — Jenkins controller (JCasC). -- `nginx` (`localhost:8088`) — внешний вход в Jenkins. -- `agent-maven` — swarm-agent с label `maven docker`. -- `agent-jjb` — swarm-agent с label `jjb docker`. -- `jobs_uploader` — one-shot контейнер, который накатывает job через `jenkins-jobs update`. +Сервисы: +- Jenkins: `http://localhost:8081` +- Jenkins через Nginx: `http://localhost:8088` +- Registry: `http://localhost:5005/v2/` +- Agent `maven` (docker label: `maven docker`) +- Agent `jjb` (docker label: `jjb docker`) +- one-shot `jobs_uploader` container -### Автоматизация (Ansible) -Playbook: -1. Поднимает `registry + jenkins + nginx`. -2. Ждет готовности Jenkins. -3. Собирает и пушит в registry все нужные образы: - - `localhost:5005/otus/slave-maven:1.0.0` - - `localhost:5005/otus/slave-jjb:1.0.0` - - `localhost:5005/otus/test-selenium:1.0.0` - - `localhost:5005/otus/test-api:1.0.0` - - `localhost:5005/otus/test-mobile:1.0.0` -4. Поднимает слейвы. -5. Накатывает все job через JJB. +Контроллер не исполняет сборки (`numExecutors: 0`, mode `EXCLUSIVE`), все job идут только на агентах. -По умолчанию UI через nginx опубликован на `8088`, чтобы не конфликтовать с Selenoid UI из `homework_4` (часто занимает `8080`). +## 6 job -## 6 Jenkins job +1. `jobs-uploader` - накатывает/обновляет job через JJB. +2. `infra-health-check` - проверка Jenkins/Registry/образов/агентов. +3. `qa-selenium-tests` - Selenium/Selenide с выбором браузера. +4. `qa-api-citrus-tests` - API тесты. +5. `qa-mobile-appium-tests` - Appium тесты, APK через `APP_URL`. +6. `qa-runner` - параллельный запуск `selenium + api + mobile`. -1. `jobs-uploader` — обновление всех job из `hw8/config/jobs`. -2. `infra-health-check` — проверка инфраструктуры и образов. -3. `qa-selenium-tests` — Selenium/Selenide (browser parameter + Allure). -4. `qa-mobile-appium-tests` — Appium (APP_URL для автоскачивания APK + Allure). -5. `qa-api-citrus-tests` — API (citrus-tests). -6. `qa-runner` — запускает `qa-selenium-tests`, `qa-mobile-appium-tests`, `qa-api-citrus-tests` параллельно. +Вьюхи в Jenkins: +- `DevOps` +- `QA-Runner` +- `QA-Tests` +- `all` -Есть вьюхи: -- `DevOps`; -- `QA`. +## Варианты раскатки job -## Важные требования окружения -- Docker + Docker Compose V2. -- Ansible. -- Linux/WSL2 host для mobile-части (желательно с `/dev/kvm` для эмуляторов `budtmo/docker-android`). -- Доступ к БД для `hw7` (`DB_URL/DB_USER/DB_PASSWORD`). +Реализованы 2 режима через `jobs_profile`: +- `devops` - только `jobs-uploader` и `infra-health-check` +- `full` - весь набор job (режим по умолчанию) -## Быстрый старт с нуля +## Требования + +- Docker + Docker Compose V2 +- Ansible (в Linux/WSL) +- доступ в интернет для pull базовых образов и maven dependencies +- для mobile: Linux/WSL2 с `/dev/kvm` (желательно для стабильной эмуляции) + +## Запуск с нуля + +Подготовка: -### 1. Перейти в `hw8` -```bash -cd C:/Users/spawn/IdeaProjects/otus-autotests/hw8 -``` - -### 2. Подготовить `.env` для compose ```bash +cd /path/to/hw8 cp compose/.env.example compose/.env ``` -Обязательно заполните в `compose/.env`: -- `JENKINS_ADMIN_ID`, `JENKINS_ADMIN_PASSWORD`; -- `MOBILE_DB_PASSWORD` (если не хотите передавать `DB_PASSWORD` руками в параметрах job); -- при необходимости `NGINX_PORT` и `JENKINS_URL_PUBLIC`. -### 3. Запустить полный деплой playbook +Минимум заполнить в `compose/.env`: +- `JENKINS_ADMIN_ID` +- `JENKINS_ADMIN_PASSWORD` +- `MOBILE_DB_PASSWORD` + +### Вариант 1: только DevOps + +`bash`: +```bash +ansible-playbook -i ansible/inventory/hosts.ini ansible/playbooks/site.yml -e jobs_profile=devops +``` + +`wsl`: +```powershell +wsl bash -lc "cd /mnt/c/Users/spawn/IdeaProjects/otus-autotests/hw8 && ansible-playbook -i ansible/inventory/hosts.ini ansible/playbooks/site.yml -e jobs_profile=devops" +``` + +После этого запускаете `jobs-uploader` (дефолт `JJB_PATH=/workspace/hw8/config/jobs`) и получаете QA job. + +### Вариант 2: сразу все job + +`bash`: ```bash ansible-playbook -i ansible/inventory/hosts.ini ansible/playbooks/site.yml ``` -Если запускаете из Windows PowerShell без установленного Ansible: +`wsl`: ```powershell wsl bash -lc "cd /mnt/c/Users/spawn/IdeaProjects/otus-autotests/hw8 && ansible-playbook -i ansible/inventory/hosts.ini ansible/playbooks/site.yml" ``` -### 4. Открыть Jenkins -- через nginx: `http://localhost:8088` -- напрямую: `http://localhost:8081` +Примечание: можно запускать и без `-e jobs_profile=full` — по умолчанию в `site.yml` используется профиль `full` (раскатываются все job). -Логин/пароль: из `compose/.env` (`JENKINS_ADMIN_ID`, `JENKINS_ADMIN_PASSWORD`). +## Запуск тестов -## Как запускать тесты +Рекомендуемый вход: `QA-Runner` -> `qa-runner` -> `Build with Parameters`. -### Рекомендуемый запуск -Запустить `qa-runner` через **Build with Parameters**. +`qa-runner` запускает в параллели: +- `qa-selenium-tests` +- `qa-api-citrus-tests` +- `qa-mobile-appium-tests` -### Selenium отдельно -Запустить `qa-selenium-tests`: -- `BROWSER`: `chrome|firefox`; -- `HEADLESS`: `true|false`. +И всегда публикует `runner-summary.txt` с: +- номерами дочерних сборок; +- статусами; +- ссылками на каждую дочернюю job. -### Appium отдельно -Запустить `qa-mobile-appium-tests`: -- `DB_PASSWORD` (по умолчанию `student`, если пусто — берется из env `MOBILE_DB_PASSWORD` Jenkins controller); -- `APP_URL` по умолчанию: `http://wiremock:8080/wishlist.apk`. -- дефолтные пароли тест-аккаунтов из `hw7`: `user1us/user2us/user3us` (соответствуют логинам). +## Отчетность -`APP_URL` передается в capability `app`, поэтому APK скачивается автоматически Appium-сервером эмулятора. +`qa-selenium-tests` и `qa-mobile-appium-tests` публикуют: +- Allure report (`/allure`); +- JUnit результаты; +- `run-info.txt`; +- `target/**` артефакты (включая скриншоты/логи тестового проекта, если они туда пишутся). +- для mobile дополнительно сохраняются `project/target/mobile-debug/*` (`docker logs` и `docker inspect` эмуляторов/сети). +- для mobile параметр `SUREFIRE_RERUN_FAILING` (по умолчанию `1`) снижает flaky-падения Appium-сессий без правок кода HW7. -## Отчеты -- `qa-selenium-tests` публикует Allure + JUnit. -- `qa-mobile-appium-tests` публикует Allure + JUnit. -- артефакты `target/**` архивируются в Jenkins. +Дополнительно в Allure: +- `environment.properties` +- `executor.json` +- `categories.json` -## Структура проекта +Также в `currentBuild.description` пишется, кто запустил job и ключевые параметры. -- `ansible/` — playbook раскатки/удаления. -- `compose/` — инфраструктура Jenkins (compose, Dockerfile, JCasC, nginx, jobs_uploader). -- `compose/images/` — Dockerfile для слейвов и test-runner образов. -- `config/jobs/` — JJB YAML + Groovy pipeline scripts + views. +## Команды для повторного запуска с нуля -## Повторное обновление job +Снести все: -1. Через Jenkins job `jobs-uploader`, либо -2. Ручным one-shot: -```bash -docker compose -f compose/docker-compose.yml --env-file compose/.env run --rm jobs_uploader -``` - -## Полное удаление стенда ```bash ansible-playbook -i ansible/inventory/hosts.ini ansible/playbooks/down.yml ``` -## Чистый повторный запуск (reset + deploy) +```powershell +wsl bash -lc "cd /mnt/c/Users/spawn/IdeaProjects/otus-autotests/hw8 && ansible-playbook -i ansible/inventory/hosts.ini ansible/playbooks/down.yml" +``` + +Полный reset + deploy: + +По умолчанию эта команда раскатывает профиль `full` (все job: DevOps + QA), так как в `ansible/playbooks/site.yml` задано `jobs_profile | default('full')`. + ```bash ansible-playbook -i ansible/inventory/hosts.ini ansible/playbooks/down.yml ansible-playbook -i ansible/inventory/hosts.ini ansible/playbooks/site.yml ``` + +```powershell +wsl bash -lc "cd /mnt/c/Users/spawn/IdeaProjects/otus-autotests/hw8 && ansible-playbook -i ansible/inventory/hosts.ini ansible/playbooks/down.yml && ansible-playbook -i ansible/inventory/hosts.ini ansible/playbooks/site.yml" +``` + +Если нужен только профиль `devops`, добавьте `-e jobs_profile=devops` во вторую команду (`site.yml`). + +## Где что лежит + +- `ansible/` - playbook раскатки/удаления +- `compose/` - инфраструктура Jenkins/agents/registry/nginx +- `compose/images/` - Dockerfile для агентов и test-runner образов +- `config/jobs/` - full JJB (DevOps + QA) +- `config/jobs-devops/` - JJB профиль только для DevOps job