Docs: Improving clickWithLeftButton()

ThomasLandauer · web-flow · commit da15bf779523 · 2026-03-26T13:15:28.000+01:00
Page: https://codeception.com/docs/modules/WebDriver#clickWithLeftButton
diff --git a/src/Codeception/Module/WebDriver.php b/src/Codeception/Module/WebDriver.php
@@ -2952,7 +2952,7 @@ public function dragAndDrop($source, $target): void
      * then the mouse is moved to an offset of the element's top-left corner.
      * Otherwise, the mouse is moved to the center of the element.
      *
-     * ``` php
+     * ```php
      * <?php
      * $I->moveMouseOver(['css' => '.checkout']);
      * $I->moveMouseOver(null, 20, 50);
@@ -2974,21 +2974,21 @@ public function moveMouseOver($cssOrXPath = null, ?int $offsetX = null, ?int $of
     }
 
     /**
-     * Performs click with the left mouse button on an element.
-     * If the first parameter `null` then the offset is relative to the actual mouse position.
-     * If the second and third parameters are given,
-     * then the mouse is moved to an offset of the element's top-left corner.
-     * Otherwise, the mouse is moved to the center of the element.
+     * Performs a click with the left mouse button.
+     * If the first parameter is given, then the offset is measured from the center of that element.
+     * If the first parameter is `null`, then the offset is relative to the actual mouse position.
+     * To debug, you can use `clickWithRightButton()` and see where the context menu is located.
      *
-     * ``` php
+     * ```php
      * <?php
      * $I->clickWithLeftButton(['css' => '.checkout']);
      * $I->clickWithLeftButton(null, 20, 50);
      * $I->clickWithLeftButton(['css' => '.checkout'], 20, 50);
      * ```
      *
-     * @param null|string|array|WebDriverBy $cssOrXPath css or xpath of the web element (body by default).
-     *
+     * @param null|string|array|WebDriverBy $cssOrXPath css or xpath of the web element (default: `<body>`).
+     * @param ?int $offsetX Positive number moves to the right
+     * @param ?int $offsetY Positive number moves downwards
      * @throws ElementNotFound
      */
     public function clickWithLeftButton($cssOrXPath = null, ?int $offsetX = null, ?int $offsetY = null): void
@@ -2998,18 +2998,7 @@ public function clickWithLeftButton($cssOrXPath = null, ?int $offsetX = null, ?i
     }
 
     /**
-     * Performs contextual click with the right mouse button on an element.
-     * If the first parameter `null` then the offset is relative to the actual mouse position.
-     * If the second and third parameters are given,
-     * then the mouse is moved to an offset of the element's top-left corner.
-     * Otherwise, the mouse is moved to the center of the element.
-     *
-     * ``` php
-     * <?php
-     * $I->clickWithRightButton(['css' => '.checkout']);
-     * $I->clickWithRightButton(null, 20, 50);
-     * $I->clickWithRightButton(['css' => '.checkout'], 20, 50);
-     * ```
+     * See <a href="#clickWithLeftButton">clickWithLeftButton()</a>
      *
      * @param null|string|array|WebDriverBy $cssOrXPath css or xpath of the web element (body by default).
      * @throws ElementNotFound
@@ -3020,7 +3009,6 @@ public function clickWithRightButton($cssOrXPath = null, ?int $offsetX = null, ?
         $this->webDriver->getMouse()->contextClick();
     }
 
-
     /**
      * Performs a double click on an element matched by CSS or XPath.
      *
