diff --git a/docs/guides/how-to-run-on-github.mdx b/docs/guides/how-to-run-on-github.mdx new file mode 100644 index 0000000..53e3acc --- /dev/null +++ b/docs/guides/how-to-run-on-github.mdx @@ -0,0 +1,344 @@ +# How to Run Testplane in GitHub CI + +## Introduction + +To run Testplane in GitHub CI, there's a [dedicated GitHub Action][gh-actions-testplane] that: + +- Handles caching of [local browsers](/docs/v8/guides/local-browsers) (if used); +- Writes statistics about failed tests to [Job Summary](https://github.blog/news-insights/product-news/supercharging-github-actions-with-job-summaries/); +- Helps display [HTML reports](../../html-reporter/html-reporter-setup) with test results in the browser. + +## Configuration + +Basic workflow to run Testplane: + +```yml +name: Testplane CI + +on: # Workflow trigger rules + push: + branches: [master] + pull_request: + branches: [master] + +jobs: + testplane_test: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Use Node.js 18 + uses: actions/setup-node@v3 + with: + node-version: 18.x + + - name: Cache npm dependencies + uses: actions/cache@v3 + with: + path: ~/.npm + key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} + + - name: Install npm deps + run: npm install + + - name: Run Testplane + id: testplane + uses: gemini-testing/gh-actions-testplane@v1 +``` + +The "gemini-testing/gh-actions-testplane" action supports the following parameters: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Parameter + + Default Value + + Description +
+ cwd + + . + Relative directory to run Testplane from (useful for monorepos)
+ package-manager + + npm + Package manager used in the project (one of: npm, pnpm, yarn)
+ html-report-prefix + + testplane-reports + Path prefix for HTML reporter reports
+ config-path + + '' + Path to custom Testplane config
+ storybook + + '' + + Enable to use @testplane/storybook plugin tests (e.g., 'true') +
+ set + + '' + List of test sets (comma-separated)
+ browser + + '' + List of browsers for testing (comma-separated)
+ grep + + '' + Grep expression to select specific tests
+ +
+ Example action with Testplane run using all parameters + +```yml +- name: Run Comprehensive Testplane Suite + id: testplane + uses: gemini-testing/gh-actions-testplane@v1 + with: + cwd: "projects/my-project-name" # Specify project path (for monorepos) + package-manager: "yarn" # Use yarn instead of npm + html-report-prefix: "reports/testplane" # Save reports to existing reports directory (for preserving reports on gh-pages) + config-path: "configs/testplane.conf.js" # Use custom config path + storybook: "true" # Run tests from `@testplane/storybook` plugin + set: "smoke,regression" # Run only selected test sets + browser: "linux-chrome,linux-firefox" # Run tests in two browsers only + grep: "Login" # Run only tests containing 'Login' in their name +``` + +
+ +### Launching chrome in GitHub CI + +GitHub CI only works with `headless` browsers. + +Also, to ensure Chrome browsers function properly in CI, you need to add the `--no-sandbox` argument to the Chrome browser launch options as follows: + +```js +{ + // ... other Testplane settings + headless: true, // Essential for GitHub CI + browsers: { + // ... other browsers, + "linux-chrome": { + // ... other browser settings + desiredCapabilities: { + // .. other desired capabilities + browserName: "chrome", + browserVersion: "135", + "goog:chromeOptions": { + args: ["--no-sandbox"] // Essential for GitHub CI + } + } + } + } +} +``` + +### Upload HTML Report Archive + +Add this step to upload an HTML report archive: + +```yml +- name: Upload report + if: always() && steps.testplane.outputs.html-report-path # Run step if report exists + uses: actions/upload-artifact@v4 + with: + name: testplane-html-report + path: ${{ steps.testplane.outputs.html-report-path }} # Path where report is saved +``` + +This will add an HTML report artifact to the job summary: + +![github artifact](/img/docs/guides/how-to-run-on-github.job-summary-artifact.png) + +### View HTML Reports in Browser + +To view reports directly in the browser via GitHub Pages: + +1. Set up GitHub Pages (Settings → Pages on the repository page): + +![gh-pages setup](/img/docs/guides/how-to-run-on-github.gh-pages-setup.png) + +2. Update job permissions: + +```yml +jobs: + testplane_test: + runs-on: ubuntu-latest + permissions: + contents: write # Required to deploy reports to gh-pages + pull-requests: write # Required to post report links in PR comments + steps: +``` + +3. Replace the upload step with these two steps: + +```yml +- name: Deploy report # Deploys report to gh-pages + if: always() && steps.testplane.outputs.html-report-path + uses: peaceiris/actions-gh-pages@v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} # Auto-provided by GitHub + publish_dir: ${{ steps.testplane.outputs.html-report-path }} + destination_dir: ${{ steps.testplane.outputs.html-report-path }} + keep_files: true + +- name: Comment PR with link to Testplane HTML report + if: always() && steps.testplane.outputs.html-report-path + uses: thollander/actions-comment-pull-request@v3 + with: + message: | + ### Testplane run finished + Testplane HTML report is available at https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/${{ steps.testplane.outputs.html-report-path }} + comment-tag: testplane_html_report_link +``` + +PR comments will now include a direct link to the HTML report: + +![gh-pages setup](/img/docs/guides/how-to-run-on-github.pull-request-comment.png) + +Final workflow example: + +```yml +name: Testplane CI + +on: # Workflow trigger rules + push: + branches: [master] + pull_request: + branches: [master] + +jobs: + testplane_test: + runs-on: ubuntu-latest + permissions: + contents: write # Required to deploy reports to gh-pages + pull-requests: write # Required to post report links in PR comments + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Use Node.js 18 + uses: actions/setup-node@v3 + with: + node-version: 18.x + + - name: Cache npm dependencies + uses: actions/cache@v3 + with: + path: ~/.npm + key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} + + - name: Install npm deps + run: npm install + + - name: Run Testplane + id: testplane + uses: gemini-testing/gh-actions-testplane@v1 + with: + html-report-prefix: testplane-reports # Report directory path + + - name: Deploy report # Deploys report to gh-pages + if: always() && steps.testplane.outputs.html-report-path + uses: peaceiris/actions-gh-pages@v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ${{ steps.testplane.outputs.html-report-path }} + destination_dir: ${{ steps.testplane.outputs.html-report-path }} + keep_files: true + + - name: Comment PR with link to Testplane HTML report + if: always() && steps.testplane.outputs.html-report-path + uses: thollander/actions-comment-pull-request@v3 + with: + message: | + ### Testplane run finished + Testplane HTML report is available at https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/${{ steps.testplane.outputs.html-report-path }} + comment-tag: testplane_html_report_link +``` + +### Clean Up Old Reports + +To periodically remove old reports, use [gemini-testing/gh-actions-reports-ttl-cleaner][gh-actions-reports-ttl-cleaner]: + +```yml +name: Remove old Testplane html reports +on: + schedule: # Runs once daily + - cron: 0 0 * * * +jobs: + collect: + name: Remove old Testplane html reports + runs-on: ubuntu-24.04 + steps: + - name: Checkout repository + uses: actions/checkout@v2 + with: + ref: gh-pages + fetch-depth: 0 + # GitHub token with "contents: write" permissions. + # Learn more: https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions + token: ... + - name: Remove reports + uses: gemini-testing/gh-actions-reports-ttl-cleaner@v1 + with: + html-report-prefix: testplane-reports # Report directory path + ttl: 90 # Delete reports older than 90 days +``` + +[gh-actions-testplane]: https://github.com/gemini-testing/gh-actions-testplane +[gh-actions-reports-ttl-cleaner]: https://github.com/gemini-testing/gh-actions-reports-ttl-cleaner diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/guides/how-to-run-on-github.mdx b/i18n/ru/docusaurus-plugin-content-docs/current/guides/how-to-run-on-github.mdx new file mode 100644 index 0000000..3f9533f --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/guides/how-to-run-on-github.mdx @@ -0,0 +1,310 @@ +# Как запустить Testplane в GitHub CI + +## Введение + +Для запуска Testplane в GitHub CI имеется [специальный Github Action][gh-actions-testplane], который: + +- Занимается кэшированием [локальных браузеров](/docs/v8/guides/local-browsers) (при использовании); +- Пишет статистику упавших тестов в [Job summary](https://github.blog/news-insights/product-news/supercharging-github-actions-with-job-summaries/); +- Помогает с отображением [html-отчета](../../html-reporter/html-reporter-setup) с результатами прогона тестов в браузере. + +## Настройка + +Базовый workflow с запуском Testplane: + +```yml +name: Testplane CI + +on: # Правила запуска workflow + push: + branches: [master] + pull_request: + branches: [master] + +jobs: + testplane_test: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Use Node.js 18 + uses: actions/setup-node@v3 + with: + node-version: 18.x + + - name: Cache npm dependencies + uses: actions/cache@v3 + with: + path: ~/.npm + key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} + + - name: Install npm deps + run: npm install + + - name: Run Testplane + id: testplane + uses: gemini-testing/gh-actions-testplane@v1 +``` + +Action "gemini-testing/gh-actions-testplane" поддерживает следующие параметры: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
**Параметр****Значение по умолчанию****Описание**
`cwd``.` + Относительная директория для запуска Testplane (полезно для запуска в + монорепозиториях) +
`package-manager``npm`Пакетный менеджер, используемый в проекте (один из: npm, pnpm, yarn)
`html-report-prefix``testplane-reports`Префикс пути для отчётов html-репортера
`config-path``''`Путь к пользовательскому конфигу Testplane
`storybook``''` + Если включено, использует тесты плагина @testplane/storybook (например:{" "} + 'true') +
`set``''`Список наборов тестов (через запятую)
`browser``''`Список браузеров для тестирования (через запятую)
`grep``''`Выражение grep для выбора конкретных тестов
+ +
+ Пример action с запуском Testplane со всеми параметрами + +```yml +- name: Run Comprehensive Testplane Suite + id: testplane + uses: gemini-testing/gh-actions-testplane@v1 + with: + cwd: "projects/my-project-name" # Указываем путь до проекта (для монорепозиториев) + package-manager: "yarn" # Используем yarn вместо npm + html-report-prefix: "reports/testplane" # Сохраняем отчеты в имеющуюся директорию reports (для сохранения отчетов на gh-pages) + config-path: "configs/testplane.conf.js" # Используем кастомный путь до конфига + storybook: "true" # Запускаем тесты плагина `@testplane/storybook` + set: "smoke,regression" # Запускаем только тесты выбранных сетов + browser: "linux-chrome,linux-firefox" # Запускаем тесты только в двух браузерах + grep: "Login" # Запускаем только тесты, в названии которых есть слово Login +``` + +
+ +### Запуск браузеров в GitHub CI + +GitHub CI поддерживает запуск только `headless` браузеров. + +Также, чтобы chrome браузеры могли корректно работать в CI, необходимо добавить `--no-sandbox` в аргументы запуска chrome браузера следующим образом: + +```js +{ + // ... other Testplane settings + headless: true, // Essential for GitHub CI + browsers: { + // ... other browsers, + "linux-chrome": { + // ... other browser settings + desiredCapabilities: { + // .. other desired capabilities + browserName: "chrome", + browserVersion: "135", + "goog:chromeOptions": { + args: ["--no-sandbox"] // Essential for GitHub CI + } + } + } + } +} +``` + +### Выгрузка архива с html-отчетом + +Чтобы выгрузить архив с html-отчетом, к базовому workflow можно добавить следующий шаг: + +```yml +- name: Upload report + if: always() && steps.testplane.outputs.html-report-path # Запускаем шаг при наличии отчета + uses: actions/upload-artifact@v4 + with: + name: testplane-html-report + path: ${{ steps.testplane.outputs.html-report-path }} # Путь, по которому сохранился отчет +``` + +С этим шагом, в Summary запуска задачи будет располагаться артефакт с html-отчетом: + +![github artifact](/img/docs/guides/how-to-run-on-github.job-summary-artifact.png) + +### Просмотр html-отчета с результатами запуска в браузере + +Для того, чтобы смотреть отчеты прямо из браузера с помощью GitHub Pages: + +1. Настройте GitHub Pages (Settings → Pages на странице репозитория): + +![gh-pages setup](/img/docs/guides/how-to-run-on-github.gh-pages-setup.png) + +2. Обновите разрешения задачи: + +```yml +jobs: + testplane_test: + runs-on: ubuntu-latest + permissions: + contents: write # Необходимо для отправки отчетов в ветку gh-pages + pull-requests: write # Необходимо для отправки комментария со ссылкой на отчет к пулл-реквесту + steps: +``` + +3. Вместо предыдущего шага "Upload report" добавьте два следующих: + +```yml +- name: Deploy report # Выкладывает отчет на gh-pages + if: always() && steps.testplane.outputs.html-report-path + uses: peaceiris/actions-gh-pages@v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} # Токен поставляется Github, дополнительной настройки не требуется + publish_dir: ${{ steps.testplane.outputs.html-report-path }} + destination_dir: ${{ steps.testplane.outputs.html-report-path }} + keep_files: true + +- name: Comment PR with link to Testplane HTML report + if: always() && steps.testplane.outputs.html-report-path + uses: thollander/actions-comment-pull-request@v3 + with: + message: | + ### Testplane run finisned + Testplane HTML-report is available at https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/${{ steps.testplane.outputs.html-report-path }} + comment-tag: testplane_html_report_link +``` + +Теперь в пулл-реквесте будет комментарий со ссылкой на Testplane html отчет, который можно будет открыть прямо в браузере. + +![gh-pages setup](/img/docs/guides/how-to-run-on-github.pull-request-comment.png) + +Итоговый GitHub Workflow будет выглядеть следующим образом: + +```yml +name: Testplane CI + +on: # Правила запуска workflow + push: + branches: [master] + pull_request: + branches: [master] + +jobs: + testplane_test: + runs-on: ubuntu-latest + permissions: + contents: write # Необходимо для отправки отчетов в ветку gh-pages + pull-requests: write # Необходимо для отправки комментария со ссылкой на отчет к пулл-реквесту + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Use Node.js 18 + uses: actions/setup-node@v3 + with: + node-version: 18.x + + - name: Cache npm dependencies + uses: actions/cache@v3 + with: + path: ~/.npm + key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} + + - name: Install npm deps + run: npm install + + - name: Run Testplane + id: testplane + uses: gemini-testing/gh-actions-testplane@v1 + with: + html-report-prefix: testplane-reports # Путь до директории с отчетами + + - name: Deploy report # Выкладывает отчет на gh-pages + if: always() && steps.testplane.outputs.html-report-path + uses: peaceiris/actions-gh-pages@v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} # Токен поставляется Github, дополнительной настройки не требуется + publish_dir: ${{ steps.testplane.outputs.html-report-path }} + destination_dir: ${{ steps.testplane.outputs.html-report-path }} + keep_files: true + + - name: Comment PR with link to Testplane HTML report + if: always() && steps.testplane.outputs.html-report-path + uses: thollander/actions-comment-pull-request@v3 + with: + message: | + ### Testplane run finisned + Testplane HTML-report is available at https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/${{ steps.testplane.outputs.html-report-path }} + comment-tag: testplane_html_report_link +``` + +Со временем, таких отчетов может накопиться слишком много и может возникнуть потребность удалять старые отчеты. + +Периодически удалять старые отчеты можно с помощью следующего workflow c action [gemini-testing/gh-actions-reports-ttl-cleaner][gh-actions-reports-ttl-cleaner]: + +```yml +name: Remove old Testplane html reports +on: + schedule: # Запускается раз в день + - cron: 0 0 * * * +jobs: + collect: + name: Remove old Testplane html reports + runs-on: ubuntu-24.04 + steps: + - name: Checkout repository + uses: actions/checkout@v2 + with: + ref: gh-pages + fetch-depth: 0 + # Токен доступа к GitHub с правами доступа "contents: write". + # Подробнее: https://docs.github.com/ru/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions + token: ... + - name: Remove reports + uses: gemini-testing/gh-actions-reports-ttl-cleaner@v1 + with: + html-report-prefix: testplane-reports # Путь до директории с отчетами + ttl: 90 # Удаляются отчеты, старше 90 дней +``` + +[gh-actions-testplane]: https://github.com/gemini-testing/gh-actions-testplane +[gh-actions-reports-ttl-cleaner]: https://github.com/gemini-testing/gh-actions-reports-ttl-cleaner diff --git a/static/img/docs/guides/how-to-run-on-github.gh-pages-setup.png b/static/img/docs/guides/how-to-run-on-github.gh-pages-setup.png new file mode 100644 index 0000000..7a332ea Binary files /dev/null and b/static/img/docs/guides/how-to-run-on-github.gh-pages-setup.png differ diff --git a/static/img/docs/guides/how-to-run-on-github.job-summary-artifact.png b/static/img/docs/guides/how-to-run-on-github.job-summary-artifact.png new file mode 100644 index 0000000..3c0a122 Binary files /dev/null and b/static/img/docs/guides/how-to-run-on-github.job-summary-artifact.png differ diff --git a/static/img/docs/guides/how-to-run-on-github.pull-request-comment.png b/static/img/docs/guides/how-to-run-on-github.pull-request-comment.png new file mode 100644 index 0000000..6794f42 Binary files /dev/null and b/static/img/docs/guides/how-to-run-on-github.pull-request-comment.png differ