Merge branch 'develop' into remove-redundant-test-binary-jobs

Author: emilyrohrbough

.gitattributes

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

.gitignore

@@ -18,6 +18,8 @@ packages/config/lib/*.js
 
 # from data-context, compiled .js files
 packages/data-context/src/**/*.js
+packages/errors/src/**/*.js
+packages/errors/test/**/*.js
 
 # from desktop-gui
 packages/desktop-gui/cypress/videos
@@ -68,6 +70,7 @@ packages/socket/lib/*.js
 
 # from system-tests
 system-tests/.projects
+system-tests/.http-mitm-proxy
 system-tests/fixtures/large-img
 
 # from npm/react
@@ -83,6 +86,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,6 @@
   "i18n-ally.keystyle": "nested",
 
   // Volar is the main extension that powers Vue's language features.
-  "volar.autoCompleteRefs": false,
-  "volar.takeOverMode.enabled": true
+  // "volar.autoCompleteRefs": false,
+  // "volar.takeOverMode.enabled": 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

@@ -89,7 +89,7 @@ executors:
   # https://github.com/CircleCI-Public/windows-orb/blob/master/src/executors/default.yml
   # https://circleci.com/docs/2.0/hello-world-windows/#software-pre-installed-in-the-windows-image
   windows: &windows-executor
-    machine:  
+    machine:
       image: windows-server-2019-vs2019:stable
       shell: bash.exe -eo pipefail
     resource_class: windows.medium
@@ -151,7 +151,7 @@ commands:
             - cypress
             - .ssh
             - node_modules # contains the npm i -g modules
-  
+
   install_cache_helpers_dependencies:
     steps:
       - run:
@@ -987,6 +987,7 @@ jobs:
       - run:
           name: Linting 🧹
           command: |
+            yarn clean
             git clean -df
             yarn lint
       - run:
@@ -1075,12 +1076,14 @@ jobs:
             # run unit tests from each individual package
             - run: yarn test
             - 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:
@@ -1913,13 +1916,6 @@ jobs:
           repo: cypress-example-kitchensink
           browser: "electron"
 
-  test-binary-against-awesome-typescript-loader:
-    <<: *defaults
-    steps:
-      - test-binary-against-repo:
-          repo: cypress-test-awesome-typescript-loader
-          browser: "electron"
-
   test-binary-against-kitchensink-firefox:
     <<: *defaults
     resource_class: medium
@@ -2212,26 +2208,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
@@ -2346,14 +2322,14 @@ windows-workflow: &windows-workflow
         executor: windows
         requires:
           - windows-build
-      
+
     - unit-tests:
         name: windows-unit-tests
         executor: windows
         resource_class: windows.medium
         requires:
           - windows-build
-    
+
     - create-build-artifacts:
         name: windows-create-build-artifacts
         executor: windows

guides/error-handling.md

@@ -0,0 +1,85 @@
+## 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.throw` 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.
+

package.json

@@ -17,15 +17,17 @@
     "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'",
     "clean-deps": "find . -depth -name node_modules -type d -exec rm -rf {} \\;",
     "clean-untracked-files": "git clean -d -f",
     "precypress:open": "yarn ensure-deps",
     "cypress:open": "cypress open --dev --global",
+    "cypress:open:ct": "cypress open-ct --dev --global",
     "precypress:open:debug": "yarn ensure-deps",
     "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",
@@ -46,7 +48,7 @@
     "stop-only": "npx stop-only --skip .cy,.publish,.projects,node_modules,dist,dist-test,fixtures,lib,bower_components,src,__snapshots__ --exclude e2e.ts,cypress-tests.ts,*only_spec.js",
     "stop-only-all": "yarn stop-only --folder packages",
     "pretest": "yarn ensure-deps",
-    "test": "yarn lerna exec yarn test --scope cypress --scope \"'@packages/{config,electron,extension,https-proxy,launcher,net-stubbing,network,proxy,rewriter,runner,runner-shared,socket}'\"",
+    "test": "yarn lerna exec yarn test --scope cypress --scope \"'@packages/{config,errors,electron,extension,https-proxy,launcher,net-stubbing,network,proxy,rewriter,runner,runner-shared,socket}'\"",
     "test-debug": "lerna exec yarn test-debug --ignore \"'@packages/{desktop-gui,driver,root,static,web-config}'\"",
     "pretest-e2e": "yarn ensure-deps",
     "test-integration": "lerna exec yarn test-integration --ignore \"'@packages/{desktop-gui,driver,root,static,web-config}'\"",
@@ -103,7 +105,6 @@
     "@types/sinon-chai": "3.2.3",
     "@typescript-eslint/eslint-plugin": "4.18.0",
     "@typescript-eslint/parser": "4.18.0",
-    "ansi-styles": "3.2.1",
     "arg": "4.1.2",
     "ascii-table": "0.0.9",
     "aws-sdk": "2.814.0",
@@ -181,7 +182,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",

packages/config/__snapshots__/index_spec.js

@@ -34,7 +34,6 @@ exports['src/index .getDefaultValues returns list of public config keys 1'] = {
   "ignoreTestFiles": "*.hot-update.js",
   "includeShadowDom": false,
   "integrationFolder": "cypress/integration",
-  "isInteractive": true,
   "keystrokeDelay": 0,
   "modifyObstructiveCode": true,
   "numTestsKeptInMemory": 50,
@@ -77,6 +76,7 @@ exports['src/index .getDefaultValues returns list of public config keys 1'] = {
   "configFile": "cypress.json",
   "devServerPublicPathRoute": "/__cypress/src",
   "hosts": null,
+  "isInteractive": true,
   "isTextTerminal": false,
   "morgan": true,
   "namespace": "__cypress",