chore: copy jsdoc for mount

bahmutov · bahmutov · commit 219b271f046a · 2019-02-17T22:07:34.000-05:00
diff --git a/cypress/integration/hello-world-inline-spec.js b/cypress/integration/hello-world-inline-spec.js
@@ -1,3 +1,5 @@
+/// <reference types="cypress" />
+/// <reference types="../support" />
 import React from 'react'
 const HelloWorld = () => <p>Hello World!</p>
 describe('HelloWorld component', () => {
diff --git a/cypress/support/commands.js b/cypress/support/commands.js
@@ -29,33 +29,31 @@ import { stylesCache, setXMLHttpRequest, setAlert } from '../../lib'
     @function   cy.injectReactDOM
 **/
 Cypress.Commands.add('injectReactDOM', () => {
-  return cy
-    .log('Injecting ReactDOM for Unit Testing')
-    .then(() => {
-      // Generate inline script tags for UMD modules
-      const scripts = Cypress.modules
-        .map(module => `<script>${module.source}</script>`)
-        .join('')
-      // include React and ReactDOM to force DOM to register all DOM event listeners
-      // otherwise the component will NOT be able to dispatch any events
-      // when it runs the second time
-      // https://github.com/bahmutov/cypress-react-unit-test/issues/3
-      var html = `<body>
+  return cy.log('Injecting ReactDOM for Unit Testing').then(() => {
+    // Generate inline script tags for UMD modules
+    const scripts = Cypress.modules
+      .map(module => `<script>${module.source}</script>`)
+      .join('')
+    // include React and ReactDOM to force DOM to register all DOM event listeners
+    // otherwise the component will NOT be able to dispatch any events
+    // when it runs the second time
+    // https://github.com/bahmutov/cypress-react-unit-test/issues/3
+    var html = `<body>
           <div id="cypress-jsdom"></div>
           ${scripts}
         </body>`
-      const document = cy.state('document')
-      document.write(html)
-      document.close()
-    })
+    const document = cy.state('document')
+    document.write(html)
+    document.close()
+  })
 })
 
 cy.stylesCache = stylesCache
 /** Caches styles from previously compiled components for reuse
     @function   cy.copyComponentStyles
     @param      {Object}  component
 **/
-Cypress.Commands.add('copyComponentStyles', (component) => {
+Cypress.Commands.add('copyComponentStyles', component => {
   // need to find same component when component is recompiled
   // by the JSX preprocessor. Thus have to use something else,
   // like component name
@@ -84,32 +82,48 @@ Cypress.Commands.add('copyComponentStyles', (component) => {
   styles.forEach(function (style) {
     head.appendChild(style)
   })
-  return
 })
 
-/** Mount a React component in a blank document; register it as an alias
-    To access: use an alias, e.g.cy.get('@Component').its('state').should(...)
-    @function   cy.mount
-    @param      {Object}  jsx
-    @param      {string}  [Component]   alias
-**/
-Cypress.Commands.add('mount', (jsx, alias) => {
-  // Get the displayname property via the component constructor
+/**
+ * Mount a React component in a blank document; register it as an alias
+ * To access: use an alias or original component reference
+ *  @function   cy.mount
+ *  @param      {Object}  jsx - component to mount
+ *  @param      {string}  [Component] - alias to use later
+ *  @example
+ ```
+ import Hello from './hello.jsx'
+ // mount and access by alias
+ cy.mount(<Hello />, 'Hello')
+ // using default alias
+ cy.get('@Component')
+ // using specified alias
+ cy.get('@Hello').its('state').should(...)
+ // using original component
+ cy.get(Hello)
+ ```
+ **/
+export const mount = (jsx, alias) => {
+  // Get the display name property via the component constructor
   const displayname = alias || jsx.type.prototype.constructor.name
-  cy
-    .injectReactDOM()
+  cy.injectReactDOM()
     .log(`ReactDOM.render(<${displayname} ... />)`, jsx.props)
     .window({ log: false })
     .then(setXMLHttpRequest)
     .then(setAlert)
     .then(win => {
       const { ReactDOM } = win
       const document = cy.state('document')
-      const component = ReactDOM.render(jsx, document.getElementById('cypress-jsdom'))
+      const component = ReactDOM.render(
+        jsx,
+        document.getElementById('cypress-jsdom')
+      )
       cy.wrap(component, { log: false }).as(displayname)
     })
   cy.copyComponentStyles(jsx)
-})
+}
+
+Cypress.Commands.add('mount', mount)
 
 /** Get one or more DOM elements by selector or alias.
     Features extended support for JSX and React.Component
@@ -124,7 +138,10 @@ Cypress.Commands.overwrite('get', (originalFn, selector, options) => {
   switch (typeof selector) {
     case 'object':
       // If attempting to use JSX as a selector, reference the displayname
-      if (selector.$$typeof && selector.$$typeof.toString().startsWith('Symbol(react')) {
+      if (
+        selector.$$typeof &&
+        selector.$$typeof.toString().startsWith('Symbol(react')
+      ) {
         const displayname = selector.type.prototype.constructor.name
         return originalFn(`@${displayname}`, options)
       }
diff --git a/cypress/support/index.d.ts b/cypress/support/index.d.ts
@@ -1,3 +1,7 @@
+// I hope to get types and docs from functions imported from ./commands one day
+// but for now have to document methods in both places
+// like this: import {mount} from './commands'
+
 declare namespace Cypress {
   interface Cypress {
     stylesCache: any
@@ -10,6 +14,25 @@ declare namespace Cypress {
   interface Chainable<Subject = any> {
     injectReactDOM: () => Chainable<void>
     copyComponentStyles: (component: Symbol) => Chainable<void>
+    /**
+     * Mount a React component in a blank document; register it as an alias
+     * To access: use an alias or original component reference
+     *  @function   cy.mount
+     *  @param      {Object}  jsx - component to mount
+     *  @param      {string}  [Component] - alias to use later
+     *  @example
+    ```
+    import Hello from './hello.jsx'
+    // mount and access by alias
+    cy.mount(<Hello />, 'Hello')
+    // using default alias
+    cy.get('@Component')
+    // using specified alias
+    cy.get('@Hello').its('state').should(...)
+    // using original component
+    cy.get(Hello)
+    ```
+    **/
     mount: (component: Symbol, alias?: string) => Chainable<void>
     get<S = any>(alias: string | symbol | Function, options?: Partial<Loggable & Timeoutable>): Chainable<any>
   }

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+/// <reference types="cypress" />`
	`2`	`+/// <reference types="../support" />`
`1`	`3`	`import React from 'react'`
`2`	`4`	`const HelloWorld = () => <p>Hello World!</p>`
`3`	`5`	`describe('HelloWorld component', () => {`