diff --git a/source/api/commands/click.md b/source/api/commands/click.md index 26a506680a..61cdc43c26 100644 --- a/source/api/commands/click.md +++ b/source/api/commands/click.md @@ -140,10 +140,10 @@ Sequence | Notes ```js // execute a SHIFT + click on the first
  • -// {release: false} is necessary so that +// { release: false } is necessary so that // SHIFT will not be released after the type command cy.get('body').type('{shift}', { release: false }) - .get('li:first').click() +cy.get('li:first').click() ``` # Notes @@ -154,24 +154,6 @@ cy.get('body').type('{shift}', { release: false }) `.click()` is an "action command" that follows all the rules {% url 'defined here' interacting-with-elements %}. -## Events - -### Events that are fired: - -```javascript -cy.get('button').click() -// mousedown -// focus -// mouseup -// click -``` - -The events are fired to spec, including the coordinates of where the event took place. - -At the moment, `mouseover` and `mouseout` events are *not* fired. {% open_an_issue %} if you need this to be fixed. - -Additionally if the `mousedown` event causes the element to be removed from the DOM, the remaining events should continue to be fired, but to the resulting element left below the removed element. This has also not been implemented. {% open_an_issue %} if you need this to be fixed. - ## Focus ### Focus is given to the first focusable element @@ -186,14 +168,6 @@ However, Cypress additionally handles situations where a child descendent is cli If the mousedown event has its default action prevented (`e.preventDefault()`) then the element will not receive focus as per the spec. -### Element removal during `mousedown` or `mouseup` - -The spec states what should happen if the element clicked is removed from the DOM during `mousedown` or `mouseup`, but Cypress is not currently factoring this in. {% open_an_issue %} if you need this to be fixed. - -### pointer-events: none - -Cypress does not currently factor in `pointer-events: none` in its clicking algorithm. {% open_an_issue %} if you need this to be fixed. - # Rules ## Requirements {% helper_icon requirements %} @@ -210,10 +184,10 @@ Cypress does not currently factor in `pointer-events: none` in its clicking algo # Command Log -***Click the button in the form that has text "Create User"*** +***Click the button*** ```javascript -cy.get('form').find('button').contains('Create User').click() +cy.get('.action-btn').click() ``` The commands above will display in the Command Log as: @@ -224,6 +198,10 @@ When clicking on `click` within the command log, the console outputs the followi {% imgTag /img/api/click/click-coords-and-events-in-console.png "console.log for click" %} +{% history %} +{% url "3.5.0" changelog#3-5-0 %} | Added sending `mouseover`, `mousemove`, `mouseout`, `pointerdown`, `pointerup`, and `pointermove` during `.click()` +{% endhistory %} + # See also - {% url `.check()` check %} diff --git a/source/api/commands/dblclick.md b/source/api/commands/dblclick.md index 02c4db9a51..f91299f1ad 100644 --- a/source/api/commands/dblclick.md +++ b/source/api/commands/dblclick.md @@ -9,6 +9,10 @@ Double-click a DOM element. ```javascript .dblclick() .dblclick(options) +.dblclick(position) +.dblclick(position, options) +.dblclick(x, y) +.dblclick(x, y, options) ``` ## Usage @@ -30,6 +34,20 @@ cy.window().dblclick() // Errors, 'window' does not yield DOM element ## Arguments +**{% fa fa-angle-right %} position** ***(String)*** + +The position where the double click should be issued. The `center` position is the default position. Valid positions are `topLeft`, `top`, `topRight`, `left`, `center`, `right`, `bottomLeft`, `bottom`, and `bottomRight`. + +{% imgTag "/img/api/coordinates-diagram.jpg" "cypress-command-positions-diagram" %} + +**{% fa fa-angle-right %} x** ***(Number)*** + +The distance in pixels from the element's left to issue the double click. + +**{% fa fa-angle-right %} y** ***(Number)*** + +The distance in pixels from the element's top to issue the double click. + **{% fa fa-angle-right %} options** ***(Object)*** Pass in an options object to change the default behavior of `.dblclick()`. @@ -37,6 +55,8 @@ Pass in an options object to change the default behavior of `.dblclick()`. Option | Default | Description --- | --- | --- `log` | `true` | {% usage_options log %} +`force` | `false` | {% usage_options force dblclick %} +`multiple` | `true` | {% usage_options multiple dblclick %} `timeout` | {% url `defaultCommandTimeout` configuration#Timeouts %} | {% usage_options timeout .dblclick %} ## Yields {% helper_icon yields %} @@ -53,6 +73,81 @@ Option | Default | Description cy.get('a#nav1').dblclick() // yields the ``` +## Position + +### Specify a position of the element to double click + +Click the bottom center of the button. + +```javascript +cy.get('button').dblclick('bottom') +``` + +## Coordinates + +### Specify coordinates relative to the top left corner + +The double click below will be issued inside of the element (30px from the left and 10px from the top). + +```javascript +cy.get('button').dblclick(30, 10) +``` + +## Options + +### Force a double click regardless of its actionable state + +Forcing a double click overrides the {% url 'actionable checks' interacting-with-elements#Forcing %} Cypress applies and will automatically fire the events. + +```javascript +cy.get('button').dblclick({ force: true }) +``` + +### Force a double click with position argument + +```javascript +cy.get('button').dblclick('topRight', { force: true }) +``` + +### Force a double click with relative coordinates + +```javascript +cy.get('button').dblclick(60, 60, { force: true }) +``` + +### Double click all buttons found on the page + +By default, Cypress will iteratively apply the double click to each element and will also log to the {% url 'Command Log' test-runner#Command-Log %} multiple times. + +You can turn this off by passing `multiple: false` to `.dblclick()`. + +```javascript +cy.get('button').dblclick({ multiple: false }) +``` + +## Double click with key combinations + +The `.dblclick()` command may also be fired with key modifiers in combination with the {% url "`.type()`" type %} command in order to simulate character sequences while double clicking, such as `SHIFT + double click`. In order to keep the modifier key active, `{release: false}` should be passed to the options of the {% url "`.type()`" type %} command. + +The following modifiers can be combined with `.dblclick()`. + +Sequence | Notes +--- | --- +`{alt}` | Activates the `altKey` modifier. Aliases: `{option}` +`{ctrl}` | Activates the `ctrlKey` modifier. Aliases: `{control}` +`{meta}` | Activates the `metaKey` modifier. Aliases: `{command}`, `{cmd}` +`{shift}` | Activates the `shiftKey` modifier. + +### Alt click + +```js +// execute a ALT + dblclick on the first
  • +// { release: false } is necessary so that +// ALT will not be released after the type command +cy.get('body').type('{alt}', { release: false }) +cy.get('li:first').dblclick() +``` + # Notes ## Actionability @@ -77,10 +172,10 @@ cy.get('a#nav1').dblclick() // yields the # Command Log -***Double click on a calendar schedule*** +***Double click on a div*** ```javascript -cy.get('[data-schedule-id="4529114"]:first').dblclick() +cy.get('.action-div').dblclick() ``` The commands above will display in the Command Log as: @@ -91,6 +186,12 @@ When clicking on `dblclick` within the command log, the console outputs the foll {% imgTag /img/api/dblclick/element-double-clicked-on.png "console.log dblclick" %} +{% history %} +{% url "3.5.0" changelog#3-5-0 %} | Added support for options `force` and `multiple`. +{% url "3.5.0" changelog#3-5-0 %} | Added support for `position`, `x`, and `y` arguments. +{% url "3.5.0" changelog#3-5-0 %} | Added sending `mouseover`, `mousemove`, `mouseout`, `pointerdown`, `pointerup`, and `pointermove` during `.dblclick()`. +{% endhistory %} + # See also - {% url `.click()` click %} diff --git a/source/api/commands/rightclick.md b/source/api/commands/rightclick.md index f71fb806c8..b0b5d58455 100644 --- a/source/api/commands/rightclick.md +++ b/source/api/commands/rightclick.md @@ -174,10 +174,10 @@ cy.get('.menu-item').rightclick() # Command Log -***Right click the button in the form that has text "Create User"*** +***Right click the DOM element*** ```javascript -cy.get('form').find('button').contains('Create User').rightclick() +cy.get('.rightclick-action-div').rightclick() ``` The commands above will display in the Command Log as: diff --git a/source/api/commands/trigger.md b/source/api/commands/trigger.md index 1d235ee076..08e7952f8a 100644 --- a/source/api/commands/trigger.md +++ b/source/api/commands/trigger.md @@ -88,9 +88,9 @@ cy.wait(1000) cy.get('.target').trigger('mouseleave') ``` -### jQuery UI Sortable +### jQuery UI Sortable -To simulate drag and drop using jQuery UI sortable requires `pageX` and `pageY` properties along with `which:1`. +To simulate drag and drop using jQuery UI sortable requires `pageX` and `pageY` properties along with `which:1`. ```javascript cy.get('[data-cy=draggable]') @@ -137,7 +137,7 @@ cy.get('button').trigger('mousedown', 'topRight') ### Specify explicit coordinates relative to the top left corner ```javascript -cy.get('button').trigger('contextmenu', 15, 40) +cy.get('button').trigger('mouseup', 15, 40) ``` ## Options @@ -227,6 +227,7 @@ When clicking on `trigger` within the command log, the console outputs the follo {% imgTag /img/api/trigger/console-log-trigger.png "console log trigger" %} {% history %} +{% url "3.5.0" changelog#3-5-0 %} | Added `screenX` and `screenY` properties to events {% url "0.20.0" changelog#0-20-0 %} | `.trigger()` command added {% endhistory %} diff --git a/source/guides/core-concepts/interacting-with-elements.md b/source/guides/core-concepts/interacting-with-elements.md index f403a22ff0..13849853ed 100644 --- a/source/guides/core-concepts/interacting-with-elements.md +++ b/source/guides/core-concepts/interacting-with-elements.md @@ -36,6 +36,7 @@ Cypress will wait for the element to pass all of these checks for the duration o - {% urlHash 'Scroll the element into view.' Scrolling %} - {% urlHash 'Ensure the element is not hidden.' Visibility %} - {% urlHash 'Ensure the element is not disabled.' Disability %} +- {% urlHash 'Ensure the element is not detached.' Detached %} - {% urlHash 'Ensure the element is not readonly.' Readonly %} - {% urlHash 'Ensure the element is not animating.' Animations %} - {% urlHash 'Ensure the element is not covered.' Covering %} @@ -75,6 +76,12 @@ The following calculations factor in CSS translations and transforms. Cypress checks whether an element's `disabled` property is `true`. +## Detached + +When many applications rerender the DOM, they actually remove the DOM element and insert a new DOM element in its place with the newly change attributes. + +Cypress checks whether an element you are making assertions is detached from the DOM. This checks that the element is still within the `document` of the application under test. + ## Readonly Cypress checks whether an element's `readonly` property is set during {% url "`.type()`" type %}. @@ -164,7 +171,7 @@ We recommend placing `debugger` or using the {% url `.debug()` debug %} command Make sure your Developer Tools are open and you can get pretty close to "seeing" the calculations Cypress is performing. -As of `0.20.0`, you can also {% url 'bind to Events' catalog-of-events %} that Cypress fires as it's working with your element. Using a debugger with these events will give you a much lower level view into how Cypress works. +You can also {% url 'bind to Events' catalog-of-events %} that Cypress fires as it's working with your element. Using a debugger with these events will give you a much lower level view into how Cypress works. ```js // break on a debugger before the action command @@ -202,6 +209,7 @@ We will NOT perform these: - Scroll the element into view - Ensure it is visible - Ensure it is not disabled +- Ensure it is not detached - Ensure it is not readonly - Ensure it is not animating - Ensure it is not covered diff --git a/themes/cypress/source/img/api/click/click-button-in-form-during-test.png b/themes/cypress/source/img/api/click/click-button-in-form-during-test.png index fc67e3cc71..dc95b74a1a 100644 Binary files a/themes/cypress/source/img/api/click/click-button-in-form-during-test.png and b/themes/cypress/source/img/api/click/click-button-in-form-during-test.png differ diff --git a/themes/cypress/source/img/api/click/click-coords-and-events-in-console.png b/themes/cypress/source/img/api/click/click-coords-and-events-in-console.png index 72d6bcd057..bd5ffd2530 100644 Binary files a/themes/cypress/source/img/api/click/click-coords-and-events-in-console.png and b/themes/cypress/source/img/api/click/click-coords-and-events-in-console.png differ diff --git a/themes/cypress/source/img/api/dblclick/double-click-in-testing.png b/themes/cypress/source/img/api/dblclick/double-click-in-testing.png index 037a370c75..1057b17ea1 100644 Binary files a/themes/cypress/source/img/api/dblclick/double-click-in-testing.png and b/themes/cypress/source/img/api/dblclick/double-click-in-testing.png differ diff --git a/themes/cypress/source/img/api/dblclick/element-double-clicked-on.png b/themes/cypress/source/img/api/dblclick/element-double-clicked-on.png index 28968e9522..028275ed7f 100644 Binary files a/themes/cypress/source/img/api/dblclick/element-double-clicked-on.png and b/themes/cypress/source/img/api/dblclick/element-double-clicked-on.png differ