.rightclick command (#2174)

* Add rightclick doc

* Update the contributing docs to be clearer about how to add a new doc (with new auto-generation for translations)

* Update source/api/commands/rightclick.md

Co-Authored-By: Ben Kucera <[email protected]>

* Update id of DOM element to open content menu to make more sense

* Add some more places where rightclick should be mentioned

Author: jennifer-shehane

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/<language>/.../file.md` and this file will not be overwritten by the English file.
 
 ## Committing Code

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

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 %}

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 %}

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 %}

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 %}

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 %}

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 `<option>` within a `<select>`.
 - {% url `.dblclick()` dblclick %} - Double-click a DOM element.
+- {% url `.rightclick()` rightclick %} - Right-click a DOM element.
 
 These commands ensure {% url "some guarantees" interacting-with-elements %} about what the state of the elements should be prior to performing their actions.
 

themes/cypress/languages/en.yml

@@ -126,6 +126,7 @@ sidebar:
     readfile: readFile
     reload: reload
     request: request
+    rightclick: rightclick
     root: root
     route: route
     screenshot: screenshot

themes/cypress/languages/ja.yml

@@ -126,6 +126,7 @@ sidebar:
     readfile: readFile
     reload: reload
     request: request
+    rightclick: rightclick
     root: root
     route: route
     screenshot: screenshot