Skip to content

Click and mouse functions#

Functions to click, move the mouse, press and drag, scroll with the wheel, and tap the page. The click functions use real mouse events and move the mouse to the element along a human-like path before clicking.

General notes:

  • Coordinates are in pixels within the visible part of the page, with the origin (0, 0) at the top-left corner.
  • The ClickBy* and ClickRandom* functions do not throw when a click misses. Instead they return an object with error and also write the error to the log. A return value of undefined means the element was found and clicked, not that the page has reacted; if you need to be sure, wait for the result with WaitForElmtBySelector or WaitForResponse. You do not need to call MoveMouseToElm* before clicking, because the click functions already move the mouse to the element. An element covered by another layer does not receive the click.
  • In a mobile session (IsMobile() returns true), the click functions send a tap instead of a mouse click: there is no mouse path beforehand and no hover, so a menu that opens only on hover will not open; tap the button that opens the menu instead. To drag in steps, use SendMouseDown, SendMouseMove and SendMouseUp: in a mobile session they act as touch and swipe.

ClickByClass#

Clicks the element whose class attribute contains the string className. This is a substring match, so "btn" matches both "btn-primary" and "submit-btn".

Syntax 
await ClickByClass(className, index=0, clickCount=1, frameSearch="", frameSearchType="");
Parameters
Name Description
className String that must appear in the element's class attribute, for example "skip-button".
index Which element to use when several match: a position counted from 0, or "random" to pick one at random. Default 0.
clickCount Number of clicks; 2 is a double-click. Default 1.
frameSearch Condition for finding the iframe that contains the element; leave it empty for the main frame. See Iframes, selectors and waiting.
frameSearchType How to match frameSearch: "src-starts", "src-ends", "src-equals", "src-contains", "src-regex" or "frame-path". Required when you use frameSearch: if you leave it empty, the function works on the main frame.
Returns

undefined when the click succeeds; {error, caller, args} when it fails, with the reason in error (caller is "ClickBySelector").

Examples 
1
2
3
4
5
6
7
8
// the first element whose class contains "skip-button"
await ClickByClass("skip-button");

// the 2nd element
await ClickByClass("skip-button", 1);

// a random matching element
await ClickByClass("skip-button", "random");

ClickByCoordinates#

Clicks a random point inside the rectangle (X1, Y1) - (X2, Y2) of the visible page area, with no element needed. The mouse moves along a curve from its current position to that point before clicking, so two calls with the same arguments do not hit the same pixel. To click one exact point, set X1 equal to X2 and Y1 equal to Y2.

Syntax 
await ClickByCoordinates(X1, Y1, X2, Y2, clickCount=1, modifiers=0, button="left");
Parameters
Name Description
X1 x coordinate of the top-left corner.
Y1 y coordinate of the top-left corner.
X2 x coordinate of the bottom-right corner.
Y2 y coordinate of the bottom-right corner.
clickCount Number of clicks; 2 is a double-click. Default 1.
modifiers Keys held down at the same time: add up the constants WITH_ALT, WITH_CTRL, WITH_COMMAND, WITH_SHIFT (see Key constants). Default 0.
button Mouse button: "left", "right" or "middle"; any other value is treated as "left". Default "left".

Coordinates X1, Y1, X2, Y2

Examples 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
// click a random point in the area (100, 100) - (200, 200)
await ClickByCoordinates(100, 100, 200, 200);

// double-click
await ClickByCoordinates(100, 100, 200, 200, 2);

// right-click
await ClickByCoordinates(100, 100, 200, 200, 1, 0, "right");

// hold Ctrl while clicking
await ClickByCoordinates(100, 100, 200, 200, 1, WITH_CTRL);

ClickByCustomJS#

Clicks the element picked by a piece of JavaScript. Use it when a selector or xpath is not enough (for example an element inside a shadow DOM, or a choice based on complex conditions). The function does not scroll to the element; if the element may be off screen, call scrollIntoView() inside jsCode.

Syntax 
await ClickByCustomJS(jsCode, clickCount=1, frameSearch="", frameSearchType="");
Parameters
Name Description
jsCode A JavaScript expression whose value is the element to click (not a block of statements with return). It also accepts a function that returns the element: the function runs directly in the page, which avoids quoting trouble, but it cannot use the macro's variables.
clickCount Number of clicks; 2 is a double-click. Default 1.
frameSearch Condition for finding the iframe that contains the element; leave it empty for the main frame. See Iframes, selectors and waiting.
frameSearchType How to match frameSearch: "src-starts", "src-ends", "src-equals", "src-contains", "src-regex" or "frame-path". Required when you use frameSearch: if you leave it empty, the function works on the main frame.
Returns

undefined when the click succeeds; {error, caller, args} when it fails, with the reason in error.

Examples 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
// the button whose text is exactly "Next"
await ClickByCustomJS(`Array.from(document.querySelectorAll("button")).find(b => b.innerText.trim() === "Next")`);

// the selector also matches a hidden copy: take only the element that has a real size
await ClickByCustomJS(`Array.from(document.querySelectorAll("input[name='btnK']")).find(e => e.offsetWidth * e.offsetHeight > 0)`);

// pass a function: scroll to the element before returning it
await ClickByCustomJS(() => {
    const el = document.querySelector("my-widget").shadowRoot.querySelector("button.buy");
    el.scrollIntoView({behavior: "instant", block: "center"});
    return el;
});

ClickById#

Clicks an element by its id. The function has no index, because an id is usually unique on the page.

Syntax 
await ClickById(id, clickCount=1, frameSearch="", frameSearchType="");
Parameters
Name Description
id The element's id, without the # sign. For an id that starts with a digit or contains special characters, use ClickBySelector("[id='...']").
clickCount Number of clicks; 2 is a double-click. Default 1.
frameSearch Condition for finding the iframe that contains the element; leave it empty for the main frame. See Iframes, selectors and waiting.
frameSearchType How to match frameSearch: "src-starts", "src-ends", "src-equals", "src-contains", "src-regex" or "frame-path". Required when you use frameSearch: if you leave it empty, the function works on the main frame.
Returns

undefined when the click succeeds; {error, caller, args} when it fails, with the reason in error (caller is "ClickBySelector").

Examples 
1
2
3
4
5
// click the element with id="load-more-button"
await ClickById("load-more-button");

// double-click the #editor element inside an iframe whose URL contains "9hits.com"
await ClickById("editor", 2, "9hits.com", "src-contains");

ClickByName#

Clicks the element whose name attribute exactly equals the given value. Often used for form buttons and fields.

Syntax 
await ClickByName(name, index=0, clickCount=1, frameSearch="", frameSearchType="");
Parameters
Name Description
name Value of the element's name attribute, for example "submit".
index Which element to use when several match: a position counted from 0, or "random" to pick one at random. Default 0.
clickCount Number of clicks; 2 is a double-click. Default 1.
frameSearch Condition for finding the iframe that contains the element; leave it empty for the main frame. See Iframes, selectors and waiting.
frameSearchType How to match frameSearch: "src-starts", "src-ends", "src-equals", "src-contains", "src-regex" or "frame-path". Required when you use frameSearch: if you leave it empty, the function works on the main frame.
Returns

undefined when the click succeeds; {error, caller, args} when it fails, with the reason in error (caller is "ClickBySelector").

Examples 
1
2
3
4
5
6
7
// click the element with name="submit" and check the result
const r = await ClickByName("submit");
if (r) Log("Click failed:", r.error);
// r = {error: "Target not found or not visible!", caller: "ClickBySelector", args: {...}}

// a random field with name="option"
await ClickByName("option", "random");

ClickBySelector#

Clicks the element that matches a CSS selector: it scrolls the element to the middle of the screen, then clicks a random point inside it. Hidden elements (display: none, visibility: hidden) are not counted. This is the most used click function.

Syntax 
await ClickBySelector(selector, index=0, clickCount=1, frameSearch="", frameSearchType="");
Parameters
Name Description
selector A CSS selector, for example "a[href*='9hits.com']".
index Which element to use when several match: a position counted from 0, or "random" to pick one at random. Default 0.
clickCount Number of clicks; 2 is a double-click. Default 1.
frameSearch Condition for finding the iframe that contains the element; leave it empty for the main frame. See Iframes, selectors and waiting.
frameSearchType How to match frameSearch: "src-starts", "src-ends", "src-equals", "src-contains", "src-regex" or "frame-path". Required when you use frameSearch: if you leave it empty, the function works on the main frame.
Returns

undefined when the click succeeds; {error, caller, args} when it fails, with the reason in error.

Examples 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
// click a link that contains 9hits.com
await ClickBySelector("a[href*='9hits.com']");

// the 2nd matching link (index counts from 0), or a random matching link
await ClickBySelector("a[href*='9hits.com']", 1);
await ClickBySelector("a[href*='9hits.com']", "random");

// double-click
await ClickBySelector("#item", 0, 2);

// the #submit button inside an iframe whose URL starts with https://9hits.com
await ClickBySelector("button#submit", 0, 1, "https://9hits.com", "src-starts");

// the #submit button inside an iframe whose URL is exactly https://9hits.com/contact.html
await ClickBySelector("button#submit", 0, 1, "https://9hits.com/contact.html", "src-equals");

// the #submit button inside an iframe whose URL ends with /contact.html
await ClickBySelector("button#submit", 0, 1, "/contact.html", "src-ends");

// the #submit button inside an iframe whose URL contains 9hits.com
await ClickBySelector("button#submit", 0, 1, "9hits.com", "src-contains");

// the #submit button inside an iframe whose URL matches the regex \d+hits\.com (in a JS string, type each \ twice)
await ClickBySelector("button#submit", 0, 1, "\\d+hits\\.com", "src-regex");

// the #submit button inside the first iframe of the page
await ClickBySelector("button#submit", 0, 1, "0", "frame-path");

// the #submit button inside the 2nd child iframe of the first iframe
await ClickBySelector("button#submit", 0, 1, "0>1", "frame-path");

// check the result
const r = await ClickBySelector("button.checkout");
if (r) Log("Click failed:", r.error);
// r = {error: "Target not found or not visible!", caller: "ClickBySelector", args: {...}}

Selector also matches a hidden copy

Some pages have two copies of the same element, one of them inside a hidden block. The click can then land on the hidden copy and fail. Use ClickByCustomJS to pick the element that has a real size.

ClickByTag#

Clicks an element by its tag name, for example "button", "a" or "iframe".

Syntax 
await ClickByTag(tag, index=0, clickCount=1, frameSearch="", frameSearchType="");
Parameters
Name Description
tag HTML tag name, for example "button".
index Which element to use when several match: a position counted from 0, or "random" to pick one at random. Default 0.
clickCount Number of clicks; 2 is a double-click. Default 1.
frameSearch Condition for finding the iframe that contains the element; leave it empty for the main frame. See Iframes, selectors and waiting.
frameSearchType How to match frameSearch: "src-starts", "src-ends", "src-equals", "src-contains", "src-regex" or "frame-path". Required when you use frameSearch: if you leave it empty, the function works on the main frame.
Returns

undefined when the click succeeds; {error, caller, args} when it fails, with the reason in error (caller is "ClickBySelector").

Examples 
1
2
3
4
5
6
7
8
// click the first iframe on the page
await ClickByTag("iframe");

// click the 2nd iframe
await ClickByTag("iframe", 1);

// double-click the first div tag
await ClickByTag("div", 0, 2);

ClickByXpath#

Clicks the first visible element that matches the xpath, after scrolling it to the middle of the screen. The function has no index: to pick another element, put its position in the xpath itself. You can build an xpath with GenerateXpath.

Syntax 
await ClickByXpath(xpath, clickCount=1, frameSearch="", frameSearchType="");
Parameters
Name Description
xpath XPath expression for the element, for example "//button[contains(text(),'Accept')]".
clickCount Number of clicks; 2 is a double-click. Default 1.
frameSearch Condition for finding the iframe that contains the element; leave it empty for the main frame. See Iframes, selectors and waiting.
frameSearchType How to match frameSearch: "src-starts", "src-ends", "src-equals", "src-contains", "src-regex" or "frame-path". Required when you use frameSearch: if you leave it empty, the function works on the main frame.
Returns

undefined when the click succeeds; {error, caller, args} when it fails, with the reason in error.

Examples 
1
2
3
4
5
6
7
8
// the button with the text "Accept"
await ClickByXpath("//button[contains(text(),'Accept')]");

// the 2nd link whose href contains 9hits.com: put the position in the xpath itself
await ClickByXpath("(//a[contains(@href,'9hits.com')])[2]");

// xpath built with GenerateXpath: a link whose href starts with https://9hits.com
await ClickByXpath(GenerateXpath("a", "href", "https://9hits.com%"));

Clicks a random visible link that points to another domain, same as ClickRandomLink("external").

Syntax 
await ClickRandomExternalLink(frameSearch="", frameSearchType="");
Parameters
Name Description
frameSearch Condition for finding the iframe that contains the link; leave it empty for the main frame. See Iframes, selectors and waiting.
frameSearchType How to match frameSearch: "src-starts", "src-ends", "src-equals", "src-contains", "src-regex" or "frame-path". Required when you use frameSearch: if you leave it empty, the function works on the main frame.
Returns

undefined when the click succeeds; {error, caller, args} when it fails, with the reason in error (caller is "ClickRandomLink").

Example 
1
2
3
// click an outbound link, then wait for the new page to finish loading
await ClickRandomExternalLink();
await WaitForLoading();

Clicks a random visible link that points to the same domain as the current page, same as ClickRandomLink("internal"). Often used to simulate a visitor moving on to another page of the same website.

Syntax 
await ClickRandomInternalLink(frameSearch="", frameSearchType="");
Parameters
Name Description
frameSearch Condition for finding the iframe that contains the link; leave it empty for the main frame. See Iframes, selectors and waiting.
frameSearchType How to match frameSearch: "src-starts", "src-ends", "src-equals", "src-contains", "src-regex" or "frame-path". Required when you use frameSearch: if you leave it empty, the function works on the main frame.
Returns

undefined when the click succeeds; {error, caller, args} when it fails, with the reason in error (caller is "ClickRandomLink").

Example 
1
2
3
// move on to another page of the same website
await ClickRandomInternalLink();
await WaitForLoading();

Clicks a random visible link on the page. Only links that have a real size and point to a web address count; javascript: and mailto: links and a tags without an href are skipped.

Syntax 
await ClickRandomLink(type="any", frameSearch="", frameSearchType="");
Parameters
Name Description
type Link type: "any" (all links), "internal" (same domain as the page) or "external" (another domain; a different subdomain also counts as different). Default "any".
frameSearch Condition for finding the iframe that contains the link; leave it empty for the main frame. See Iframes, selectors and waiting.
frameSearchType How to match frameSearch: "src-starts", "src-ends", "src-equals", "src-contains", "src-regex" or "frame-path". Required when you use frameSearch: if you leave it empty, the function works on the main frame.
Returns

undefined when the click succeeds; {error, caller, args} when it fails, with the reason in error.

Examples 
1
2
3
4
5
6
7
8
9
// any link
await ClickRandomLink();

// only links on the same domain; wait for the new page if the click succeeded
const r = await ClickRandomLink("internal");
if (!r) await WaitForLoading();

// only inside an iframe whose URL starts with https://9hits.com
await ClickRandomLink("any", "https://9hits.com", "src-starts");

DragMouse#

Drags the mouse: presses and holds the button at the start point, moves along a curve to the end point, then releases. Use it for sliders and other draggable elements. If a coordinate is missing or is not a number, the function does nothing.

Syntax 
await DragMouse(from, to, speed=0.5, button="left", modifiers=0);
Parameters
Name Description
from Point where the drag starts, as {X, Y} (upper case).
to Point where the drag drops, as {X, Y} (upper case).
speed Drag duration in seconds; the larger the number, the slower the drag. Any value that is not a positive number is treated as 0.5. Default 0.5.
button Mouse button held while dragging: "left", "right" or "middle". Default "left".
modifiers Keys held down at the same time: add up the constants WITH_ALT, WITH_CTRL, WITH_COMMAND, WITH_SHIFT (see Key constants). Default 0.
Examples 
1
2
3
4
5
6
7
// drag from (200, 300) to (600, 300) in 0.8 seconds
await DragMouse({X: 200, Y: 300}, {X: 600, Y: 300}, 0.8);

// drag the slider handle 300px to the right
const p = await GetElementPosBySelector(".slider-handle");
const y = (p.y1 + p.y2) / 2;
await DragMouse({X: (p.x1 + p.x2) / 2, Y: y}, {X: p.x2 + 300, Y: y});

HTML5 drag and drop

Many kinds of drag and drop on web pages (especially HTML5 drag and drop) do not respond to this action. Test it on the real page before you rely on it.

Drag in steps

DragMouse presses, drags and releases in a single call and cannot stop midway. To drag in steps and check the page before dragging further (a slider that differs every time, or in a mobile session), use SendMouseDown, SendMouseMove and SendMouseUp.

MoveMouse#

Moves the mouse between two points along a human-like curve, without pressing any button by default. The longer the path, the longer it takes. The mouse jumps to startPoint before it sets off, so you will usually want MoveMouseToArea or MoveMouseToElmBySelector instead: both continue from the current mouse position. Called between SendMouseDown and SendMouseUp, the whole path is a single drag with the button held.

Syntax 
await MoveMouse(startPoint, endPoint, modifiers=0, button="none");
Parameters
Name Description
startPoint Start point, as {X, Y} (upper case).
endPoint End point, as {X, Y} (upper case). If either point is missing, the function does nothing.
modifiers Keys held down at the same time: add up the constants WITH_ALT, WITH_CTRL, WITH_COMMAND, WITH_SHIFT (see Key constants). Default 0.
button Mouse button held while moving: "none" (no button held), "left", "right" or "middle". Default "none".
Example 
1
2
3
4
5
6
await WaitForLoading();
// move the mouse along the four sides of a square
await MoveMouse({X: 100, Y: 100}, {X: 400, Y: 100});
await MoveMouse({X: 400, Y: 100}, {X: 400, Y: 400});
await MoveMouse({X: 400, Y: 400}, {X: 100, Y: 400});
await MoveMouse({X: 100, Y: 400}, {X: 100, Y: 100});

MoveMouseToAnyWhere#

Moves the mouse from its current position to a random point in the visible page area, to simulate a mouse moving while idle. The function does not click, but the mouse may stop over a link or button and trigger a hover effect. Call it after the page has finished loading.

Syntax 
await MoveMouseToAnyWhere(modifiers=0, button="none");
Parameters
Name Description
modifiers Keys held down at the same time: add up the constants WITH_ALT, WITH_CTRL, WITH_COMMAND, WITH_SHIFT (see Key constants). Default 0.
button Mouse button held while moving: "none" (no button held), "left", "right" or "middle". Default "none".
Example 
1
2
3
4
5
6
await WaitForLoading();
// move the mouse a few times, with a random pause between moves
for (let i = 0; i < 3; i++) {
    await MoveMouseToAnyWhere();
    await Delay(500, 1500);
}

MoveMouseToArea#

Moves the mouse from its current position along a curve to a random point inside the given rectangle. This is the usual way to bring the mouse to an area without ever landing on the same pixel twice. All four coordinates must be numbers; otherwise the function writes an error to the log and does nothing. You do not need to call this function before the ClickBy* functions.

Syntax 
await MoveMouseToArea(X1, Y1, X2, Y2, modifiers=0, button="none");
Parameters
Name Description
X1 x coordinate of the top-left corner.
Y1 y coordinate of the top-left corner.
X2 x coordinate of the bottom-right corner.
Y2 y coordinate of the bottom-right corner.
modifiers Keys held down at the same time: add up the constants WITH_ALT, WITH_CTRL, WITH_COMMAND, WITH_SHIFT (see Key constants). Default 0.
button Mouse button held while moving: "none" (no button held), "left", "right" or "middle". Default "none".

Coordinates X1, Y1, X2, Y2

Examples 
1
2
3
4
5
6
// move the mouse into the area (0, 0) - (300, 300)
await MoveMouseToArea(0, 0, 300, 300);

// move the mouse into an element's box
const p = await GetElementPosBySelector("#target");
await MoveMouseToArea(p.x1, p.y1, p.x2, p.y2);

MoveMouseToElmByCustomJS#

Moves the mouse to the element picked by a piece of JavaScript (like the jsCode of ClickByCustomJS) without clicking, for example to open a menu that appears on hover. The function does not scroll to the element. If the element is not found, the function writes an error to the log and does nothing.

Syntax 
await MoveMouseToElmByCustomJS(jsCode, frameSearch="", frameSearchType="", modifiers=0, button="none");
Parameters
Name Description
jsCode A JavaScript expression whose value is the element to move the mouse to, or a function that returns the element, like the jsCode of ClickByCustomJS.
frameSearch Condition for finding the iframe that contains the element; leave it empty for the main frame. See Iframes, selectors and waiting.
frameSearchType How to match frameSearch: "src-starts", "src-ends", "src-equals", "src-contains", "src-regex" or "frame-path". Required when you use frameSearch: if you leave it empty, the function works on the main frame.
modifiers Keys held down at the same time: add up the constants WITH_ALT, WITH_CTRL, WITH_COMMAND, WITH_SHIFT (see Key constants). Default 0.
button Mouse button held while moving: "none" (no button held), "left", "right" or "middle". Default "none".
Examples 
1
2
3
4
5
6
7
8
9
// hover over the 3rd child of .carousel
await MoveMouseToElmByCustomJS("document.querySelector('.carousel').children[2]");

// pass a function that scrolls to the element before returning it
await MoveMouseToElmByCustomJS(() => {
    const el = document.querySelector("footer .social");
    el.scrollIntoView({behavior: "instant", block: "center"});
    return el;
});

MoveMouseToElmBySelector#

Scrolls the element that matches a CSS selector to the middle of the screen, then moves the mouse to it without clicking, usually to open a menu that appears on hover. The parameter order differs from ClickBySelector: there is no clickCount. If the element is not found, the function writes an error to the log and does nothing.

Syntax 
await MoveMouseToElmBySelector(selector, index=0, frameSearch="", frameSearchType="", modifiers=0, button="none");
Parameters
Name Description
selector A CSS selector, for example "nav .menu-products".
index Which element to use when several match: a position counted from 0, or "random" to pick one at random. Default 0.
frameSearch Condition for finding the iframe that contains the element; leave it empty for the main frame. See Iframes, selectors and waiting.
frameSearchType How to match frameSearch: "src-starts", "src-ends", "src-equals", "src-contains", "src-regex" or "frame-path". Required when you use frameSearch: if you leave it empty, the function works on the main frame.
modifiers Keys held down at the same time: add up the constants WITH_ALT, WITH_CTRL, WITH_COMMAND, WITH_SHIFT (see Key constants). Default 0.
button Mouse button held while moving: "none" (no button held), "left", "right" or "middle". Default "none".
Examples 
1
2
3
4
5
6
7
8
// on https://google.com: move the mouse to the search box
await WaitForLoading();
await MoveMouseToElmBySelector('textarea[title="Search"]');

// hover over a menu to open its submenu, then click an item inside it
await MoveMouseToElmBySelector("nav .menu-products");
await Delay(500, 1000);
await ClickBySelector("nav .menu-products .submenu a", "random");

MoveMouseToElmByXpath#

Scrolls the first visible element that matches the xpath to the middle of the screen, then moves the mouse to it without clicking. If the element is not found, the function writes an error to the log and does nothing.

Syntax 
await MoveMouseToElmByXpath(xpath, frameSearch="", frameSearchType="", modifiers=0, button="none");
Parameters
Name Description
xpath XPath expression for the element. You can build it with GenerateXpath.
frameSearch Condition for finding the iframe that contains the element; leave it empty for the main frame. See Iframes, selectors and waiting.
frameSearchType How to match frameSearch: "src-starts", "src-ends", "src-equals", "src-contains", "src-regex" or "frame-path". Required when you use frameSearch: if you leave it empty, the function works on the main frame.
modifiers Keys held down at the same time: add up the constants WITH_ALT, WITH_CTRL, WITH_COMMAND, WITH_SHIFT (see Key constants). Default 0.
button Mouse button held while moving: "none" (no button held), "left", "right" or "middle". Default "none".
Examples 
1
2
3
4
5
// move the mouse to the button with id="submit"
await MoveMouseToElmByXpath("//button[@id='submit']");

// xpath built with GenerateXpath: a link whose href contains 9hits.com
await MoveMouseToElmByXpath(GenerateXpath("a", "href", "%9hits.com%"));

SendMouseClick#

Presses and releases the mouse right at coordinates x, y of the page area, without moving the mouse there first. For a human-like path to that point, use ClickByCoordinates. In a mobile session, the command is sent as a tap.

Syntax 
await SendMouseClick(x, y, button="left", repeat=1, modifiers=0);
Parameters
Name Description
x x coordinate of the click point. A negative or non-numeric value is treated as 0.
y y coordinate of the click point. A negative or non-numeric value is treated as 0.
button Mouse button: "left", "right" or "middle"; any other value is treated as "left". Default "left".
repeat Number of clicks; 2 is a double-click. Default 1.
modifiers Keys held down at the same time: add up the constants WITH_ALT, WITH_CTRL, WITH_COMMAND, WITH_SHIFT (see Key constants). Default 0.
Examples 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
// left-click at (100, 150)
await SendMouseClick(100, 150);

// right-click
await SendMouseClick(100, 150, "right");

// double-click
await SendMouseClick(100, 150, "left", 2);

// hold Ctrl while clicking
await SendMouseClick(100, 150, "left", 1, WITH_CTRL);

SendMouseDown#

Presses and holds a mouse button at coordinates x, y until you call SendMouseUp. While the button is held, SendMouseMove and MoveMouse move the mouse with the button down, so the page receives a drag. Use it when you need to drag in steps and check the page along the way, for example a slider that differs every time. In a mobile session, the function puts a finger on the screen.

Syntax 
await SendMouseDown(x, y, button="left", modifiers=0);
Parameters
Name Description
x x coordinate of the press point. A negative or non-numeric value is treated as 0.
y y coordinate of the press point. A negative or non-numeric value is treated as 0.
button Mouse button: "left", "right" or "middle"; any other value is treated as "left". Has no effect in a mobile session. Default "left".
modifiers Keys held down at the same time: add up the constants WITH_ALT, WITH_CTRL, WITH_COMMAND, WITH_SHIFT (see Key constants). Default 0.
Returns

undefined when the button was pressed; {error, caller, args} when a button is already held and not yet released, or when the press failed.

Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
// drag the slider handle to the right in small steps, stop when the page reports a match
const p = await GetElementPosBySelector(".slider-handle");
const y = (p.y1 + p.y2) / 2;
let x = (p.x1 + p.x2) / 2;
await MoveMouseToElmBySelector(".slider-handle");
await SendMouseDown(x, y);
for (let i = 0; i < 40; i++) {
    x += RandomInt(6, 12);
    await SendMouseMove(x, y + RandomInt(-2, 2));
    await Delay(30, 60);
    const done = await EvalScript("document.querySelector('.slider-ok') !== null");
    if (done.result) break;
}
await SendMouseUp();

Warning

Always call SendMouseUp after SendMouseDown. The button stays held, even across macro runs, until it is released, and the next SendMouseDown is rejected until then. The function presses right at the given point without moving the mouse there first; for a human-like path, call MoveMouseToElmBySelector or MoveMouse first, as in the example.

SendMouseMove#

Makes the pointer jump straight to coordinates x, y, with no path. For human-like mouse movement, use MoveMouse, MoveMouseToArea or the click functions. The new position is remembered; later mouse movement functions and SendMouseWheel continue from there.

Syntax 
await SendMouseMove(x, y, modifiers=0, button="none");
Parameters
Name Description
x x coordinate of the target point. A negative or non-numeric value is treated as 0.
y y coordinate of the target point. A negative or non-numeric value is treated as 0.
modifiers Keys held down at the same time: add up the constants WITH_ALT, WITH_CTRL, WITH_COMMAND, WITH_SHIFT (see Key constants). Default 0.
button Mouse button held while moving: "none" (no button held), "left", "right" or "middle". Default "none".
Example 
1
2
3
// put the mouse in the middle of the box you want to scroll, then scroll down
await SendMouseMove(400, 300);
await SendMouseWheel(0, -120);

Note

Called between SendMouseDown and SendMouseUp, the mouse moves with the button held and the page receives a drag; in a mobile session, a finger moves across the screen.

SendMouseUp#

Releases the mouse button held by SendMouseDown. In a mobile session, it lifts the finger.

Syntax 
await SendMouseUp(x=-1, y=-1, modifiers=0);
Parameters
Name Description
x x coordinate of the release point. Leave it empty or pass a negative number to use the current mouse position. Default -1.
y y coordinate of the release point. Leave it empty or pass a negative number to use the current mouse position. Default -1.
modifiers Keys held down at the same time: add up the constants WITH_ALT, WITH_CTRL, WITH_COMMAND, WITH_SHIFT (see Key constants). Default 0.
Returns

undefined when the button was released; {error, caller, args} when it could not be released.

Example 
1
2
3
4
// press at (200, 300), drag to (480, 300) along a human-like path, then release
await SendMouseDown(200, 300);
await MoveMouse({X: 200, Y: 300}, {X: 480, Y: 300});
await SendMouseUp(480, 300);

Note

The function releases the same button that SendMouseDown pressed. If no button is held, the function just releases the left button once, which has no side effects.

SendMouseWheel#

Turns the mouse wheel once at the current mouse position, so move the mouse into the area you want to scroll first. The sign of the scroll amount is the opposite of the usual browser convention: a negative deltaY scrolls down and a positive one scrolls up. If you only need to scroll the page, ScrollTo is more predictable; this function is for pages that listen for real wheel events.

Syntax 
await SendMouseWheel(deltaX, deltaY, modifiers=0, button="left");
Parameters
Name Description
deltaX Horizontal scroll amount in pixels: negative scrolls right, positive scrolls left, 0 means no horizontal scroll.
deltaY Vertical scroll amount in pixels: negative scrolls down, positive scrolls up.
modifiers Keys held down at the same time: add up the constants WITH_ALT, WITH_CTRL, WITH_COMMAND, WITH_SHIFT (see Key constants). Default 0.
button Mouse button sent with the scroll: "left", "right", "middle" or "none". Default "left"; you rarely need to change it.
Examples 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
// move the mouse into the area you want to scroll
await MoveMouseToArea(300, 300, 500, 400);

// scroll down 120px, wait 3 seconds, then scroll back up
await SendMouseWheel(0, -120);
await Delay(3000);
await SendMouseWheel(0, 120);

// scroll right 200px
await SendMouseWheel(-200, 0);

SendTouch#

Touches the screen at one or more points at the same time, one finger per point. The function only touches and lifts; it cannot swipe or drag. Use it when the session emulates a touch (mobile) device.

Syntax 
await SendTouch(points, repeat=1, modifiers=0);
Parameters
Name Description
points Array of touch points {x, y} (lower case), one finger per point. Passing upper-case {X, Y} touches the (0, 0) corner.
repeat Number of taps; 2 is a double tap. Any value that is not a positive number is treated as 1. Default 1.
modifiers Keys held down at the same time: add up the constants WITH_ALT, WITH_CTRL, WITH_COMMAND, WITH_SHIFT (see Key constants). Default 0.
Examples 
1
2
3
4
5
6
7
8
// tap with one finger at (200, 400)
await SendTouch([{x: 200, y: 400}]);

// double tap
await SendTouch([{x: 200, y: 400}], 2);

// tap with two fingers at once
await SendTouch([{x: 150, y: 400}, {x: 250, y: 400}]);