Product
Introducing SSO
Streamline your login process and enhance security by enabling Single Sign-On (SSO) on the Socket platform, now available for all customers on the Enterprise plan, supporting 20+ identity providers.
grimoire
Advanced tools
Readme
Grimoire is a library that extends Phantom.js for development of bots to automate website usage. Major additions to Phantom include:
Rock-Solid DOM Interaction - A lot of automating website usage is waiting for the DOM to reflect a state, sending mouse/keyboard events to DOM elements. Grimoire adds a robust getSelector
method that is used to retrieve structured data from the DOM, test for DOM states (or the negation of states), and reliably identify element viewport locations for mouse / keyboard actions.
Event Emitter - Grimoire adds Node.js-style event emitter functionality. Phantom allows for the assignment of single handlers to events on a webpage (i.e. onPageResourceRequested
, onLoadError
). Grimore extends this by allowing the assignment of multiple handlers to these events.
Web Server API - Phantom ships with a barebones web server module. Grimoire extends this into an RPC API, allowing easy interprocess driven browser sessions, turning Phantom scripts into server daemons, with the ability to webdrive multiple automation sessions in the same process.
Visual Debugging - Grimoire adds ability to inspect an active browser session at any time, both with a full data dump of state and a visual rendering of the viewport.
DOM Action Helpers - utility methods for clicking on elements, and setting values on a page.
Grimoire is an external JS file that needs to be loaded into a Phantomjs context with the injectJS
method. It depends on loading several native Phantom modules and third-party JS libraries. Here is an example setup. For now, it's probably easiest just to include this at the top of your Phantom scripts using Grimoire, and suggestions for better design are welcome:
var Webpage = require('webpage')
, System = require('system')
, Phantom = phantom
, CP = require('child_process')
, FS = require('fs')
, Server = require('webserver')
;
Phantom.injectJs('../node_modules/underscore/underscore-min.js');
Phantom.injectJs('../node_modules/async/dist/async.min.js');
Phantom.injectJs('../node_modules/jsbelt/lib/belt.js');
Phantom.injectJs('../node_modules/moment/min/moment.min.js');
var M = {}
, Async = async
, Moment = moment;
Phantom.injectJs('../node_modules/grimoire/grimoire.js');
M = Grimoire.call(M);
Note that this script uses NPM to manage dependencies. Bower or no dependency manager would be fine as well. After this setup code, add any script-specific code.
M
basically represents a singleton instance of the module. It has inherited all the extensions Grimoire provides.
createPage(options) - create a new Phantom page (essentially a new session). The page will include a uuid
property which can be passed to the web server to retrieve this specific page/session at any point.
Options:
UserAgents
{'width': 2048, 'height': 16000}
.Returns new page that was created
loadURL(options, callback(error, page)) - load a URL for a page, optionally waiting until all resources have loaded before invoking a callback Options:
getSelector(options, callback(error, result)) - find element or elements in the DOM, meeting different criteria and pass them to callback, or timeout if no such elements are found and pass error to callback. Options:
innerText
that matches content
, where content is a string, or stringified regexgetBoundingClientRect
method, and will not work with this option.)count
number of elements are found to match criteriax
, y
, width
, and height
of bounding rectangeinnerText
of elementouterHtml
of elementfilter
, this function is executed in the browser's Javascript contextinspectPage(options, callback) - debugging method used to visually inspect a page and log all page information, optionally pausing script execution Options
image_path
at from functionelementClick(options, callback) - click on an element on the page. This method should be passed an element
object from the getSelector
method.
Options
getSelector
method, must have a rect
property that conveys the bounding rectangle
x_offset
shifts the x-coordinate of the specific point clickedy_offset
shifts the y-coordinate of the specific point clickedelementClickCheckbox(options, callback) - click on a checkbox element on the page. Checkboxes are a little tricky as they do not have dimensions in the getBoundingClientRect
method. This method should be passed an element
object from the getSelector
method, which is usually the immediate parent of the checkbox DOM element itself.
Options
getSelector
method, must have a rect
property that conveys the bounding rectangle
x_offset
shifts the x-coordinate of the specific point clickedy_offset
shifts the y-coordinate of the specific point clickedelementEnterText(options, callback) - enter text into an element
elementSelectOption(options, callback) - choose option in select list
startServer(options, callback) - start a webserver for this script, which provides an RPC API for invoking script methods via HTTP request.
Options
Usage
The webserver method converts standalone scripts into modules capable of robust interprocess communication. To execute a method in the script remotely, make a request to /method?method=name-of-method&other_args=....
. For example, if the script includes a method called clickRow
which requires an index
argument to specify the row, requesting /method?method=clickRow&index=5
will execute the clickRow
method on the row with index
5.
Web requests will return a JSON object which includes an error
key (including the message if any error occurred, and a data
key, containing the results of the method. The data
object will include page_uuid
with a unique identifier for the page created or used with the given method execution. In future requests, this same UUID can be passed as page=[uuid]
to retrieve an existing page in executing a given method. In this way, the webserver allows for session-style design patterns, where multiple methods can be executed over time on the same page, with multiple pages being managed by the same script at once.
Additionally, responses will include an inspect_url
parameters, with a URL to inspect a specified page visually. When this endpoint is requested, an image is created with the specified page and returned as the response. This is useful in debugging script behavior.
main(options) - this method is called at the end of the script file to parse commandline arguments passed to the script and call methods at load. This method reads in command line arguments and parses matching the pattern --key=value
. Passing an argument with the name of another method in the script will cause this method to be executed, passing in any command line arguments as options. For example, a command line call of:
phantomjs somescript.js --startServer --port=5555 --host="http://localhost" --something=else
will execute the startServer
method, passing in the following arguments (note: all command line arguments are passed as string values):
{
'port': '5555'
, 'host': 'http://localhost'
, 'something': 'else'
}
FAQs
framework for phantomjs
The npm package grimoire receives a total of 4 weekly downloads. As such, grimoire popularity was classified as not popular.
We found that grimoire demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Streamline your login process and enhance security by enabling Single Sign-On (SSO) on the Socket platform, now available for all customers on the Enterprise plan, supporting 20+ identity providers.
Security News
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
Security News
As cyber threats become more autonomous, AI-powered defenses are crucial for businesses to stay ahead of attackers who can exploit software vulnerabilities at scale.