Skip to content

Commit 0e5a562

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

File tree

5 files changed

+635
-0
lines changed

5 files changed

+635
-0
lines changed

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

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

0 commit comments

Comments
 (0)