The Browser Type (v6 and above)
Botfather features an embedded Chromium based webbrowser that can be automated. Starting with Botfather version 6, multiple browsers can be automated simultaneously. Browsers run “headless” in the background by default. However, they can be inspected und controlled by users via browser windows.
Botfather browsers can be used to automate many things such as loading websites, executing Javascript, sending click, scroll and keyboard events. Furthermore, browsers can take screenshots which then can be saved our analyzed using the Vision API.
Table of contents
- Table of contents
- Create browsers and load websites
- Reload websites
- Stop loading websites
- Go back and forward
- Resize a browser
- Query basic browser information
- Take screenshots of websites
- Move the mouse and click
- Hold and release the mouse
- Scroll the mouse wheel
- Press keyboard keys and enter text
- Execute Javascript
- Evaluate Javascript (experimental)
- Manipulate or block responses
- Setting a custom user agent
Create browsers and load websites
var browser1 = new Browser("Browser Name 1");
var browser2 = new Browser("Browser Name 2", new Size(1200, 600));
browser1.loadUrl("https://google.com/");
browser2.loadUrl("https://youtube.com/");
browser1.finishLoading(); // (default) waits max 30 seconds for the website to load
browser2.finishLoading(10); // waits max 10 seconds for the website to load
Reload websites
var browser = new Browser("Test Browser");
browser.loadUrl("https://example.com");
// Reload the browser
browser.reload();
// Reload the browser ignoring the cache
browser.reloadIgnoringCache();
Stop loading websites
var browser = new Browser("Test Browser");
browser.loadUrl("https://example.com/");
if (browser.isLoading()) {
browser.stopLoading();
}
Go back and forward
if (browser.canGoBack()) {
browser.goBack();
}
if (browser.canGoForward()) {
browser.goForward();
}
Resize a browser
var new_size = new Size(1000, 600);
browser.resize(new_size);
Query basic browser information
The .getRect()
method return a Rect object, the .getSize()
method a Size object and the .getUrl()
method a Url object.
if (browser.isLoading()) {
// e.g. wait
}
var rect = browser.getRect();
var size = browser.getSize();
var url = browser.getUrl();
// A browsers Rect is usefull to get it's center Point
var center = rect.getCenter();
Take screenshots of websites
The .takeScreenshot()
method returns an Image object which can be saved or used with the Vision API.
var image = browser.takeScreenshot();
image.save('image.png');
Move the mouse and click
// Move the mouse to the center of the browser
browser.moveMouse(browser.rect.center);
// Click directly somewhere
var a_point = new Point(100, 100);
browser.leftClick(a_point);
browser.middleClick(a_point)
browser.rightClick(a_point);
Hold and release the mouse
Holding a releasing is usefull for controlling games or performing a drag an drop.
var a_point = new Point(100, 100);
browser.holdLeft(a_point);
browser.releaseLeft(a_point);
browser.holdMiddle(a_point);
browser.releaseMiddle(a_point);
browser.holdRight(a_point);
browser.releaseRight(a_point);
Scroll the mouse wheel
var location = new Point(200, 200);
var pixels_horizontally = 0;
var pixels_vertically = 50;
browser.scrollWHeel(location, pixels_horizontally, pixels_vertically);
Press keyboard keys and enter text
var browser = new Browser("Test Browser", new Size(1400, 700));
browser.loadUrl("https://keyboardtester.co/keyboard-tester.html");
browser.holdKey("Ctrl");
browser.enterText("Holding Ctrl has no effect here but it works!");
browser.releaseKey("Ctrl");
browser.pressKey("!");
Pressing modifier keys to enter special characters such as “!” or “@” is not required. Instead write browser.pressKey("!");
or browser.pressKey("@");
. The botfather browser will try its best to enter the character specified. Still you might want to press certain modifier keys if you’re e.g. testing a browser game. The same goes for other special keys.
Supported modifier keys and special keys:
- “Ctrl”
- “Alt”
- “Shift”
- “Meta”
- “Left”
- “Right”
- “Up”
- “Down”
- “Tab”
- “Escape”
- “Enter”
- “Backspace”
- “Delete”
Execute Javascript
Executes javascript_code in the browsers Javascript engine. This can be used to fill out login forms an sumit them. This method does not return anything.
var code = "document.body.style.background = red;";
browser.executeJavascript(code);
Evaluate Javascript (experimental)
Scripts can now evalute arbitrary Javascript code in a Browser an use the returned value.
var browser = new Browser("A Test Browser");
browser.loadUrl("google.com");
browser.finishLoading();
var title = browser.evaluateJavascript("document.title;");
Helper.log(title);
Everything except functions can be returned and used, even objects:
var browser = new Browser("Another test Browser");
browser.loadUrl("youtube.com");
browser.finishLoading();
var location = browser.evaluateJavascript("document.location;");
Helper.log(location.href);
The Javascript is evaluated in the browsers webhelper
process. In case something goes wrong the .evaluateJavascript
method has an optional timeout_in_ms
parameter. Its default value is 10000
milliseconds.
var browser = new Browser("Timeout Test");
try {
// Wait 5 seconds for the code to finish executing
browser.evaluateJavascript("while(true);", 5 * 1000);
} catch (e) {
Helper.log(e);
}
Beware: This is an experimental feature. At the point of writing evaluating document;
still crashes a browsers webhelper
process.
Manipulate or block responses
Most of the browsers resource modification methods take regular expressions as arguments.
// Prevent a resource from loading
browser.blockResource(".css");
// Replace a requested resource
browser.replaceResource(".png", "https://botfather.io/static/images/logo.png");
// Unmodify a single resource identified by the regular expression used before
browser.unmodifyResource(".css");
// Unmodify all modified resources for this browser
browser.unmodifyResources();
Setting a custom user agent
Setting a custom user agent is useful for testing websites or webapps which expect a specific user agent.
var browser = new Browser("Test");
// Set a custom user agent string
browser.setUserAgent("Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/81.0");
// Subsequent requests will use the custom user agent
browser.loadUrl("https://www.whatismybrowser.com/detect/what-is-my-user-agent");
One may change the user agent as many times as they wish. The user agent can also be resetted to Botfathers default. Botfathers default user agent is based on the its inbuilt Chromium browser.
// Reset to the default user agent
browser.resetUserAgent();