Merge pull request #20171 from cypress-io/10.0-release-merge-4b50f9ee

chore: 10.0 release merge 4b50f9e and v10 error wiring and content improvements

.gitattributes

@@ -1,3 +1,5 @@
 * text=auto
 
 *.json text eol=lf
+
+packages/errors/__snapshot-html__/** linguist-generated=true

.gitignore

@@ -15,6 +15,8 @@ Cached Theme Material Design.pak
 
 # from data-context, compiled .js files
 packages/data-context/src/**/*.js
+packages/errors/src/**/*.js
+packages/errors/test/**/*.js
 
 # from driver
 packages/driver/cypress/videos
@@ -61,6 +63,7 @@ packages/socket/lib/*.js
 
 # from system-tests
 system-tests/.projects
+system-tests/.http-mitm-proxy
 system-tests/fixtures/large-img
 
 # from npm/react
@@ -76,6 +79,11 @@ system-tests/fixtures/large-img
 # from runner-ct
 /packages/runner-ct/cypress/screenshots
 
+# from errors
+/packages/errors/__snapshot-images__
+/packages/errors/__snapshot-md__
+/packages/errors/__snapshot-html-local__
+
 # graphql, auto-generated
 /packages/launchpad/src/generated
 /packages/app/src/generated

.vscode/settings.json

@@ -36,6 +36,7 @@
   "i18n-ally.keystyle": "nested",
 
   // Volar is the main extension that powers Vue's language features.
-  "volar.autoCompleteRefs": false,
+  // These are commented out because they slow down node development
+  // "volar.autoCompleteRefs": false,
   // "volar.takeOverMode.enabled": true
 }

.vscode/terminals.json

@@ -53,6 +53,13 @@
       "cwd": "[cwd]/packages/app",
       "command": "yarn dev"
     },
+    {
+      "name": "packages/app watch",
+      "focus": true,
+      "onlySingle": true,
+      "cwd": "[cwd]",
+      "command": "yarn watch"
+    },
     {
       "name": "packages/server test-watch",
       "focus": true,

browser-versions.json

@@ -1,4 +1,4 @@
 {
-  "chrome:beta": "98.0.4758.80",
+  "chrome:beta": "99.0.4844.27",
   "chrome:stable": "98.0.4758.80"
 }

circle.yml

@@ -1002,6 +1002,7 @@ jobs:
       - run:
           name: Linting 🧹
           command: |
+            yarn clean
             git clean -df
             yarn lint
       - run:
@@ -1120,12 +1121,14 @@ jobs:
             # run type checking for each individual package
             - run: yarn lerna run types
             - verify-mocha-results:
-                expectedResultCount: 9
+                expectedResultCount: 10
       - store_test_results:
           path: /tmp/cypress
       # CLI tests generate HTML files with sample CLI command output
       - store_artifacts:
           path: cli/test/html
+      - store_artifacts:
+          path: packages/errors/__snapshot-images__
       - store-npm-logs
 
   unit-tests-release:
@@ -1983,14 +1986,6 @@ jobs:
           browser: "electron"
           pull_request_id: 524
 
-  test-binary-against-awesome-typescript-loader:
-    <<: *defaults
-    steps:
-      - test-binary-against-repo:
-          repo: cypress-test-awesome-typescript-loader
-          browser: "electron"
-          pull_request_id: 8
-
   test-binary-against-kitchensink-firefox:
     <<: *defaults
     resource_class: medium
@@ -2334,26 +2329,6 @@ linux-workflow: &linux-workflow
     - test-binary-against-kitchensink:
         requires:
           - create-build-artifacts
-    # when working on a feature or a fix,
-    # you are probably working in a branch
-    # and you want to run a specific PR in the cypress-example-recipes
-    # against this branch. This workflow job includes
-    # the job but only when it runs on specific branch
-    # DO NOT DELETE THIS JOB BEFORE MERGING TO DEVELOP
-    # on "develop" this branch will be ignored anyway
-    # and someone else might use this job definition for another
-    # feature branch and would just update the branch filter
-    # - test-binary-against-recipe-pull-request:
-    #     name: Test cypress run parsing
-    #     filters:
-    #       branches:
-    #         only:
-    #           - cli-to-module-api-7760
-        # requires:
-        #   - create-build-artifacts
-    - test-binary-against-awesome-typescript-loader:
-        requires:
-          - create-build-artifacts
     - test-binary-and-npm-against-other-projects:
         context: test-runner:trigger-test-jobs
         <<: *mainBuildFilters

guides/error-handling.md

@@ -0,0 +1,84 @@
+## Error Handling in Cypress
+
+Clear, consistent, errors are one of the important parts of the Cypress experience. When something goes wrong, there should be clear, actionable feedback for the user about exactly *what* went wrong, *where* it went wrong, and next steps on how to fix.
+
+### @packages/errors
+
+All error related logic for the server should be added to `@packages/errors`. This logic has been separated out from the `@packages/server` to enable strict type checking & use in other packages we have added in the `10.0-release` branch.
+
+Summary of the Errors package:
+
+- `errors.ts`: A key/value mapping of known errors to functions returning "ErrorTemplates", described below, also includes/re-exports several helper utilities:
+  - `get` / `getError`: builds & retrieves the error as a `CypressError`, should be the main way we retrieve errors throughout Cypress. Aliased as `errors.get` for existing use in the server package
+  - `throw` / `throwErr`: Get & throw the error, so we can spy/stub it in a test. Aliased as `errors.throwErr` for existing use in the server package
+  - `logWarning`: Logs the error as a warning to the console, aliased as `errors.log` for existing use in the server package
+- `errTemplate.ts`: Tagged template literal formatting the error as described below
+- `stackUtils.ts`: Utilities for working with a stack trace, extended by the driver package
+
+### errTemplate
+
+The `errTemplate` is a tagged template literal. It allows us to maintain consistent behavior & formatting in our error messages, when we see a variable, we format it depending on the target environment.
+
+The error message returns a message that defaults to being formatted for the terminal, and has a `forBrowser` method which returns the error message where the variables are wrapped in backticks '`' for Markdown display in the browser.
+
+Return Value of `errTemplate` (`ErrTemplateResult`):
+
+```ts
+{
+  // Will always exist, this is the terminal-formatted error message
+  message: string,
+  // Will always exist, this is the browser-formatted error message
+  messageMarkdown: string,
+  details?: string, // Exists if there is `details()` call in the errTemplate
+  originalError?: ErrorLike // Exists if an error was passed into the `details()`
+}
+```
+
+#### Example:
+
+```ts
+CANNOT_TRASH_ASSETS: (arg1: string) => {
+  return errTemplate`\
+      Warning: We failed to trash the existing run results.
+
+      This error will not alter the exit code.
+
+      ${details(arg1)}`
+},
+```
+
+In this case, `arg1` will be highlighted in yellow when printed to the terminal.
+
+
+```ts
+PLUGINS_FILE_ERROR: (arg1: string, arg2: Error) => {
+  return errTemplate`\
+      The plugins file is missing or invalid.
+
+      Your \`pluginsFile\` is set to ${arg1}, but either the file is missing, it contains a syntax error, or threw an error when required. The \`pluginsFile\` must be a \`.js\`, \`.ts\`, or \`.coffee\` file.
+
+      Or you might have renamed the extension of your \`pluginsFile\`. If that's the case, restart the test runner.
+
+      Please fix this, or set \`pluginsFile\` to \`false\` if a plugins file is not necessary for your project.
+
+      ${details(arg2)}
+    `
+},
+```
+
+`arg1` will be highlighted in `blue` for the terminal, and wrapped in backticks when called with `forBrowser`. Details will be printed in `yellow` as a stack trace when printed to the terminal, or shown as a stack-trace in the browser.
+
+### Error Wrapping
+
+Any time we know about an edge case that is an error, we should define an error in `errors.ts`. This error should be retrieved by `getError`, which converts it to a `CypressError`.
+
+The `CypressError` is an `Error` containing the message returned from the `errTemplate`. The `stack` is set to that of the `originalError` if it exists (i.e. the error object passed into `details`), otherwise it's the `stack` from where the `getError` / `throwError` is called.
+
+
+The `CypressError` has an `isCypressErr` prop which we use as a duck-type guard against exiting the process when logging exceptions. It also maintains a reference to the `originalError` if it exists.
+
+### Child-Process Errors
+
+All errors that occur in a child process spawned by Cypress should be sent over the `ipc` bridge using `util.serializeError`.
+
+This ensures the `name`, `message`, `stack`, and any other relevant details are preserved and can be handled by the standard process of Cypress' error standardization / wrapping.

npm/create-cypress-tests/src/component-testing/init-component-testing.test.ts

@@ -307,7 +307,7 @@ describe('init component tests script', () => {
     ).to.be.true
   })
 
-  it('Doesn\'t affect injected code if user has custom babel.config.js', async () => {
+  it(`Doesn't affect injected code if user has custom babel.config.js`, async () => {
     createTempFiles({
       '/cypress/plugins/index.js': 'module.exports = (on, config) => {}',
       '/cypress.config.ts': 'export default {}',

npm/react/examples/nextjs/cypress/components/Page.cy.jsx

@@ -12,7 +12,7 @@ describe('NextJS page', () => {
     cy.contains('.search-text', 'You are searching for: Cypress')
   })
 
-  it('It doesn\'t run the `.getInitialProps()`', () => {
+  it(`It doesn't run the .getInitialProps()`, () => {
     mount(<IndexPage />)
 
     cy.get('[data-testid="server-result"').should('not.exist')

npm/vite-dev-server/src/makeCypressPlugin.ts

@@ -55,7 +55,6 @@ export const makeCypressPlugin = (
       base = config.base
     },
     async transformIndexHtml () {
-      debug('transformIndexHtml with base', base)
       const indexHtmlPath = indexHtml ? resolve(projectRoot, indexHtml) : resolve(__dirname, '..', 'index.html')
       const indexHtmlContent = await readFile(indexHtmlPath, { encoding: 'utf8' })
       // find </body> last index

npm/vite-dev-server/src/resolveServerConfig.ts

@@ -1,5 +1,5 @@
 import Debug from 'debug'
-import { createServer, ViteDevServer, InlineConfig } from 'vite'
+import { InlineConfig } from 'vite'
 import { dirname, resolve } from 'path'
 import getPort from 'get-port'
 import { makeCypressPlugin } from './makeCypressPlugin'

package.json

@@ -17,7 +17,7 @@
     "bump": "node ./scripts/binary.js bump",
     "check-node-version": "node scripts/check-node-version.js",
     "check-terminal": "node scripts/check-terminal.js",
-    "clean": "lerna run clean --parallel --no-bail",
+    "clean": "lerna run clean --parallel --no-bail || echo 'ok, errors while cleaning'",
     "check-ts": "gulp checkTs",
     "clean-deps": "find . -depth -name node_modules -type d -exec rm -rf {} \\;",
     "clean-untracked-files": "git clean -d -f",
@@ -28,6 +28,7 @@
     "cypress:open:debug": "node ./scripts/debug.js cypress:open",
     "precypress:run": "yarn ensure-deps",
     "cypress:run": "cypress run --dev",
+    "cypress:run:ct": "cypress run-ct --dev",
     "precypress:run:debug": "yarn ensure-deps",
     "cypress:run:debug": "node ./scripts/debug.js cypress:run",
     "cypress:verify": "cypress verify --dev",
@@ -50,7 +51,7 @@
     "stop-only": "npx stop-only --skip .cy,.publish,.projects,node_modules,dist,dist-test,fixtures,lib,bower_components,src,__snapshots__ --exclude cypress-tests.ts,*only.cy.js",
     "stop-only-all": "yarn stop-only --folder packages",
     "pretest": "yarn ensure-deps",
-    "test": "yarn lerna exec yarn test --scope cypress --scope \"'@packages/{config,data-context,electron,extension,https-proxy,launcher,net-stubbing,network,proxy,rewriter,socket}'\"",
+    "test": "yarn lerna exec yarn test --scope cypress --scope \"'@packages/{config,errors,data-context,electron,extension,https-proxy,launcher,net-stubbing,network,proxy,rewriter,socket}'\"",
     "test-debug": "lerna exec yarn test-debug --ignore \"'@packages/{driver,root,static,web-config}'\"",
     "pretest-e2e": "yarn ensure-deps",
     "test-integration": "lerna exec yarn test-integration --ignore \"'@packages/{driver,root,static,web-config}'\"",
@@ -125,7 +126,6 @@
     "@typescript-eslint/eslint-plugin": "4.18.0",
     "@typescript-eslint/parser": "4.18.0",
     "@urql/introspection": "^0.3.0",
-    "ansi-styles": "3.2.1",
     "arg": "4.1.2",
     "ascii-table": "0.0.9",
     "autobarrel": "^1.1.0",
@@ -213,7 +213,7 @@
     "snap-shot-it": "7.9.3",
     "start-server-and-test": "1.10.8",
     "stop-only": "3.0.1",
-    "strip-ansi": "4.0.0",
+    "strip-ansi": "6.0.0",
     "term-to-html": "1.2.0",
     "terminal-banner": "1.1.0",
     "through": "2.3.8",