diff --git a/.github/workflows/check-markdown.yml b/.github/workflows/check-markdown.yml index 42ae19e08..b643abc9d 100644 --- a/.github/workflows/check-markdown.yml +++ b/.github/workflows/check-markdown.yml @@ -7,11 +7,15 @@ on: workflow_dispatch: jobs: - check-markdown-links: + check-markdown: runs-on: ubuntu-24.04 - name: Check links in Markdown files + name: Check Markdown files steps: - name: Checkout uses: actions/checkout@v4 - - run: npm ci - - run: npm run check:markdown + - name: Install dependencies + run: npm ci + - name: Check Markdown links + run: npm run check:markdown + - name: Check Markdown formatting + run: npm run format:markdown:check diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 000000000..2c22bd9bc --- /dev/null +++ b/.prettierignore @@ -0,0 +1 @@ +/LICENSE.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 21340ae76..ed4991167 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -30,4 +30,4 @@ See [Releases](https://github.com/cypress-io/github-action/releases) for full de | v4.0.0 | Support for Cypress 10 and later versions added. | | v3 | Action runs under Node.js 16 instead of Node.js 12. | | v2 | Cypress runs using the [Module API](https://docs.cypress.io/guides/guides/module-api) instead of being started via the command line. | -| v1 | *This version is no longer runnable in GitHub due to security changes.* | +| v1 | _This version is no longer runnable in GitHub due to security changes._ | diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e801f92d8..ab1cbb464 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ Thanks for taking the time to contribute! :smile: -*To contribute to the main Cypress product, please read the related [CONTRIBUTING](https://github.com/cypress-io/cypress/blob/develop/CONTRIBUTING.md) document, which also contains useful general tips.* +_To contribute to the main Cypress product, please read the related [CONTRIBUTING](https://github.com/cypress-io/cypress/blob/develop/CONTRIBUTING.md) document, which also contains useful general tips._ To contribute to the [cypress-io/github-action](https://github.com/cypress-io/github-action) repository, please continue reading here. @@ -17,7 +17,6 @@ This document describes topics useful to contributors to this repository. The re 1. GitHub's Marketplace as [cypress-io/github-action](https://github.com/marketplace/actions/cypress-io#cypress-iogithub-action--) 2. npm's JavaScript Package Registry as [@cypress/github-action](https://www.npmjs.com/package/@cypress/github-action) - You can read the GitHub document [Creating a JavaScript action](https://docs.github.com/en/actions/creating-actions/creating-a-javascript-action) for background information on how JavaScript actions for GitHub are created and how they work. ### Requirements @@ -31,6 +30,7 @@ You must have the following installed on your system to contribute locally: If you are submitting a Pull Request (PR) to provide a fix or feature for the action, the following is relevant to you: The main source code elements for the action are: + - [action.yml](action.yml) - [index.js](index.js) - [src/ping.js](src/ping.js) @@ -45,11 +45,17 @@ To contribute changes, follow these instructions in the order given below: 1. Make the necessary source code changes, including additions or changes to the [README.md](./README.md) documentation if parameters are added or affected. 1. Execute the following in the root directory of the cloned repository - ```bash - npm install - npm run format - npm run build - ``` + ```bash + npm install + npm run format + npm run build + ``` + +1. If you have modified any Markdown documents (`*.md`) then execute + + ```bash + npm run format:markdown + ``` 1. Commit the change. (If you are working on Microsoft Windows, see [Windows users](#windows-users) below.) 1. Push to the repository. @@ -97,18 +103,18 @@ This information is for Cypress.io Members or Collaborators who merge pull reque 1. When merging a pull request, use the [Squash and merge](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/about-merge-methods-on-github#squashing-your-merge-commits) option to squash all commits into one. 1. Make sure the commit subject and body follow [semantic commit convention](https://semantic-release.gitbook.io/semantic-release/#commit-message-format), for instance: - ```text - feat: added new parameter - fix: fixed a bug - ``` + ```text + feat: added new parameter + fix: fixed a bug + ``` - If you need to bump the major version, mark it as breaking change in the body of the commit's message like: + If you need to bump the major version, mark it as breaking change in the body of the commit's message like: - ```text - fix: upgrade dependency X + ```text + fix: upgrade dependency X - BREAKING CHANGE: requires minimum Node.js 18 to run - ``` + BREAKING CHANGE: requires minimum Node.js 18 to run + ``` 1. New versions of this action will be released automatically by the CI when merged to the `master` branch, see [.github/workflows/main.yml](.github/workflows/main.yml). This will create a new [GitHub release](https://github.com/cypress-io/github-action/releases) and will update the current highest branch from the series `v5`, `v6`, ... etc. Thus specifying `uses: cypress-io/github-action@v6` (or higher version if available) selects the new version automatically. This **will not** push the latest release to GitHub Marketplace. 1. The action's CI is configured to use the [default Angular release rules](https://github.com/semantic-release/commit-analyzer/blob/master/lib/default-release-rules.js). This means that only `feat:`, `fix:` and `perf:` trigger a new release which is then logged to the [releases](https://github.com/cypress-io/github-action/releases) page. Other Angular commit types listed on [Contributing to Angular](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#-commit-message-format) can be used for documentation purposes, however they are ignored by the currently configured release process. diff --git a/README.md b/README.md index 0fd506756..8d96de78e 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ # cypress-io/github-action [![Action status][ci-badge]][ci-workflow] [![cypress][cloud-badge]][cloud-project] [![renovate-app badge][renovate-badge]][renovate-bot] - > [GitHub Action](https://docs.github.com/en/actions) for running [Cypress](https://www.cypress.io) end-to-end and component tests. Includes npm, pnpm and Yarn installation, custom caching and lots of configuration options. +> [GitHub Action](https://docs.github.com/en/actions) for running [Cypress](https://www.cypress.io) end-to-end and component tests. Includes npm, pnpm and Yarn installation, custom caching and lots of configuration options. - Placing `use: cypress-io/github-action@v6` into a GitHub Action workflow gives you a simple way to run Cypress. The action takes the project's npm, pnpm or Yarn package manager lock file, installs dependencies and caches these dependencies for future use. It then proceeds to run Cypress end-to-end tests with the built-in Electron browser and provides a test summary after completion. +Placing `use: cypress-io/github-action@v6` into a GitHub Action workflow gives you a simple way to run Cypress. The action takes the project's npm, pnpm or Yarn package manager lock file, installs dependencies and caches these dependencies for future use. It then proceeds to run Cypress end-to-end tests with the built-in Electron browser and provides a test summary after completion. - If you are testing against a running server like the [Cypress Kitchen Sink showcase example](https://example.cypress.io/) on https://example.cypress.io/ no other parameters are necessary. In other cases where you need to fire up a development server, you can add the [start](#start-server) parameter to the workflow. Browse through the examples to find other useful parameters. +If you are testing against a running server like the [Cypress Kitchen Sink showcase example](https://example.cypress.io/) on https://example.cypress.io/ no other parameters are necessary. In other cases where you need to fire up a development server, you can add the [start](#start-server) parameter to the workflow. Browse through the examples to find other useful parameters. ## Examples @@ -452,9 +452,11 @@ Please refer to the [default GitHub environment variables](https://docs.github.c When recording runs to Cypress Cloud, the PR number and URL can be automatically detected if you pass `GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}` via the workflow `env`. When set, this value enables the Action to perform additional logic that grabs the related PR number and URL (if they exist) and sets them in the environment variables `CYPRESS_PULL_REQUEST_ID` and `CYPRESS_PULL_REQUEST_URL`, respectively. -* See Cypress' documentation on [CI Build Information](https://on.cypress.io/guides/continuous-integration/introduction#CI-Build-Information) + +- See Cypress' documentation on [CI Build Information](https://on.cypress.io/guides/continuous-integration/introduction#CI-Build-Information) Example workflow using the variables: + ```yml name: Example echo PR number and URL on: push @@ -571,7 +573,6 @@ jobs: runs-on: ubuntu-24.04 name: E2E steps: - - name: Checkout uses: actions/checkout@v4 @@ -736,6 +737,7 @@ The Cypress GH Action does not spawn or create any additional containers - it on If you use the GitHub Actions facility for [Re-running workflows and jobs](https://docs.github.com/en/actions/managing-workflow-runs/re-running-workflows-and-jobs), note that [Re-running failed jobs in a workflow](https://docs.github.com/en/actions/managing-workflow-runs/re-running-workflows-and-jobs?tool=webui#re-running-failed-jobs-in-a-workflow) is not suited for use with parallel recording into Cypress Cloud. Re-running failed jobs in this situation does not simply re-run failed Cypress tests. Instead it re-runs **all** Cypress tests, load-balanced over the containers with failed jobs. To optimize runs when there are failing tests present, refer to optional [Cypress Cloud Smart Orchestration](https://docs.cypress.io/cloud/features/smart-orchestration/overview/) Premium features: + - [Spec Prioritization](https://docs.cypress.io/cloud/features/smart-orchestration/spec-prioritization) - [Auto Cancellation](https://docs.cypress.io/guides/cloud/smart-orchestration/run-cancellation). See also [Specify auto cancel after failures](#specify-auto-cancel-after-failures) for details of how to set this option in a Cypress GH Action workflow. @@ -796,6 +798,7 @@ jobs: with: start: npm start ``` + **Caution:** use the `start` parameter only to start a server, not to run Cypress, otherwise tests may be run twice. The action runs Cypress tests by default, unless the parameter `runTests` is set to `false`. **Note:** sometimes on Windows you need to run a different start command. You can use the `start-windows` parameter for this. @@ -888,8 +891,6 @@ By default, `wait-on` will retry for 60 seconds. You can pass a custom timeout i wait-on-timeout: 120 ``` - - You can wait for multiple URLs to respond by separating urls with a comma ```yml @@ -1064,7 +1065,7 @@ repo/ package-lock.json ``` - We use `working-directory: app-test` to match the above example directory structure: +We use `working-directory: app-test` to match the above example directory structure: ```yml on: push @@ -1429,11 +1430,11 @@ jobs: This action installs local dependencies using lock files. Ensure that exactly one type of lock file is used for each project or working-directory from the following supported package managers: - | Lock file | Package Manager | Installation command | - | ------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------- | - | `package-lock.json` | [npm](https://docs.npmjs.com/cli/v9/commands/npm-ci) | `npm ci` | - | `pnpm-lock.yaml` | [pnpm](https://pnpm.io/cli/install#--frozen-lockfile) | `pnpm install --frozen-lockfile` | - | `yarn.lock` | [Yarn Classic](https://classic.yarnpkg.com/en/docs/cli/install#toc-yarn-install-frozen-lockfile) | `yarn --frozen-lockfile` | +| Lock file | Package Manager | Installation command | +| ------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------- | +| `package-lock.json` | [npm](https://docs.npmjs.com/cli/v9/commands/npm-ci) | `npm ci` | +| `pnpm-lock.yaml` | [pnpm](https://pnpm.io/cli/install#--frozen-lockfile) | `pnpm install --frozen-lockfile` | +| `yarn.lock` | [Yarn Classic](https://classic.yarnpkg.com/en/docs/cli/install#toc-yarn-install-frozen-lockfile) | `yarn --frozen-lockfile` | See section [Yarn Modern](#yarn-modern) for information about using Yarn version 2 and later. @@ -1697,6 +1698,7 @@ Please see our [Contributing Guideline](./CONTRIBUTING.md) which explains how to This project is licensed under the terms of the [MIT license][license-file]. + [ci-badge]: https://github.com/cypress-io/github-action/actions/workflows/main.yml/badge.svg [ci-workflow]: https://github.com/cypress-io/github-action/actions/workflows/main.yml [cloud-badge]: https://img.shields.io/endpoint?url=https://cloud.cypress.io/badge/simple/3tb7jn/master&style=flat&logo=cypress diff --git a/docs/MAINTENANCE.md b/docs/MAINTENANCE.md index 3943a17d4..8b7e9b433 100644 --- a/docs/MAINTENANCE.md +++ b/docs/MAINTENANCE.md @@ -8,7 +8,7 @@ The [examples](../examples) directory contains examples of the use of Cypress (C The examples make use of [npm](https://www.npmjs.com/), [pnpm](https://pnpm.io/), [Yarn 1 (Classic)](https://classic.yarnpkg.com/) and [Yarn Modern](https://yarnpkg.com/) to define and install the packages being used. For [Yarn Modern](https://yarnpkg.com/) the recommended [Corepack](https://yarnpkg.com/corepack) is used as a Yarn version manager. -*The previous [examples/v9](https://github.com/cypress-io/github-action/tree/v5/examples/v9) are archived in the [v5](https://github.com/cypress-io/github-action/tree/v5/) branch. This directory contains examples which were set up to use Cypress `9.7.0`, the last version using Legacy Configuration, covering Cypress 9 and below. These `v9` examples are no longer maintained. +_The previous [examples/v9](https://github.com/cypress-io/github-action/tree/v5/examples/v9) are archived in the [v5](https://github.com/cypress-io/github-action/tree/v5/) branch. This directory contains examples which were set up to use Cypress `9.7.0`, the last version using Legacy Configuration, covering Cypress 9 and below. These `v9` examples are no longer maintained._ ## Requirements diff --git a/examples/component-tests/README.md b/examples/component-tests/README.md index 83ed859cb..093d3db86 100644 --- a/examples/component-tests/README.md +++ b/examples/component-tests/README.md @@ -3,16 +3,18 @@ This example was built as follows: 1. [Vite > Getting Started](https://vitejs.dev/guide/) instructions with the [react](https://vite.new/react) template were used to create the app - ```bash - npm create vite@latest component-tests -- --template react - ``` - The linting `npm` modules and linting script have been removed, since this is out-of-scope for the example. + ```bash + npm create vite@latest component-tests -- --template react + ``` + The linting `npm` modules and linting script have been removed, since this is out-of-scope for the example. 1. The Cypress documentation instructions from [Component Testing > Getting Started](https://on.cypress.io/guides/component-testing/getting-started) were followed to set up component testing, including copying - - `` component: [react/my-awesome-app/src/components/Stepper.jsx](https://github.com/cypress-io/component-testing-quickstart-apps/blob/main/react/my-awesome-app/src/components/Stepper.jsx) + - `` component: [react/my-awesome-app/src/components/Stepper.jsx](https://github.com/cypress-io/component-testing-quickstart-apps/blob/main/react/my-awesome-app/src/components/Stepper.jsx) + + from the [Cypress Component Testing Quickstart Apps](https://github.com/cypress-io/component-testing-quickstart-apps) repo to this repo's `examples/component-tests/src/components/` sub-directory. - from the [Cypress Component Testing Quickstart Apps](https://github.com/cypress-io/component-testing-quickstart-apps) repo to this repo's `examples/component-tests/src/components/` sub-directory. 1. The script `"test": "cypress run --component"` was added to `package.json`. + ## Execution Execute the following to change to this directory: diff --git a/examples/install-only/README.md b/examples/install-only/README.md index cf9b2e9cd..09d11fe50 100644 --- a/examples/install-only/README.md +++ b/examples/install-only/README.md @@ -1,4 +1,5 @@ # example: install-only + > Do not install _every_ dependency, just Cypress before running tests This example has production and development dependencies, but only installs Cypress to test already deployed URL. diff --git a/examples/recording/README.md b/examples/recording/README.md index 59caff718..702e6f31a 100644 --- a/examples/recording/README.md +++ b/examples/recording/README.md @@ -18,6 +18,7 @@ Access "Project settings" in Cypress Cloud and copy the contents of each of the | Record Keys | EXAMPLE_RECORDING_KEY | Actions secrets | Refer to the GitHub documentation + - [Creating encrypted secrets for a repository](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository). When you have done this, the example recording will take the `projectId` from the `EXAMPLE_PROJECT_ID` variable instead of from the [cypress.config.js](cypress.config.js) configuration file. diff --git a/package.json b/package.json index 8d721eab9..f375eca4e 100644 --- a/package.json +++ b/package.json @@ -13,6 +13,8 @@ "test": "echo \"There are no tests :(\"", "build": "ncc build -o dist index.js", "format": "prettier --write index.js src/ping.js action.yml", + "format:markdown": "prettier --write \"**/*.md\"", + "format:markdown:check": "prettier --check \"**/*.md\"", "lint": "eslint", "check:markdown": "find *.md docs/*.md -print0 | xargs -0 -n1 markdown-link-check", "update:cypress": "./scripts/update-cypress-latest.sh",