Skip to content

Commit a83cad7

Browse files
miguelangaranocurrentsmiguelangaranocurrents
authored
Merge pull request #105 from currents-dev/cursor/readme-currents-action-docs-ecd5
[CSR-4288] Document Playwright Last Failed action in README
2 parents 4062444 + f13893e commit a83cad7

1 file changed

Lines changed: 145 additions & 226 deletions

File tree

‎README.md‎

Lines changed: 145 additions & 226 deletions
Original file line numberDiff line numberDiff line change
@@ -1,235 +1,154 @@
1-
# Create a GitHub Action Using TypeScript
2-
3-
[![GitHub Super-Linter](https://github.com/actions/typescript-action/actions/workflows/linter.yml/badge.svg)](https://github.com/super-linter/super-linter)
4-
![CI](https://github.com/actions/typescript-action/actions/workflows/ci.yml/badge.svg)
5-
[![Check dist/](https://github.com/actions/typescript-action/actions/workflows/check-dist.yml/badge.svg)](https://github.com/actions/typescript-action/actions/workflows/check-dist.yml)
6-
[![CodeQL](https://github.com/actions/typescript-action/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/actions/typescript-action/actions/workflows/codeql-analysis.yml)
7-
[![Coverage](./badges/coverage.svg)](./badges/coverage.svg)
8-
9-
Use this template to bootstrap the creation of a TypeScript action. :rocket:
10-
11-
This template includes compilation support, tests, a validation workflow,
12-
publishing, and versioning guidance.
13-
14-
If you are new, there's also a simpler introduction in the
15-
[Hello world JavaScript action repository](https://github.com/actions/hello-world-javascript-action).
16-
17-
## Create Your Own Action
18-
19-
To create your own action, you can use this repository as a template! Just
20-
follow the below instructions:
21-
22-
1. Click the **Use this template** button at the top of the repository
23-
1. Select **Create a new repository**
24-
1. Select an owner and name for your new repository
25-
1. Click **Create repository**
26-
1. Clone your new repository
27-
28-
> [!IMPORTANT]
29-
>
30-
> Make sure to remove or update the [`CODEOWNERS`](./CODEOWNERS) file! For
31-
> details on how to use this file, see
32-
> [About code owners](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners).
33-
34-
## Initial Setup
35-
36-
After you've cloned the repository to your local machine or codespace, you'll
37-
need to perform some initial setup steps before you can develop your action.
38-
39-
> [!NOTE]
40-
>
41-
> You'll need to have a reasonably modern version of
42-
> [Node.js](https://nodejs.org) handy (20.x or later should work!). If you are
43-
> using a version manager like [`nodenv`](https://github.com/nodenv/nodenv) or
44-
> [`nvm`](https://github.com/nvm-sh/nvm), this template has a `.node-version`
45-
> file at the root of the repository that will be used to automatically switch
46-
> to the correct version when you `cd` into the repository. Additionally, this
47-
> `.node-version` file is used by GitHub Actions in any `actions/setup-node`
48-
> actions.
49-
50-
1. :hammer_and_wrench: Install the dependencies
51-
52-
```bash
53-
npm install
54-
```
55-
56-
1. :building_construction: Package the TypeScript for distribution
57-
58-
```bash
59-
npm run bundle
60-
```
61-
62-
1. :white_check_mark: Run the tests
63-
64-
```bash
65-
$ npm test
66-
67-
PASS ./index.test.js
68-
✓ throws invalid number (3ms)
69-
✓ wait 500 ms (504ms)
70-
✓ test runs (95ms)
71-
72-
...
73-
```
74-
75-
## Update the Action Metadata
76-
77-
The [`action.yml`](action.yml) file defines metadata about your action, such as
78-
input(s) and output(s). For details about this file, see
79-
[Metadata syntax for GitHub Actions](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions).
80-
81-
When you copy this repository, update `action.yml` with the name, description,
82-
inputs, and outputs for your action.
83-
84-
## Update the Action Code
85-
86-
The [`src/`](./src/) directory is the heart of your action! This contains the
87-
source code that will be run when your action is invoked. You can replace the
88-
contents of this directory with your own code.
89-
90-
There are a few things to keep in mind when writing your action code:
91-
92-
- Most GitHub Actions toolkit and CI/CD operations are processed asynchronously.
93-
In `main.ts`, you will see that the action is run in an `async` function.
94-
95-
```javascript
96-
import * as core from '@actions/core'
97-
//...
98-
99-
async function run() {
100-
try {
101-
//...
102-
} catch (error) {
103-
core.setFailed(error.message)
104-
}
105-
}
106-
```
107-
108-
For more information about the GitHub Actions toolkit, see the
109-
[documentation](https://github.com/actions/toolkit/blob/master/README.md).
110-
111-
So, what are you waiting for? Go ahead and start customizing your action!
112-
113-
1. Create a new branch
114-
115-
```bash
116-
git checkout -b releases/v1
117-
```
118-
119-
1. Replace the contents of `src/` with your action code
120-
1. Add tests to `__tests__/` for your source code
121-
1. Format, test, and build the action
122-
123-
```bash
124-
npm run all
125-
```
126-
127-
> This step is important! It will run [`ncc`](https://github.com/vercel/ncc)
128-
> to build the final JavaScript action code with all dependencies included.
129-
> If you do not run this step, your action will not work correctly when it is
130-
> used in a workflow. This step also includes the `--license` option for
131-
> `ncc`, which will create a license file for all of the production node
132-
> modules used in your project.
133-
134-
1. Commit your changes
135-
136-
```bash
137-
git add .
138-
git commit -m "My first action is ready!"
139-
```
140-
141-
1. Push them to your repository
142-
143-
```bash
144-
git push -u origin releases/v1
145-
```
146-
147-
1. Create a pull request and get feedback on your action
148-
1. Merge the pull request into the `main` branch
149-
150-
Your action is now published! :rocket:
151-
152-
For information about versioning your action, see
153-
[Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md)
154-
in the GitHub Actions toolkit.
155-
156-
## Validate the Action
157-
158-
You can now validate the action by referencing it in a workflow file. For
159-
example, [`ci.yml`](./.github/workflows/ci.yml) demonstrates how to reference an
160-
action in the same repository.
1+
# Playwright Last Failed (GitHub Action)
2+
3+
This action supports **re-running only the Playwright tests that failed** when
4+
GitHub Actions runs “re-run failed jobs” (or similar retries). It works together
5+
with [Currents](https://currents.dev) and the
6+
[`@currents/cmd`](https://www.npmjs.com/package/@currents/cmd) CLI.
7+
8+
**Full setup, sharding, orchestration, and CI build ID details:** [Re-run only
9+
failed tests (GitHub Actions)][gha-rerun] on [docs.currents.dev][docs]. For
10+
background on why re-runs need extra configuration, see the guide [Re-run only
11+
failed tests][guide-rerun].
12+
13+
## Purpose
14+
15+
- Before the Playwright test step: restores **last run** metadata (via Currents
16+
cache or the Currents API) and exposes **extra Playwright CLI flags** as a
17+
step output.
18+
- After the job (cache mode only): saves updated **last run** metadata so the
19+
next retry can target failures again.
20+
21+
The step output is passed into the Playwright command—for example
22+
`npx playwright test … ${{ steps.<id>.outputs.extra-pw-flags }}`—so only failed
23+
tests run on retry.
24+
25+
## How it works
26+
27+
The action runs on **Node 24** and installs `@currents/cmd` globally
28+
(`npm install -g @currents/cmd`). It then behaves in one of two ways:
29+
30+
### 1. Cache mode (default)
31+
32+
Suited to workflows that report runs to Currents with a **record key** (typical
33+
Playwright reporter + sharding flow).
34+
35+
1. **Main step:** runs `npx currents cache get` with the `last-run` preset. On
36+
success, it reads a generated preset file and sets the output
37+
`extra-pw-flags`.
38+
1. **Post step:** runs `npx currents cache set` with the same preset so the next
39+
workflow attempt can read an updated snapshot.
40+
41+
Authentication and targeting use the **Currents record key** (input `key` or
42+
`CURRENTS_RECORD_KEY`). Optional `id`, `path`, matrix inputs, and
43+
`pw-output-dir` tune what is cached.
44+
45+
### 2. API / orchestration mode (`use-api` or `or8n`)
46+
47+
Suited to workflows that rely on **Currents Orchestration** (or otherwise need
48+
the CLI to resolve failures via the API). In this mode the **post-cache step is
49+
skipped**.
50+
51+
On **re-run attempts** (`GITHUB_RUN_ATTEMPT` > 1), the main step runs
52+
`npx currents api get-run` to fetch the previous run and, when successful, sets
53+
`extra-pw-flags` to `--last-failed`. The workflow should define
54+
**`CURRENTS_API_KEY`**, **`CURRENTS_PROJECT_ID`** (and related environment
55+
variables as in the docs), and set **`or8n: true`** (or `use-api: true`) as
56+
shown in the [orchestration section][or8n-section] of the documentation.
57+
58+
## Outputs
59+
60+
| Name | Description |
61+
| ---------------- | ----------------------------------------------- |
62+
| `extra-pw-flags` | Flags to append to the Playwright test command. |
63+
64+
If restoration fails, the output may be empty; the workflow can still run tests
65+
normally.
66+
67+
## Inputs (options)
68+
69+
- **`key`** (optional, default `''`). Currents **record key**, or set
70+
`CURRENTS_RECORD_KEY`. Used in cache mode.
71+
- **`debug`** (optional, default `false`). Enables debug logging for CLI
72+
commands.
73+
- **`id`** (optional, default `''`). Cache ID namespace for `cache get` /
74+
`cache set`.
75+
- **`path`** (optional, default `''`). Comma-separated paths to include when
76+
writing cache (post step).
77+
- **`output-dir`** (optional, default `''`). Directory for preset output during
78+
`cache get`.
79+
- **`pw-output-dir`** (optional, default `test-results`). Playwright output
80+
directory; used for API mode `.last-run.json` path and for `--pw-output-dir`
81+
on cache set.
82+
- **`matrix-index`** (optional, default `1`). Shard index for parallel runs
83+
(`cache get` / `cache set`).
84+
- **`matrix-total`** (optional, default `1`). Total shards.
85+
- **`use-api`** (optional, default `false`). API-based last-failed resolution
86+
(same code path as `or8n`).
87+
- **`or8n`** (optional, default `false`). Orchestration-oriented behavior (API
88+
path; no post-cache step).
89+
- **`api-key`** (optional, default `''`). API key, or set `CURRENTS_API_KEY` in
90+
the environment.
91+
- **`project-id`** (optional, default `''`). Currents project ID, or set
92+
`CURRENTS_PROJECT_ID`.
93+
- **`previous-ci-build-id`** (optional, default `''`). Override for the previous
94+
CI build ID when resolving the prior run (see [custom CI build
95+
ID][custom-ci-build-id]).
96+
97+
\*In cache mode a record key (input or environment) is required for meaningful
98+
cache reads/writes.
99+
100+
## Setup
101+
102+
1. **Add `@currents/cmd` to the repository** as a dev dependency and install
103+
with a **frozen lockfile** in CI (`npm ci`, etc.). The action installs a
104+
global CLI for convenience; pinning `@currents/cmd` in the repository keeps
105+
CI reproducible. See the note in the [official docs][gha-rerun].
106+
1. **Configure Currents** (record key, and for API mode, API key and project ID)
107+
using secrets and `env` as described in the documentation.
108+
1. **Add this action before the Playwright step** and pass `extra-pw-flags` into
109+
the test command.
110+
1. **Sharding:** set `matrix-index` and `matrix-total` from the job matrix (for
111+
example `${{ matrix.shard }}` and `${{ strategy.job-total }}`).
112+
113+
### Minimal example (cache mode, sharded)
161114

162115
```yaml
163-
steps:
164-
- name: Checkout
165-
id: checkout
166-
uses: actions/checkout@v4
167-
168-
- name: Test Local Action
169-
id: test-action
170-
uses: ./
171-
with:
172-
milliseconds: 1000
173-
174-
- name: Print Output
175-
id: output
176-
run: echo "${{ steps.test-action.outputs.time }}"
116+
- name: Playwright Last Failed
117+
id: last-failed
118+
uses: currents-dev/playwright-last-failed@v1
119+
env:
120+
CURRENTS_RECORD_KEY: ${{ secrets.CURRENTS_RECORD_KEY }}
121+
with:
122+
pw-output-dir: test-results
123+
matrix-index: ${{ matrix.shard }}
124+
matrix-total: ${{ strategy.job-total }}
125+
126+
- name: Run Playwright
127+
run: npx playwright test ${{ steps.last-failed.outputs.extra-pw-flags }}
177128
```
178129
179-
For example workflow runs, check out the
180-
[Actions tab](https://github.com/actions/typescript-action/actions)! :rocket:
130+
For orchestration (`or8n: true`), environment variables, custom
131+
`CURRENTS_CI_BUILD_ID`, and copypaste workflows, see **[Re-run only failed tests
132+
(GitHub Actions)][gha-rerun]**.
181133

182-
## Usage
134+
## Action metadata
183135

184-
After testing, you can create version tag(s) that developers can use to
185-
reference different stable versions of your action. For more information, see
186-
[Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md)
187-
in the GitHub Actions toolkit.
136+
Input/output definitions are in [`action.yml`](./action.yml).
188137

189-
To include the action in a workflow in another repository, you can use the
190-
`uses` syntax with the `@` symbol to reference a specific branch, tag, or commit
191-
hash.
138+
## Developing this repository
192139

193-
```yaml
194-
steps:
195-
- name: Checkout
196-
id: checkout
197-
uses: actions/checkout@v4
198-
199-
- name: Test Local Action
200-
id: test-action
201-
uses: actions/typescript-action@v1 # Commit with the `v1` tag
202-
with:
203-
milliseconds: 1000
204-
205-
- name: Print Output
206-
id: output
207-
run: echo "${{ steps.test-action.outputs.time }}"
208-
```
140+
This action is implemented in TypeScript (`src/index.ts`, `src/post.ts`). After
141+
changing sources, run `npm run all` to format, lint, test, and rebuild `dist/`
142+
before committing.
143+
144+
<!-- prettier-ignore-start -->
145+
<!-- markdownlint-disable MD013 -->
146+
147+
[docs]: https://docs.currents.dev
148+
[gha-rerun]: https://docs.currents.dev/getting-started/ci-setup/github-actions/re-run-failed-only-tests
149+
[guide-rerun]: https://docs.currents.dev/guides/ci-optimization/re-run-only-failed-tests
150+
[or8n-section]: https://docs.currents.dev/getting-started/ci-setup/github-actions/re-run-failed-only-tests#currents-orchestration
151+
[custom-ci-build-id]: https://docs.currents.dev/getting-started/ci-setup/github-actions/re-run-failed-only-tests#custom-ci-build-id-for-reruns
209152

210-
## Publishing a New Release
211-
212-
This project includes a helper script, [`script/release`](./script/release)
213-
designed to streamline the process of tagging and pushing new releases for
214-
GitHub Actions.
215-
216-
GitHub Actions allows users to select a specific version of the action to use,
217-
based on release tags. This script simplifies this process by performing the
218-
following steps:
219-
220-
1. **Retrieving the latest release tag:** The script starts by fetching the most
221-
recent SemVer release tag of the current branch, by looking at the local data
222-
available in your repository.
223-
1. **Prompting for a new release tag:** The user is then prompted to enter a new
224-
release tag. To assist with this, the script displays the tag retrieved in
225-
the previous step, and validates the format of the inputted tag (vX.X.X). The
226-
user is also reminded to update the version field in package.json.
227-
1. **Tagging the new release:** The script then tags a new release and syncs the
228-
separate major tag (e.g. v1, v2) with the new release tag (e.g. v1.0.0,
229-
v2.1.2). When the user is creating a new major release, the script
230-
auto-detects this and creates a `releases/v#` branch for the previous major
231-
version.
232-
1. **Pushing changes to remote:** Finally, the script pushes the necessary
233-
commits, tags and branches to the remote repository. From here, you will need
234-
to create a new release in GitHub so users can easily reference the new tags
235-
in their workflows .
153+
<!-- markdownlint-enable MD013 -->
154+
<!-- prettier-ignore-end -->

0 commit comments

Comments
 (0)