cypress 13.3.0 → 13.3.2

package/mount-utils/mount-utils/README.md

@@ -0,0 +1,140 @@
+# @cypress/mount-utils
+
+> **Note** this package is not meant to be used outside of cypress component testing.
+
+This library exports some shared types and utility functions designed to build adapters for components frameworks.
+
+It is used in:
+
+- [`@cypress/react`](https://github.com/cypress-io/cypress/tree/develop/npm/react)
+- [`@cypress/vue`](https://github.com/cypress-io/cypress/tree/develop/npm/vue)
+- [`@cypress/svelte`](https://github.com/cypress-io/cypress/tree/develop/npm/svelte)
+- [`@cypress/angular`](https://github.com/cypress-io/cypress/tree/develop/npm/angular)
+
+## What is a Mount Adapter?
+
+All Component Tests require a component to be **mounted**. This is generally done with a custom command, `cy.mount` by default.
+
+
+### Requirements
+
+All the functionality used to create the first party Mount adapters is available to support third parties adapters. At minimum, a Mount Adapter must:
+
+- Receive a component as the first argument. This could be class, function etc - depends on the framework.
+- Return a Cypress Chainable (for example using `cy.wrap`) that resolves whatever is idiomatic for your framework
+- Call `getContainerEl` to access the root DOM element
+
+In addition, we recommend that Mount Adapters:
+
+- call `setupHooks` to register the required lifecycle hooks for `@cypress/mount-utils` to work
+
+### Example Mount Adapter: Web Components 
+
+Here's a simple yet realistic example of Mount Adapter targeting Web Components. It uses utilities from this package (`@cypress/mount-utils`) This is recommended, so your adapter behaves similar to the first party Mount Adapters.
+
+```ts
+import {
+  ROOT_SELECTOR,
+  setupHooks,
+  getContainerEl
+} from "@cypress/mount-utils";
+
+Cypress.on("run:start", () => {
+  // Consider doing a check to ensure your adapter only runs in Component Testing mode.
+  if (Cypress.testingType !== "component") {
+    return;
+  }
+
+  Cypress.on("test:before:run", () => {
+    // Do some cleanup from previous test - for example, clear the DOM.
+    getContainerEl().innerHTML = "";
+  });
+});
+
+function maybeRegisterComponent<T extends CustomElementConstructor>(
+  name: string,
+  webComponent: T
+) {
+  // Avoid double-registering a Web Component.
+  if (window.customElements.get(name)) {
+    return;
+  }
+
+  window.customElements.define(name, webComponent);
+}
+
+export function mount(
+  webComponent: CustomElementConstructor
+): Cypress.Chainable {
+  // Get root selector defined in `cypress/support.component-index.html
+  const $root = document.querySelector(ROOT_SELECTOR)!;
+
+  // Change to kebab-case to comply with Web Component naming convention
+  const name = webComponent.name
+    .replace(/([a-z0–9])([A-Z])/g, "$1-$2")
+    .toLowerCase();
+
+  /// Register Web Component
+  maybeRegisterComponent(name, webComponent);
+
+  // Render HTML containing component.
+  $root.innerHTML = `<${name} id="root"></${name}>`;
+
+  // Log a messsage in the Command Log.
+  Cypress.log({
+    name: "mount",
+    message: [`<${name} ... />`],
+  });
+
+  // Return a `Cypress.Chainable` that returns whatever is idiomatic
+  // in the framework your mount adapter targets.
+  return cy.wrap(document.querySelector("#root"), { log: false });
+}
+
+// Setup Cypress lifecycle hooks.
+setupHooks();
+```
+
+Usage:
+
+```ts
+// User will generally register a `cy.mount` command in `cypress/support/component.js`:
+
+import { mount } from '@package/cypress-web-components'
+
+Cypress.Commands.add('mount', mount)
+
+// Test
+export class WebCounter extends HTMLElement {
+  constructor() {
+    super();
+  }
+
+  connectedCallback() {
+    this.innerHTML = `
+      <div>
+        <button>Counter</button>
+      </div>`;
+  }
+}
+
+
+describe('web-component.cy.ts', () => {
+  it('playground', () => {
+    cy.mount(WebCounter)
+  })
+})
+```
+
+For more robust, production ready examples, check out our first party adapters.
+
+## Compatibility
+
+| @cypress/mount-utils | cypress |
+| -------------------- | ------- |
+| <= v1                | <= v9   |
+| >= v2                | >= v10  |
+
+## Changelog
+
+[Changelog](./CHANGELOG.md)

package/mount-utils/mount-utils/dist/index.d.ts

@@ -0,0 +1,40 @@
+export declare const ROOT_SELECTOR = "[data-cy-root]";
+/**
+ * Gets the root element used to mount the component.
+ * @returns {HTMLElement} The root element
+ * @throws {Error} If the root element is not found
+ */
+export declare const getContainerEl: () => HTMLElement;
+export declare function checkForRemovedStyleOptions(mountingOptions: Record<string, any>): void;
+/**
+ * Utility function to register CT side effects and run cleanup code during the "test:before:run" Cypress hook
+ * @param optionalCallback Callback to be called before the next test runs
+ */
+export declare function setupHooks(optionalCallback?: Function): void;
+/**
+ * Remove any style or extra link elements from the iframe placeholder
+ * left from any previous test
+ *
+ * Removed as of Cypress 11.0.0
+ * @see https://on.cypress.io/migration-11-0-0-component-testing-updates
+ */
+export declare function cleanupStyles(): void;
+/**
+ * Additional styles to inject into the document.
+ * A component might need 3rd party libraries from CDN,
+ * local CSS files and custom styles.
+ *
+ * Removed as of Cypress 11.0.0.
+ * @see https://on.cypress.io/migration-11-0-0-component-testing-updates
+ */
+export declare type StyleOptions = unknown;
+/**
+ * Injects custom style text or CSS file or 3rd party style resources
+ * into the given document.
+ *
+ * Removed as of Cypress 11.0.0.
+ * @see https://on.cypress.io/migration-11-0-0-component-testing-updates
+ */
+export declare const injectStylesBeforeElement: (options: Partial<StyleOptions & {
+    log: boolean;
+}>, document: Document, el: HTMLElement | null) => void;

package/mount-utils/mount-utils/dist/index.js

@@ -0,0 +1,68 @@
+export const ROOT_SELECTOR = '[data-cy-root]';
+/**
+ * Gets the root element used to mount the component.
+ * @returns {HTMLElement} The root element
+ * @throws {Error} If the root element is not found
+ */
+export const getContainerEl = () => {
+    const el = document.querySelector(ROOT_SELECTOR);
+    if (el) {
+        return el;
+    }
+    throw Error(`No element found that matches selector ${ROOT_SELECTOR}. Please add a root element with data-cy-root attribute to your "component-index.html" file so that Cypress can attach your component to the DOM.`);
+};
+export function checkForRemovedStyleOptions(mountingOptions) {
+    for (const key of ['cssFile', 'cssFiles', 'style', 'styles', 'stylesheet', 'stylesheets']) {
+        if (mountingOptions[key]) {
+            Cypress.utils.throwErrByPath('mount.removed_style_mounting_options', key);
+        }
+    }
+}
+/**
+ * Utility function to register CT side effects and run cleanup code during the "test:before:run" Cypress hook
+ * @param optionalCallback Callback to be called before the next test runs
+ */
+export function setupHooks(optionalCallback) {
+    // We don't want CT side effects to run when e2e
+    // testing so we early return.
+    // System test to verify CT side effects do not pollute e2e: system-tests/test/e2e_with_mount_import_spec.ts
+    if (Cypress.testingType !== 'component') {
+        return;
+    }
+    // When running component specs, we cannot allow "cy.visit"
+    // because it will wipe out our preparation work, and does not make much sense
+    // thus we overwrite "cy.visit" to throw an error
+    Cypress.Commands.overwrite('visit', () => {
+        throw new Error('cy.visit from a component spec is not allowed');
+    });
+    Cypress.Commands.overwrite('session', () => {
+        throw new Error('cy.session from a component spec is not allowed');
+    });
+    Cypress.Commands.overwrite('origin', () => {
+        throw new Error('cy.origin from a component spec is not allowed');
+    });
+    // @ts-ignore
+    Cypress.on('test:before:after:run:async', () => {
+        optionalCallback === null || optionalCallback === void 0 ? void 0 : optionalCallback();
+    });
+}
+/**
+ * Remove any style or extra link elements from the iframe placeholder
+ * left from any previous test
+ *
+ * Removed as of Cypress 11.0.0
+ * @see https://on.cypress.io/migration-11-0-0-component-testing-updates
+ */
+export function cleanupStyles() {
+    Cypress.utils.throwErrByPath('mount.cleanup_styles');
+}
+/**
+ * Injects custom style text or CSS file or 3rd party style resources
+ * into the given document.
+ *
+ * Removed as of Cypress 11.0.0.
+ * @see https://on.cypress.io/migration-11-0-0-component-testing-updates
+ */
+export const injectStylesBeforeElement = (options, document, el) => {
+    Cypress.utils.throwErrByPath('mount.inject_styles_before_element');
+};

package/mount-utils/mount-utils/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@cypress/mount-utils",
+  "version": "0.0.0-development",
+  "description": "Shared utilities for the various component testing adapters",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc || echo 'built, with type errors'",
+    "postbuild": "node ../../scripts/sync-exported-npm-with-cli.js",
+    "check-ts": "tsc --noEmit",
+    "watch": "tsc -w",
+    "lint": "eslint --ext .js,.ts,.json, ."
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^17.1.0",
+    "@rollup/plugin-node-resolve": "^11.1.1",
+    "rollup": "3.7.3",
+    "rollup-plugin-dts": "5.0.0",
+    "rollup-plugin-typescript2": "^0.29.0",
+    "typescript": "^4.7.4"
+  },
+  "files": [
+    "dist"
+  ],
+  "types": "dist/index.d.ts",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cypress-io/cypress.git"
+  },
+  "homepage": "https://github.com/cypress-io/cypress/tree/develop/npm/mount-utils#readme",
+  "bugs": "https://github.com/cypress-io/cypress/issues/new?template=1-bug-report.md",
+  "publishConfig": {
+    "access": "public"
+  },
+  "nx": {
+    "targets": {
+      "build": {
+        "outputs": [
+          "{workspaceRoot}/cli/mount-utils",
+          "{projectRoot}/dist"
+        ]
+      }
+    }
+  }
+}

package/mount-utils/package.json

@@ -6,7 +6,6 @@
   "scripts": {
     "build": "tsc || echo 'built, with type errors'",
     "postbuild": "node ../../scripts/sync-exported-npm-with-cli.js",
-    "build-prod": "yarn build",
     "check-ts": "tsc --noEmit",
     "watch": "tsc -w",
     "lint": "eslint --ext .js,.ts,.json, ."
@@ -33,5 +32,15 @@
   "bugs": "https://github.com/cypress-io/cypress/issues/new?template=1-bug-report.md",
   "publishConfig": {
     "access": "public"
+  },
+  "nx": {
+    "targets": {
+      "build": {
+        "outputs": [
+          "{workspaceRoot}/cli/mount-utils",
+          "{projectRoot}/dist"
+        ]
+      }
+    }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cypress",
-  "version": "13.3.0",
+  "version": "13.3.2",
   "main": "index.js",
   "scripts": {
     "postinstall": "node index.js --exec install",
@@ -117,10 +117,26 @@
       "require": "./svelte/dist/cypress-svelte.cjs.js"
     }
   },
+  "nx": {
+    "targets": {
+      "build-cli": {
+        "dependsOn": [
+          "prebuild"
+        ],
+        "outputs": [
+          "{projectRoot}/types",
+          "{projectRoot}/build"
+        ]
+      }
+    },
+    "implicitDependencies": [
+      "@cypress/*"
+    ]
+  },
   "buildInfo": {
     "commitBranch": "develop",
-    "commitSha": "0871b03c5b21711cd23056454da8f23dcaca4950",
-    "commitDate": "2023-09-27T14:00:29.000Z",
+    "commitSha": "04a1156ccd6093441c17ea04c98570ef8470a239",
+    "commitDate": "2023-10-18T15:16:19.000Z",
     "stable": true
   },
   "description": "Cypress is a next generation front end testing tool built for the modern web",

package/react/package.json

@@ -88,6 +88,19 @@
   "publishConfig": {
     "access": "public"
   },
+  "nx": {
+    "targets": {
+      "build": {
+        "dependsOn": [
+          "!@cypress/react18:build"
+        ],
+        "outputs": [
+          "{workspaceRoot}/cli/react",
+          "{projectRoot}/dist"
+        ]
+      }
+    }
+  },
   "standard": {
     "globals": [
       "Cypress",

package/react/react/README.md

@@ -0,0 +1,14 @@
+# @cypress/react
+
+Mount React components in the open source [Cypress.io](https://www.cypress.io/) test runner
+
+> **Note:** This package is bundled with the `cypress` package and should not need to be installed separately. See the [React Component Testing Docs](https://docs.cypress.io/guides/component-testing/react/overview) for mounting React components. Installing and importing `mount` from `@cypress/react` should only be done for advanced use-cases.
+## Development
+
+Run `yarn build` to compile and sync packages to the `cypress` cli package.
+
+Run `yarn cy:open` to open Cypress component testing against real-world examples.
+
+Run `yarn test` to execute headless Cypress tests.
+
+## [Changelog](./CHANGELOG.md)