From 3d060c0b6f1ad7a773a9dc23f8db592764316108 Mon Sep 17 00:00:00 2001 From: Mike McCready <66998419+MikeMcC399@users.noreply.github.com> Date: Tue, 29 Apr 2025 16:45:49 +0200 Subject: [PATCH 1/2] test: rework custom test command and example --- .github/workflows/example-custom-command.yml | 13 +++++---- README.md | 30 ++++++++++++-------- 2 files changed, 26 insertions(+), 17 deletions(-) diff --git a/.github/workflows/example-custom-command.yml b/.github/workflows/example-custom-command.yml index 814a3bc46..a5cb6206e 100644 --- a/.github/workflows/example-custom-command.yml +++ b/.github/workflows/example-custom-command.yml @@ -1,4 +1,9 @@ name: example-custom-command +# example using the command parameter +# this allows any cli command to be run +# the command parameter causes other action parameters that would be passed to Cypress +# to be ignored and so it should not be used with these other parameters +# for example, browsers, config, record, parallel, spec, etc would be ignored on: push: branches: @@ -8,18 +13,16 @@ on: jobs: start: - # example where instead of forming the default "cypress run ..." - # the user can specify their own command runs-on: ubuntu-24.04 steps: - - name: Checkout ๐Ÿ›Ž + - name: Checkout uses: actions/checkout@v4 - - name: Custom tests ๐Ÿงช + - name: Custom tests uses: ./ with: command: npm run custom-test working-directory: examples/custom-command - - name: Show saved file ๐Ÿ–จ + - name: Show saved file run: cat examples/custom-command/results.json diff --git a/README.md b/README.md index be114a7ea..6088b057b 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ The following examples demonstrate the actions' functions. - [Wait for server](#wait-on) to respond before running the tests - Use [custom install command](#custom-install-command) - Use [command prefix](#command-prefix) -- Use [own custom test command](#custom-test-command) +- Use [custom test command](#custom-test-command) - Pass [custom build id](#custom-build-id) when recording to Cypress Cloud - Generate a [robust custom build id](#robust-custom-build-id) to allow re-running the workflow - Use different [working-directory](#working-directory) @@ -955,22 +955,28 @@ jobs: ### Custom test command -You can overwrite the Cypress run command with your own command. +The `command` parameter executes a CLI command using the GitHub [@actions/exec](https://github.com/actions/toolkit/tree/main/packages/exec) action. + +This parameter is useful for special test cases, for example: + +- in the project [examples/custom-command](./examples/custom-command/), a JavaScript [examples/custom-command/index.js](./examples/custom-command/index.js) is run with `node .` through `command: npm run custom-test` +- in the workflow [example-yarn-modern-pnp.yml](.github/workflows/example-yarn-modern-pnp.yml) Yarn Modern with Plug'n'Play is run with `command: yarn run --binaries-only cypress run` since [Yarn Plug'n'Play](#yarn-plugnplay) is not natively supported by the action. + +If you don't have a special case and you just need to convert a `cypress run` CLI command to use the Cypress GitHub Action, refer to the section [Migrating from CLI command](#migrating-from-cli-command) which explains how to map CLI options to equivalent action parameters, avoiding the need for the `command` parameter in most cases. + +There are some parameters that cannot be used together with the `command` parameter, and these are ignored. The parameters include action input parameters listed in the table [CLI Run Option / Action Parameter](#cli-run-option--action-parameter), the [publish-summary](#suppress-job-summary), [summary-title](#job-summary-title) and [command-prefix](#command-prefix). If any such parameters are passed to the action, a warning message appears in the logs that the parameters have been ignored. + +Correct Example: ```yml steps: - - name: Checkout ๐Ÿ›Ž - uses: actions/checkout@v4 - - - name: Custom tests ๐Ÿงช - uses: cypress-io/github-action@v6 + - uses: actions/checkout@v4 + - uses: cypress-io/github-action@v6 with: - command: npm run e2e:ci + command: npm run custom-test ``` -**Caution**: using the action parameter `command` causes multiple other parameters to be ignored including: `auto-cancel-after-failures`, `browser`, `ci-build-id`, `command-prefix`, `component`, `config`, `config-file`, `env`, `group`, `headed`, `parallel`, `project`, `publish-summary`, `quiet`, `record`, `spec` and `tag`. - -See [example-custom-command.yml](.github/workflows/example-custom-command.yml) file. +[![command example](https://github.com/cypress-io/github-action/actions/workflows/example-custom-command.yml/badge.svg)](.github/workflows/example-custom-command.yml) ### Custom build id @@ -1598,7 +1604,7 @@ If you configure a `workflow_dispatch` event in your own workflows, you will be ### Outputs -This action sets a GitHub step output `resultsUrl` if the run was recorded on [Cypress Cloud](https://on.cypress.io/cloud-introduction) using the action parameter setting `record: true` (see [Record test results on Cypress Cloud](#record-test-results-on-cypress-cloud)). Note that if a custom test command with the [command](#custom-test-command) option or the [command-prefix](#command-prefix) option are used then no `resultsUrl` step output is saved. +This action sets a GitHub step output `resultsUrl` if the run was recorded on [Cypress Cloud](https://on.cypress.io/cloud-introduction) using the action parameter setting `record: true` (see [Record test results on Cypress Cloud](#record-test-results-on-cypress-cloud)). Note that if a custom test command with the [command](#custom-test-command) parameter or the [command-prefix](#command-prefix) parameter are used then no `resultsUrl` step output is saved. This is an example of using the step output `resultsUrl`: From 3c7b90fe4d871d7814bbab7bf57d4e6bd3fd0397 Mon Sep 17 00:00:00 2001 From: Mike McCready <66998419+MikeMcC399@users.noreply.github.com> Date: Fri, 2 May 2025 09:02:41 +0200 Subject: [PATCH 2/2] change heading for example snippet --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d8da1563f..eb2ef9c4d 100644 --- a/README.md +++ b/README.md @@ -976,7 +976,7 @@ If you don't have a special case and you just need to convert a `cypress run` CL There are some parameters that cannot be used together with the `command` parameter, and these are ignored. The parameters include action input parameters listed in the table [CLI Run Option / Action Parameter](#cli-run-option--action-parameter), the [publish-summary](#suppress-job-summary), [summary-title](#job-summary-title) and [command-prefix](#command-prefix). If any such parameters are passed to the action, a warning message appears in the logs that the parameters have been ignored. -Correct Example: +Correct example snippet: ```yml steps: