Skip to content

Commit 96e8634

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

File tree

5 files changed

+581
-0
lines changed

5 files changed

+581
-0
lines changed

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

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

0 commit comments

Comments
 (0)