Merge pull request #5 from JaySunSyn/refactor-query

Refactor query and commands

.editorconfig

@@ -0,0 +1,28 @@
+# EditorConfig helps developers define and maintain consistent
+# coding styles between different editors and IDEs
+# editorconfig.org
+
+root = true
+
+[*]
+
+# Change these settings to your own preference
+indent_style = space
+indent_size = 2
+
+# We recommend you to keep these unchanged
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.json]
+indent_size = 2
+
+[*.{html,js}]
+block_comment_start = /**
+block_comment = *
+block_comment_end = */

.eslintrc

@@ -0,0 +1,16 @@
+{
+  "extends": [
+    "google"
+  ],
+  "env": {
+    "es6": true
+  },
+  "rules": {
+    "require-jsdoc": 0,
+    "max-len": [2, {
+      "code": 120,
+      "tabWidth": 2,
+      "ignoreUrls": true
+    }]
+  }
+}

.gitignore

@@ -0,0 +1 @@
+node_modules/

README.md

@@ -1,73 +1,143 @@
 # Cypress Daywalker
+[![Gitter](https://img.shields.io/gitter/room/DAVFoundation/DAV-Contributors.svg?style=flat-square)](https://gitter.im/cypress-daywalker)
+
+Please star this repo if you use this plugin.
+This helps me to understand how many people it is useful for and motivates me to continue improving it.
 
 [![Gitter](https://img.shields.io/gitter/room/DAVFoundation/DAV-Contributors.svg?style=flat-square)](https://gitter.im/cypress-daywalker)
 
 ## Installation
 
-Add the plugin to `devDependencies`
+### 1. Install the dependency
+Add the plugin to your `devDependencies`
+
 ```bash
 npm install -D cypress-daywalker
 ```
-
+### 2. Add daywalker commands
 At the top of **`cypress/support/commands.js`**:
 ```js
 import 'cypress-daywalker/commands'
 ```
 
-## Usage
-
-### Include the daywalker script
+### 3. Add the Daywalker script
+You need to inject `cypress-daywalker.js` into your application's entrypoint. This can happen by manually or dynamically adding a script tag to your entrypoint file.
 
-**Include the daywalker script automatically:**
+#### Via a static script tag
+This is the easiest way: At the top of your entrypoint file e.g. **`index.html`** add the following script tag.
 
-The daywalker script gets injected when visiting a page via `cy.visit()`.
-
-If you do not use `cy.visit`, add the script manually.
-
-**Include the daywalker script manually:**
-
-either via a) At the top of your entrypoint e.g. **`index.html`** add following script tag
 ```html
-    <script src="./node_modules/cypress-daywalker/cypress-daywalker.js"></script>
+  <!-- Eventually adjust the path to your node modules -->
+  <script src="./node_modules/cypress-daywalker/cypress-daywalker.js"></script>
 ```
-or via b) Dynamically add the daywalker script before each test
+
+#### Via a dynamic script tag
+You might want to avoid that the script tag ends up in a production environment. Therefore, you can inject the script tag into your document before any other javascript gets executed by listening to the `window:before:load` event.
 
 ```javascript
 context('Default', () => {
   before(() => {
+
+    // INJECT THE SCRIPT LIKE THIS:
     cy.on('window:before:load', (w) => {
       const script = w.document.createElement('script');
+      // Eventually adjust the path to your node modules
       script.src = '/node_modules/cypress-daywalker/cypress-daywalker.js';
       w.document.querySelector('head').appendChild(script);
     });
+
     cy.visit('http://localhost:3000/');
   });
   it('input gets filled', () => {
-    ...
+    // Test stuff
   });
 });
 ```
 
-[Example](https://github.com/JaySunSyn/cypress-daywalker/blob/master/example/cypress/integration/example.spec.js)
+## Usage
+Find an [example here](https://github.com/JaySunSyn/cypress-daywalker/blob/master/example/).
+
+Not all CSS selectors are supported yet, so do not use it as you would use jQuery or the usual querySelector command. Please create issues of use cases where you would like better querying functionalities. For the apps where this plugin was tested (very large and very small apps) the current functionality worked pretty well.
+
+### Query
+
+#### By Tag
+
+This works very well.
+
+```js
+cy.get('paper-button')
+```
+
+#### By ID
+
+This works very well.
+
+```js
+cy.get('#submit')
+cy.get('paper-button#submit')
+```
+
+#### By Class
+
+Find custom elements everywhere in the app or *native elements at root level*.
+
+```js
+cy.get('.foo')
+cy.get('.foo.moo')
+```
+
+#### By Direct Parent
+
+```html
+<div class="find-me">
+  <paper-button></paper-button>
+</div>
+<paper-button></paper-button>
+```
+
+```js
+cy.get('.find-me > paper-button')
+```
+
+#### By path
+
+Starting from the root level:
+
+```js
+cy.get('div my-element paper-input#important')
+```
+
+or starting from any custom element:
+
+```js
+cy.get('my-element div#jay')
+```
+
+Starting a path with a native element which is inside a shadow root is not supported.
+
+### Lazy loaded components
+If you lazy load some components, you, for example, can add a `.wait(500)` to your `.visit()` command to wait for them to get available.
 
-### Custom commands
+### Commands
+Not all cypress commands can be used yet. For some, there are replacements below.
 
 #### Click
 
 Instead of `.click()` use:
 
 ```js
-cy.get('paper-button').dispatch('click')
-cy.get('paper-button').dispatch(new MouseEvent('click'))
+cy.get('paper-button').dispatch('click') // Results in Event('click')
+cy.get('paper-button').dispatch(new MouseEvent('click')) // Or pass in any other event
 ```
 
 #### Type
 
 Instead of `.type('Hello world')` use:
 
 ```js
-cy.get('paper-input').setProp('moto moto')
-cy.get('paper-input').setProp('Question', 'label')
+cy.get('paper-input').setProp('moto moto') // Results in the value property gets set
+cy.get('paper-input').setProp('Question', 'label') // Or specify the property name
 ```
 
 #### Invoke