automatonic
v0.1.1
Published
Browser automation as an electron library
Downloads
13
Readme
Automatonic
automatonic is a library that, for now, is meant to be used within an Electron app for browser automation. Electron provides pretty good APIs for doing automation, but they're not particularly convenient for things like automated testing. There are things like Nightmare.js the provide an abstraction on top of Electron, and this is largely inspired by those.
Why not just use Nightmare.js?
Reasons. Here are a few:
- The page I was trying to test would cause Nightmare.js to freeze, but the same test when run manually in Electron or PhantomJS worked fine.
- You can't use Nightmare.js from within an Electron app.
- You can't test multi-session interaction (multiple browsers, like chat) because you only get access to one BrowserWindow.
API
All of the API methods return a Promise, and all of them use an internal queue to make sure actions run in the correct order. As this is still in a proof-of-concept phase, the API is fairly limited. At some point, there may be an API to use directly from node that spins up a child process with Electron and proxies back and forth like Nightmare.js.
Browser
constructor([options object]) or
Browser.new([options object])
The options object is passed straight through to Electron's
BrowserWindow
. If not specified,webPreferences.nodeIntegration
is set tofalse
because it can interfere with module loaders and has the tiny risk of having a third party script completely own your machine.The automatonic specific options are:
- pollInterval: number of milliseconds between element checks when waiting for an element to appear. Default is 200.
- typingInterval: number of milliseconds between characters when typing into an input. Default is 50.
- exposeElectronAs:
string
variable name to expose the electron module to the page e.g.window.${exposeElectronAs} = require('electron')
. This is implemented with a preload script, so it works even ifnodeIntegration
is disabled (the default). - preloadScript:
string
of extra script that gets added to any generated preload script to be handed to electron.
Any generated preload scripts are created as temporary files that are cleaned up when the main process exits.
Properties
- browser
The
BrowserWindow
instance belonging to thisBrowser
.
Methods
goto(url[, options object])
Navigate to the given
url
. Any options are passed directly toBrowserWindow.loadURL
, and the returned Promise resolves when the page load is complete.execute(function[, ...args])
Execute the given function in the browser by
toString()
ing it,JSON.stringify
ing the arguments, shipping them to the render instance, wrapping everything up in a Promise, and returning the result.click(selector[, options object])
Find an element with the given selector and trigger
mouseover
,mousedown
,click
, andmouseup
events. This will wait up to 1s (default, change with thetimeout
option) for the element to appear.type(selector, string[, options object])
Find an element with the given selector, focus it, and then pass each character from the string into the target element. Each character will trigger
keydown
,keypress
, update the value,input
, andkeyup
. Once all of the characters are added, achange
event will be triggered. This will wait up to 1s (default, change with thetimeout
option) for the element to appear. Specifyingappend: true
will not empty the target input before sending characters.waitFor(selector, timeout = 5000)
Wait up to
timeout
milliseconds for an element matchingselector
to appear on the page.waitFor(timeout = 1000)
Wait for
timeout
milliseconds before continuing.checkFor(selector)
Immediately check to see if an element matching
selector
exists.checkForText(string)
Immediately check to see if
string
exists in the page HTML. Ifstring
is a RegExp, then itstest
method will be used to determine whether or not there is a match.checkpoint()
Sets a checkpoint in the queue. If any step before the checkpoint fails, everything between the checkpoint and the failure will be removed from the queue. The Promise returned will resolve when all of the steps before the checkpoint have resolved.
close()
Closes and disposes of the Browser.
Utility methods
run(generator)
This is basically a copy of co that only allows
yield
ing Promises. This is particularly useful for allowing easy branching within an automation. This returns a Promise that resolves when the generator has nothing left toyield
.sleep(milliseconds)
Returns a Promise that resolves after
milliseconds
ms have elapsed.
Usage
const { Browser, run, sleep } = require('automatonic');
run(function*() {
const I = new Browser();
I.goto('https://google.com');
// let's give 'em a second to settle
yield sleep(1000);
// do a search
I.type('#lst-ib', 'automatonic\n');
I.click('button[name=btnG]');
// wait for a result and grab its title
I.wait('h3.r a');
const first = yield I.execute(function() {
return document.querySelector('h3.r a').innerText;
});
if (~first.toLowerCase().indexOf('wikipedia')) {
console.log("hey look, it's a Wikipedia link");
} else {
console.log("it's not a Wikipedia link, let's click it");
I.click('h3.r a');
}
yield sleep(20000);
I.close();
}).then(null, err => {
console.error('OH NOES!', err);
});