Skip to content

Commit 29fd3cd

Browse files
KuznetsovRomanKuznetsovRoman
authored
Merge pull request #62 from gemini-testing/TESTPLANE-469.gh_action_docs
docs: add github action docs
2 parents 4653750 + d7ae44d commit 29fd3cd

File tree

5 files changed

+654
-0
lines changed

5 files changed

+654
-0
lines changed

‎docs/guides/how-to-run-on-github.mdx‎

Lines changed: 344 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,344 @@
1+
# How to Run Testplane in GitHub CI
2+
3+
## Introduction
4+
5+
To run Testplane in GitHub CI, there's a [dedicated GitHub Action][gh-actions-testplane] that:
6+
7+
- Handles caching of [local browsers](/docs/v8/guides/local-browsers) (if used);
8+
- Writes statistics about failed tests to [Job Summary](https://github.blog/news-insights/product-news/supercharging-github-actions-with-job-summaries/);
9+
- Helps display [HTML reports](../../html-reporter/html-reporter-setup) with test results in the browser.
10+
11+
## Configuration
12+
13+
Basic workflow to run Testplane:
14+
15+
```yml
16+
name: Testplane CI
17+
18+
on: # Workflow trigger rules
19+
push:
20+
branches: [master]
21+
pull_request:
22+
branches: [master]
23+
24+
jobs:
25+
testplane_test:
26+
runs-on: ubuntu-latest
27+
steps:
28+
- name: Checkout repository
29+
uses: actions/checkout@v4
30+
31+
- name: Use Node.js 18
32+
uses: actions/setup-node@v3
33+
with:
34+
node-version: 18.x
35+
36+
- name: Cache npm dependencies
37+
uses: actions/cache@v3
38+
with:
39+
path: ~/.npm
40+
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
41+
42+
- name: Install npm deps
43+
run: npm install
44+
45+
- name: Run Testplane
46+
id: testplane
47+
uses: gemini-testing/gh-actions-testplane@v1
48+
```
49+
50+
The "gemini-testing/gh-actions-testplane" action supports the following parameters:
51+
52+
<table>
53+
<thead>
54+
<tr>
55+
<td>
56+
<strong>Parameter</strong>
57+
</td>
58+
<td>
59+
<strong>Default Value</strong>
60+
</td>
61+
<td>
62+
<strong>Description</strong>
63+
</td>
64+
</tr>
65+
</thead>
66+
<tbody>
67+
<tr>
68+
<td>
69+
<code>cwd</code>
70+
</td>
71+
<td>
72+
<code>.</code>
73+
</td>
74+
<td>Relative directory to run Testplane from (useful for monorepos)</td>
75+
</tr>
76+
<tr>
77+
<td>
78+
<code>package-manager</code>
79+
</td>
80+
<td>
81+
<code>npm</code>
82+
</td>
83+
<td>Package manager used in the project (one of: npm, pnpm, yarn)</td>
84+
</tr>
85+
<tr>
86+
<td>
87+
<code>html-report-prefix</code>
88+
</td>
89+
<td>
90+
<code>testplane-reports</code>
91+
</td>
92+
<td>Path prefix for HTML reporter reports</td>
93+
</tr>
94+
<tr>
95+
<td>
96+
<code>config-path</code>
97+
</td>
98+
<td>
99+
<code>''</code>
100+
</td>
101+
<td>Path to custom Testplane config</td>
102+
</tr>
103+
<tr>
104+
<td>
105+
<code>storybook</code>
106+
</td>
107+
<td>
108+
<code>''</code>
109+
</td>
110+
<td>
111+
Enable to use @testplane/storybook plugin tests (e.g., <code>'true'</code>)
112+
</td>
113+
</tr>
114+
<tr>
115+
<td>
116+
<code>set</code>
117+
</td>
118+
<td>
119+
<code>''</code>
120+
</td>
121+
<td>List of test sets (comma-separated)</td>
122+
</tr>
123+
<tr>
124+
<td>
125+
<code>browser</code>
126+
</td>
127+
<td>
128+
<code>''</code>
129+
</td>
130+
<td>List of browsers for testing (comma-separated)</td>
131+
</tr>
132+
<tr>
133+
<td>
134+
<code>grep</code>
135+
</td>
136+
<td>
137+
<code>''</code>
138+
</td>
139+
<td>Grep expression to select specific tests</td>
140+
</tr>
141+
</tbody>
142+
</table>
143+
144+
<details>
145+
<summary>Example action with Testplane run using all parameters</summary>
146+
147+
```yml
148+
- name: Run Comprehensive Testplane Suite
149+
id: testplane
150+
uses: gemini-testing/gh-actions-testplane@v1
151+
with:
152+
cwd: "projects/my-project-name" # Specify project path (for monorepos)
153+
package-manager: "yarn" # Use yarn instead of npm
154+
html-report-prefix: "reports/testplane" # Save reports to existing reports directory (for preserving reports on gh-pages)
155+
config-path: "configs/testplane.conf.js" # Use custom config path
156+
storybook: "true" # Run tests from `@testplane/storybook` plugin
157+
set: "smoke,regression" # Run only selected test sets
158+
browser: "linux-chrome,linux-firefox" # Run tests in two browsers only
159+
grep: "Login" # Run only tests containing 'Login' in their name
160+
```
161+
162+
</details>
163+
164+
### Launching chrome in GitHub CI
165+
166+
GitHub CI only works with `headless` browsers.
167+
168+
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:
169+
170+
```js
171+
{
172+
// ... other Testplane settings
173+
headless: true, // Essential for GitHub CI
174+
browsers: {
175+
// ... other browsers,
176+
"linux-chrome": {
177+
// ... other browser settings
178+
desiredCapabilities: {
179+
// .. other desired capabilities
180+
browserName: "chrome",
181+
browserVersion: "135",
182+
"goog:chromeOptions": {
183+
args: ["--no-sandbox"] // Essential for GitHub CI
184+
}
185+
}
186+
}
187+
}
188+
}
189+
```
190+
191+
### Upload HTML Report Archive
192+
193+
Add this step to upload an HTML report archive:
194+
195+
```yml
196+
- name: Upload report
197+
if: always() && steps.testplane.outputs.html-report-path # Run step if report exists
198+
uses: actions/upload-artifact@v4
199+
with:
200+
name: testplane-html-report
201+
path: ${{ steps.testplane.outputs.html-report-path }} # Path where report is saved
202+
```
203+
204+
This will add an HTML report artifact to the job summary:
205+
206+
![github artifact](/img/docs/guides/how-to-run-on-github.job-summary-artifact.png)
207+
208+
### View HTML Reports in Browser
209+
210+
To view reports directly in the browser via GitHub Pages:
211+
212+
1. Set up GitHub Pages (Settings → Pages on the repository page):
213+
214+
![gh-pages setup](/img/docs/guides/how-to-run-on-github.gh-pages-setup.png)
215+
216+
2. Update job permissions:
217+
218+
```yml
219+
jobs:
220+
testplane_test:
221+
runs-on: ubuntu-latest
222+
permissions:
223+
contents: write # Required to deploy reports to gh-pages
224+
pull-requests: write # Required to post report links in PR comments
225+
steps:
226+
```
227+
228+
3. Replace the upload step with these two steps:
229+
230+
```yml
231+
- name: Deploy report # Deploys report to gh-pages
232+
if: always() && steps.testplane.outputs.html-report-path
233+
uses: peaceiris/actions-gh-pages@v4
234+
with:
235+
github_token: ${{ secrets.GITHUB_TOKEN }} # Auto-provided by GitHub
236+
publish_dir: ${{ steps.testplane.outputs.html-report-path }}
237+
destination_dir: ${{ steps.testplane.outputs.html-report-path }}
238+
keep_files: true
239+
240+
- name: Comment PR with link to Testplane HTML report
241+
if: always() && steps.testplane.outputs.html-report-path
242+
uses: thollander/actions-comment-pull-request@v3
243+
with:
244+
message: |
245+
### Testplane run finished
246+
Testplane HTML report is available at https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/${{ steps.testplane.outputs.html-report-path }}
247+
comment-tag: testplane_html_report_link
248+
```
249+
250+
PR comments will now include a direct link to the HTML report:
251+
252+
![gh-pages setup](/img/docs/guides/how-to-run-on-github.pull-request-comment.png)
253+
254+
Final workflow example:
255+
256+
```yml
257+
name: Testplane CI
258+
259+
on: # Workflow trigger rules
260+
push:
261+
branches: [master]
262+
pull_request:
263+
branches: [master]
264+
265+
jobs:
266+
testplane_test:
267+
runs-on: ubuntu-latest
268+
permissions:
269+
contents: write # Required to deploy reports to gh-pages
270+
pull-requests: write # Required to post report links in PR comments
271+
steps:
272+
- name: Checkout repository
273+
uses: actions/checkout@v4
274+
275+
- name: Use Node.js 18
276+
uses: actions/setup-node@v3
277+
with:
278+
node-version: 18.x
279+
280+
- name: Cache npm dependencies
281+
uses: actions/cache@v3
282+
with:
283+
path: ~/.npm
284+
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
285+
286+
- name: Install npm deps
287+
run: npm install
288+
289+
- name: Run Testplane
290+
id: testplane
291+
uses: gemini-testing/gh-actions-testplane@v1
292+
with:
293+
html-report-prefix: testplane-reports # Report directory path
294+
295+
- name: Deploy report # Deploys report to gh-pages
296+
if: always() && steps.testplane.outputs.html-report-path
297+
uses: peaceiris/actions-gh-pages@v4
298+
with:
299+
github_token: ${{ secrets.GITHUB_TOKEN }}
300+
publish_dir: ${{ steps.testplane.outputs.html-report-path }}
301+
destination_dir: ${{ steps.testplane.outputs.html-report-path }}
302+
keep_files: true
303+
304+
- name: Comment PR with link to Testplane HTML report
305+
if: always() && steps.testplane.outputs.html-report-path
306+
uses: thollander/actions-comment-pull-request@v3
307+
with:
308+
message: |
309+
### Testplane run finished
310+
Testplane HTML report is available at https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/${{ steps.testplane.outputs.html-report-path }}
311+
comment-tag: testplane_html_report_link
312+
```
313+
314+
### Clean Up Old Reports
315+
316+
To periodically remove old reports, use [gemini-testing/gh-actions-reports-ttl-cleaner][gh-actions-reports-ttl-cleaner]:
317+
318+
```yml
319+
name: Remove old Testplane html reports
320+
on:
321+
schedule: # Runs once daily
322+
- cron: 0 0 * * *
323+
jobs:
324+
collect:
325+
name: Remove old Testplane html reports
326+
runs-on: ubuntu-24.04
327+
steps:
328+
- name: Checkout repository
329+
uses: actions/checkout@v2
330+
with:
331+
ref: gh-pages
332+
fetch-depth: 0
333+
# GitHub token with "contents: write" permissions.
334+
# Learn more: https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions
335+
token: ...
336+
- name: Remove reports
337+
uses: gemini-testing/gh-actions-reports-ttl-cleaner@v1
338+
with:
339+
html-report-prefix: testplane-reports # Report directory path
340+
ttl: 90 # Delete reports older than 90 days
341+
```
342+
343+
[gh-actions-testplane]: https://github.com/gemini-testing/gh-actions-testplane
344+
[gh-actions-reports-ttl-cleaner]: https://github.com/gemini-testing/gh-actions-reports-ttl-cleaner

0 commit comments

Comments
 (0)