diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 110daf36e5..ea8967bfc6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -101,9 +101,9 @@ To add a page such as a new guide or API documentation: - Add the new page to the relevant directory under [`source`](/source). - Link to your new page in the [`sidebar.yml`](/source/_data/sidebar.yml). -- Add translations for the sidebar link (for English, this is located in [`en.yml`](/themes/cypress/languages/en.yml)). +- Add translations for the sidebar link for each supported language (for English, this is located in [`en.yml`](/themes/cypress/languages/en.yml)). - Build the documentation site locally so that you can visually inspect your new page and the links to it. -- Copy over the new page to other language translations - Japanese docs in [`source/ja`](/source/ja), Chinese docs in [`source/zh-cn`](/source/zh-cn). +- Commit the new file using git - we auto-generate the doc to display within each supported language, this auto-generation depends on the file existing in git. - Submit a [pull request](#Pull-Requests) for your change. #### A Worked Example @@ -167,6 +167,8 @@ Our currently supported languages can be found at [`/source/_data/languages.yml` Translate existing documentation then submit a [pull request](#Pull-Requests) for your change. +**Note:** When adding a new doc file to the English source, the English file will need to be commited to git before the translated file is auto-generated. + If a page does not have a translation, then a pre-start step copies the English file to the language folder. These copies should NOT be committed into the source code. Only when the file has been translated you can add it to the source code with `git add --force source//.../file.md` and this file will not be overwritten by the English file. ## Committing Code diff --git a/source/_data/sidebar.yml b/source/_data/sidebar.yml index 359e534ae0..21aa6765b1 100644 --- a/source/_data/sidebar.yml +++ b/source/_data/sidebar.yml @@ -111,6 +111,7 @@ api: readfile: readfile.html reload: reload.html request: request.html + rightclick: rightclick.html root: root.html route: route.html screenshot: screenshot.html diff --git a/source/api/commands/click.md b/source/api/commands/click.md index 28b1f882f5..26a506680a 100644 --- a/source/api/commands/click.md +++ b/source/api/commands/click.md @@ -228,6 +228,7 @@ When clicking on `click` within the command log, the console outputs the followi - {% url `.check()` check %} - {% url `.dblclick()` dblclick %} +- {% url `.rightclick()` rightclick %} - {% url `.select()` select %} - {% url `.submit()` submit %} - {% url `.type()` type %} diff --git a/source/api/commands/dblclick.md b/source/api/commands/dblclick.md index 7b0d3dd386..02c4db9a51 100644 --- a/source/api/commands/dblclick.md +++ b/source/api/commands/dblclick.md @@ -94,3 +94,4 @@ When clicking on `dblclick` within the command log, the console outputs the foll # See also - {% url `.click()` click %} +- {% url `.rightclick()` rightclick %} diff --git a/source/api/commands/rightclick.md b/source/api/commands/rightclick.md new file mode 100644 index 0000000000..f71fb806c8 --- /dev/null +++ b/source/api/commands/rightclick.md @@ -0,0 +1,199 @@ +--- +title: rightclick +--- + +Right click a DOM element. + +{% note warning %} +`.rightclick()` will not open context menus native to the browser. `.rightclick()` should be used to test your app's handling of right click related events such as `contextmenu`. +{% endnote %} + +# Syntax + +```javascript +.rightclick() +.rightclick(options) +.rightclick(position) +.rightclick(position, options) +.rightclick(x, y) +.rightclick(x, y, options) +``` + +## Usage + +**{% fa fa-check-circle green %} Correct Usage** + +```javascript +cy.get('.menu').rightclick() // Right click on .menu +cy.focused().rightclick() // Right click on el with focus +cy.contains('Today').rightclick() // Right click on first el containing 'Today' +``` + +**{% fa fa-exclamation-triangle red %} Incorrect Usage** + +```javascript +cy.rightclick('button') // Errors, cannot be chained off 'cy' +cy.window().rightclick() // Errors, 'window' does not yield DOM element +``` + +## Arguments + +**{% fa fa-angle-right %} position** ***(String)*** + +The position where the right 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 right click. + +**{% fa fa-angle-right %} y** ***(Number)*** + +The distance in pixels from the element's top to issue the right click. + +**{% fa fa-angle-right %} options** ***(Object)*** + +Pass in an options object to change the default behavior of `.rightclick()`. + +Option | Default | Description +--- | --- | --- +`log` | `true` | {% usage_options log %} +`force` | `false` | {% usage_options force rightclick %} +`multiple` | `false` | {% usage_options multiple rightclick %} +`timeout` | {% url `defaultCommandTimeout` configuration#Timeouts %} | {% usage_options timeout .rightclick %} + +## Yields {% helper_icon yields %} + +{% yields same_subject .rightclick %} + +# Examples + +## No Args + +### Right click the menu + +```javascript +cy.get('#open-menu').rightclick() +``` + +## Position + +### Specify a corner of the element to right click + +Right click the top right corner of the DOM element. + +```javascript +cy.get('#open-menu').rightclick('topRight') +``` + +## Coordinates + +### Specify explicit coordinates relative to the top left corner + +The right click below will be issued inside of the element (15px from the left and 40px from the top). + +```javascript +cy.get('#open-menu').rightclick(15, 40) +``` + +## Options + +### Force a right click regardless of its actionable state + +Forcing a right click overrides the {% url 'actionable checks' interacting-with-elements#Forcing %} Cypress applies and will automatically fire the events. + +```javascript +cy.get('#open-menu').rightclick({ force: true }) +``` + +### Force a right click with position argument + +```javascript +cy.get('#open-menu').rightclick('bottomLeft', { force: true }) +``` + +### Force a right click with relative coordinates + +```javascript +cy.get('#open-menu').rightclick(5, 60, { force: true }) +``` + +### Right click all buttons found on the page + +By default, Cypress will error if you're trying to right click multiple elements. By passing `{ multiple: true }` Cypress will iteratively apply the right click to each element and will also log to the {% url 'Command Log' test-runner#Command-Log %} multiple times. + +```javascript +cy.get('.open-menu').rightclick({ multiple: true }) +``` + +## Right click with key combinations + +The `.rightclick()` command may also be fired with key modifiers in combination with the {% url "`.type()`" type %} command in order to simulate character sequences while right clicking, such as `ALT + rightclick`. 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 `.rightclick()`. + +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. + +### Command right click + +```js +// execute a CMD + right click on the .menu-item +// { release: false } is necessary so that +// CMD will not be released after the type command +cy.get('body').type('{cmd}', { release: false }) +cy.get('.menu-item').rightclick() +``` + +# Notes + +## Actionability + +### The element must first reach actionability + +`.rightclick()` is an "action command" that follows all the rules {% url 'defined here' interacting-with-elements %}. + +# Rules + +## Requirements {% helper_icon requirements %} + +{% requirements dom .rightclick %} + +## Assertions {% helper_icon assertions %} + +{% assertions actions .rightclick %} + +## Timeouts {% helper_icon timeout %} + +{% timeouts actions .rightclick %} + +# Command Log + +***Right click the button in the form that has text "Create User"*** + +```javascript +cy.get('form').find('button').contains('Create User').rightclick() +``` + +The commands above will display in the Command Log as: + +{% imgTag /img/api/rightclick/rightclick-dom-element-in-command-log.png "Command log for right click" %} + +When clicking on `rightclick` within the command log, the console outputs the following: + +{% imgTag /img/api/rightclick/rightclick-console-log-with-mouse-events.png "console.log for right click" %} + +{% history %} +{% url "3.5.0" changelog#3-5-0 %} | `.rightclick()` command added +{% endhistory %} + +# See also + +- {% url `.click()` click %} +- {% url `.dblclick()` dblclick %} +- {% url `.trigger()` trigger %} diff --git a/source/api/commands/trigger.md b/source/api/commands/trigger.md index b49a75d27d..1d235ee076 100644 --- a/source/api/commands/trigger.md +++ b/source/api/commands/trigger.md @@ -236,6 +236,7 @@ When clicking on `trigger` within the command log, the console outputs the follo - {% url `.check()` check %} - {% url `.click()` click %} - {% url `.focus()` focus %} +- {% url `.rightclick()` rightclick %} - {% url `.select()` select %} - {% url `.submit()` submit %} - {% url `.type()` type %} diff --git a/source/guides/core-concepts/interacting-with-elements.md b/source/guides/core-concepts/interacting-with-elements.md index cc464204b4..f403a22ff0 100644 --- a/source/guides/core-concepts/interacting-with-elements.md +++ b/source/guides/core-concepts/interacting-with-elements.md @@ -17,6 +17,7 @@ Some commands in Cypress are for interacting with the DOM such as: - {% url `.click()` click %} - {% url `.dblclick()` dblclick %} +- {% url `.rightclick()` rightclick %} - {% url `.type()` type %} - {% url `.clear()` clear %} - {% url `.check()` check %} diff --git a/source/guides/core-concepts/introduction-to-cypress.md b/source/guides/core-concepts/introduction-to-cypress.md index b694514df0..e46da668a4 100644 --- a/source/guides/core-concepts/introduction-to-cypress.md +++ b/source/guides/core-concepts/introduction-to-cypress.md @@ -237,6 +237,7 @@ Here are even more action commands Cypress provides to interact with your app: - {% url `.uncheck()` uncheck %} - Uncheck checkbox(es). - {% url `.select()` select %} - Select an `