Skip to content

Commit cc8ab49

Browse files
KuznetsovRomanKuznetsovRoman
committed
docs: add github action docs
1 parent 4653750 commit cc8ab49

File tree

5 files changed

+627
-0
lines changed

5 files changed

+627
-0
lines changed

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

Lines changed: 332 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,332 @@
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+
To modify default parameters, pass values in the `with` section. For example, to run Testplane in a monorepo subdirectory:
145+
146+
```yml
147+
- name: Run Testplane
148+
id: testplane
149+
uses: gemini-testing/gh-actions-testplane@v1
150+
with:
151+
cwd: ./projects/my-project
152+
```
153+
154+
### Launching chrome in GitHub CI
155+
156+
Here’s the English translation of your text:
157+
158+
---
159+
160+
To ensure Chrome browsers function properly in CI, you need to add the `--no-sandbox` argument to the Chrome browser launch options as follows:
161+
162+
```js
163+
{
164+
// ... other browsers
165+
"linux-chrome": {
166+
// ... other browser settings
167+
"desiredCapabilities": {
168+
// ... other desired capabilities
169+
"browserName": "chrome",
170+
"browserVersion": "135",
171+
"goog:chromeOptions": {
172+
"args": ["--no-sandbox"]
173+
}
174+
}
175+
}
176+
}
177+
```
178+
179+
### Upload HTML Report Archive
180+
181+
Add this step to upload an HTML report archive:
182+
183+
```yml
184+
- name: Upload report
185+
if: always() && steps.testplane.outputs.html-report-path # Run step if report exists
186+
uses: actions/upload-artifact@v4
187+
with:
188+
name: testplane-html-report
189+
path: ${{ steps.testplane.outputs.html-report-path }} # Path where report is saved
190+
```
191+
192+
This will add an HTML report artifact to the job summary:
193+
194+
![github artifact](/img/docs/guides/how-to-run-on-github.job-summary-artifact.png)
195+
196+
### View HTML Reports in Browser
197+
198+
To view reports directly in the browser via GitHub Pages:
199+
200+
1. Set up GitHub Pages (Settings → Pages on the repository page):
201+
202+
![gh-pages setup](/img/docs/guides/how-to-run-on-github.gh-pages-setup.png)
203+
204+
2. Update job permissions:
205+
206+
```yml
207+
jobs:
208+
testplane_test:
209+
runs-on: ubuntu-latest
210+
permissions:
211+
contents: write # Required to deploy reports to gh-pages
212+
pull-requests: write # Required to post report links in PR comments
213+
steps:
214+
```
215+
216+
3. Replace the upload step with these two steps:
217+
218+
```yml
219+
- name: Deploy report # Deploys report to gh-pages
220+
if: always() && steps.testplane.outputs.html-report-path
221+
uses: peaceiris/actions-gh-pages@v4
222+
with:
223+
github_token: ${{ secrets.GITHUB_TOKEN }} # Auto-provided by GitHub
224+
publish_dir: ${{ steps.testplane.outputs.html-report-path }}
225+
destination_dir: ${{ steps.testplane.outputs.html-report-path }}
226+
keep_files: true
227+
228+
- name: Comment PR with link to Testplane HTML report
229+
if: always() && steps.testplane.outputs.html-report-path
230+
uses: thollander/actions-comment-pull-request@v3
231+
with:
232+
message: |
233+
### Testplane run finished
234+
Testplane HTML report is available at https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/${{ steps.testplane.outputs.html-report-path }}
235+
comment-tag: testplane_html_report_link
236+
```
237+
238+
PR comments will now include a direct link to the HTML report:
239+
240+
![gh-pages setup](/img/docs/guides/how-to-run-on-github.pull-request-comment.png)
241+
242+
Final workflow example:
243+
244+
```yml
245+
name: Testplane CI
246+
247+
on: # Workflow trigger rules
248+
push:
249+
branches: [master]
250+
pull_request:
251+
branches: [master]
252+
253+
jobs:
254+
testplane_test:
255+
runs-on: ubuntu-latest
256+
permissions:
257+
contents: write # Required to deploy reports to gh-pages
258+
pull-requests: write # Required to post report links in PR comments
259+
steps:
260+
- name: Checkout repository
261+
uses: actions/checkout@v4
262+
263+
- name: Use Node.js 18
264+
uses: actions/setup-node@v3
265+
with:
266+
node-version: 18.x
267+
268+
- name: Cache npm dependencies
269+
uses: actions/cache@v3
270+
with:
271+
path: ~/.npm
272+
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
273+
274+
- name: Install npm deps
275+
run: npm install
276+
277+
- name: Run Testplane
278+
id: testplane
279+
uses: gemini-testing/gh-actions-testplane@v1
280+
with:
281+
html-report-prefix: testplane-reports # Report directory path
282+
283+
- name: Deploy report # Deploys report to gh-pages
284+
if: always() && steps.testplane.outputs.html-report-path
285+
uses: peaceiris/actions-gh-pages@v4
286+
with:
287+
github_token: ${{ secrets.GITHUB_TOKEN }}
288+
publish_dir: ${{ steps.testplane.outputs.html-report-path }}
289+
destination_dir: ${{ steps.testplane.outputs.html-report-path }}
290+
keep_files: true
291+
292+
- name: Comment PR with link to Testplane HTML report
293+
if: always() && steps.testplane.outputs.html-report-path
294+
uses: thollander/actions-comment-pull-request@v3
295+
with:
296+
message: |
297+
### Testplane run finished
298+
Testplane HTML report is available at https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/${{ steps.testplane.outputs.html-report-path }}
299+
comment-tag: testplane_html_report_link
300+
```
301+
302+
### Clean Up Old Reports
303+
304+
To periodically remove old reports, use [gemini-testing/gh-actions-reports-ttl-cleaner][gh-actions-reports-ttl-cleaner]:
305+
306+
```yml
307+
name: Remove old Testplane html reports
308+
on:
309+
schedule: # Runs once daily
310+
- cron: 0 0 * * *
311+
jobs:
312+
collect:
313+
name: Remove old Testplane html reports
314+
runs-on: ubuntu-24.04
315+
steps:
316+
- name: Checkout repository
317+
uses: actions/checkout@v2
318+
with:
319+
ref: gh-pages
320+
fetch-depth: 0
321+
# GitHub token with "contents: write" permissions.
322+
# Learn more: https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions
323+
token: ...
324+
- name: Remove reports
325+
uses: gemini-testing/gh-actions-reports-ttl-cleaner@v1
326+
with:
327+
html-report-prefix: testplane-reports # Report directory path
328+
ttl: 90 # Delete reports older than 90 days
329+
```
330+
331+
[gh-actions-testplane]: https://github.com/gemini-testing/gh-actions-testplane
332+
[gh-actions-reports-ttl-cleaner]: https://github.com/gemini-testing/gh-actions-reports-ttl-cleaner

0 commit comments

Comments
 (0)