If you haven't already, read the README get an overview and examples of the concepts used in this page.
To use Queen, you'll need Node.js 0.8 or higher.
There are two distinct way Queen operates. As a HTTP server which captures browsers, and as a TCP server for applications to execute code on captured browsers. The second server is optional if you're only using Queen locally, but Queen is intended to be used as browser pool for your entire organization to execute code on.
The easiest way to test and play around with Queen is to start the Queen and run a script in one step
by executing something like queen your-script.js, and then connecting a browser. However, this is very inefficient because it means we have to start a new Queen Server for each script we want to run.
A more efficient way of using Queen is to start a stand-alone server whose sole purpose is to collect browsers and run scripts on them when asked to, and then we can establish a connection to this server to run our script. Here's how:
-
Execute:
queen -h localhost:9101 -c localhost:9200-
-h localhost:9101tells Queen to capture browsers at http://localhost:9101. If we didn't give queen this option, it would capture browsers at [your ip address]:80. Queen will log out to the console which host it's capturing browsers when it starts. -
-c localhost:9200tells Queen to listen for TCP connections at localhost:9200, this is where other applications can connect to in order to run scripts on the browsers Queen has captured. - Since we didn't provide a filename, Queen won't try to run a script, it's now just acting as a pure server. Also note that if there is a queenConfig.js file in the directory queen is started in, Queen will use those options to initialize itself.
-
-
Execute:
queen -r localhost:9101 http://queenjs.com/server-example.js-
-r localhost:9101tells Queen to run in "remote" mode and connect to a Queen server running at localhost:9101, which is the Queen Server we started in step 1. -
http://queenjs.com/server-example.jsis the queen script we want to execute. It will ask the Queen server to run http://queenjs.com/client-example.js on captured browsers, Queen will then establish socketed communication between the server-example.js script running on your machine and the client-example.js scripts running on the browsers, allowing the scripts to communicate with each other. You can open and read these scripts to find out more about how they work.
-
-
Point one or more browsers at http://localhost:9200
- This allows Queen to "capture the browsers". Once it has successfully captured the browser, Queen will be able to push scripts to the browser for it to run. Since we already have a pending job, it will automatically push it to this browser. You should start seeing outputs on your console now.
Queen weights in at around 18MB, not lightweight by JavaScript standards. Most of the "weight" in Queen, is the server portion, the one that captures browsers and lets other applications connect to it to run code on the captured browsers. If all were want to do is run scripts on an existing Queen server (like we did in step 2), we don't need all that weight.
queen-remote is a 250 KB package that allows you to connect to existing Queen servers to run your tests. Let's try the above example again, this time with queen-remote. You first need to install queen-remote by executing npm install queen-remote
- Execute:
queen -h localhost:9101 -c localhost:9200- This step remains the same as in the previous example.
- Execute:
queen-remote -h localhost:9101 http://queenjs.com/server-example.js-
-h localhost:9101tells Queen Remote to connect to the Queen Server hosted at localhost:9101, which is the Queen Server we started in step 1. -
http://queenjs.com/server-example.jsis the same file as from the previous example.
-
- Point one or more browsers at http://localhost:9200
- This step remains the same as in the previous example.
There! The same results, with a much lighter package. As you may have realized, the size saving doesn't matter if you're running Queen on the same machine as the Queen Server. However, Queen is designed to be used as an internal server, allowing anyone in the network to run scripts on it, so the savings becomes worth while if others in your organization want to quickly download queen-remote to run scripts on the server.
With a Queen server running, go to the [CAPTURE_URL]/monitor/. In the above examples, this would be http://localhost:9200/monitor/. You should see something like this:
The Queen Server can automatically populate itself with browsers (as in, start up browsers and point them at it self to capture them). It has three methods of doing so: through Selenium, BrowserStack, or Sauce Labs.
The best way to learn about automatic population is to run through the examples. The best one to start with is the Selenium once, since you can run that directly on your machine.
Download the repo, and view the "how-to-run-this-example.txt" files in the following folders:
You can use Queen in three ways
Install queen by executing npm install -g queen in your command line.
Queen can be executed through the command line as queen [options] [filepath].
The only thing you cannot configure through the command line is populators, you'll need a
queenConfig.js file in order to define those.
When queen is started without a server-side script, it will act as a hub for remote clients to connect to and execute their server-side scripts. See the queen-remote project for more information on the remote client.
Queen can be require'd in to your project as a module, allowing you to run queen programatically,
or extend it to suit your needs.