Permalink
Browse files

Initial commit of screening

  • Loading branch information...
0 parents commit eb0e7c53c76a0bc99bdf125a487eab23e3ed747c Pierre Frisch committed with zacharyc Dec 22, 2011
Showing 303 changed files with 69,966 additions and 0 deletions.
@@ -0,0 +1,4 @@
+.DS_Store
+.idea/
+server/results.json
+server/node_modules
@@ -0,0 +1,3 @@
+[submodule "public/node_modules/montage"]
+ path = public/node_modules/montage
+ url = git@github.com:Motorola-Mobility/montage.git
0 README
No changes.
@@ -0,0 +1,76 @@
+<!-- <copyright>
+ This file contains proprietary software owned by Motorola Mobility, Inc.<br/>
+ No rights, expressed or implied, whatsoever to this software are provided by Motorola Mobility, Inc. hereunder.<br/>
+ (c) Copyright 2011 Motorola Mobility, Inc. All Rights Reserved.
+ </copyright> -->
+
+# Agent communication
+
+Agents are entities which are able to remote control one or more browsers and this document
+describes the types of agents that are supported by Screening and how the communication
+between our server and the individual agents works.
+
+## AgentPool
+
+The AgentPool (`server/lib/agent-pool.js`) is our central place where we manage all the
+agents that are connected to our Screening server. It allows adding new agents, deleting
+agents, getting a list of agents or getting a reference to one specific agent.
+
+## iFrame Agent
+
+This Agent (`server/lib/socket-agent.js`) represents a client that connects itself
+through a websocket (using `socket.io`) to the server. On the client-side this agent needs
+to be opened manually by either clicking on `New agent` or opening the URL
+`http://HOST_OR_IP:8081/screening/agent/index.html`. Through this action a new URL is opened
+which itself connects via websocket to the server (notifies the AgentPool) and provides an
+iFrame which then can be remote controlled by the `socket.io` library on the server.
+
+Note: This agent is also used to record an interaction with an application.
+
+All the communication between external socket-clients and the server can be found in
+`server/lib/socket-agent.js`, `server/lib/sockets.js` and `server/lib/testcase-runner-iframe.js`.
+The `socket-agent.js` is the component which is responsible for providing functionality to
+change the state of the agent (connected, start/stop recording, start/stop test execution), the
+`sockets.js` is the part which connects agents/drivers to the Screening server and the
+`testcase-runner-iframe.js` is caring about sending individual commands to an agent (e.g.
+execute JavaScript, goto URL, ...).
+
+![Websocket Communication (Connection / Execution)](img/AgentCommunication_websocket.png)
+
+The diagram above illustates the webdriver communication between the server and the
+agent / control-room instances. It does not cover the recording events of the iFrame agent.
+
+For details how the server is executing a Testscript and sending individual commands to an
+iFrame agent see `TestScriptExecution.md`.
+
+## Webdriver Agent
+
+This agent (`server/lib/webdriver-agent.js`) is responsible for handling the connection
+between the server and a remote Webdriver instance. Our Screening server is able to communicate
+with a Webdriver server through a HTTP REST-API which is standardized in the
+[JSONWireProtocol](http://code.google.com/p/selenium/wiki/JsonWireProtocol/ "JSONWireProtocol").
+The big difference to the iFrame agent is, that we can connect a Webdriver by telling the Screening
+server the base URL of it (either through the Control-Room or via REST-API) and we
+are then able to remote-control as many browser instances this particular Webdriver can handle.
+
+`server/lib/testcase-runner-webdriver.js` is basically just the initializer for providing
+a connection to the Webdriver client library, which can be found in `server/lib/webdriver`. The
+Webdriver client library is a modified version of
+[Webdriver-JS](https://github.com/dmachi/webdriver-js "Webdriver-JS") and provides a complete
+client implementation of the Webdriver API as of 2011-09-19.
+
+In Screening we don't use the complete functionality of this library yet and it will be decided in
+the future if more parts of this library will be used.
+
+Details about concrete communication between our server and a Webdriver can be found in
+`server/lib/teststep-runner-webdriver.js`. There you'll see which parts of the Webdriver
+library are used and how the Screening JS-API maps to the Webdriver API.
+
+![Webdriver Communication Overview](img/AgentCommunication_websocket.png)
+
+In this diagram you see an overview how the Screening server is communicating to remote Webdriver instances and gives an overview of the architecture of Webdriver and its components.
+
+Further details about the Webdriver can be found on
+[Selenium Wiki](http://code.google.com/p/selenium/w/list "Selenium Wiki")
+
+The document `TestScriptExecution.md` is explaining in detail how a Testscipt is executed and how individual commands are sent to the `Webdriver-Teststep-Runner`.
@@ -0,0 +1,147 @@
+<!-- <copyright>
+ This file contains proprietary software owned by Motorola Mobility, Inc.<br/>
+ No rights, expressed or implied, whatsoever to this software are provided by Motorola Mobility, Inc. hereunder.<br/>
+ (c) Copyright 2011 Motorola Mobility, Inc. All Rights Reserved.
+ </copyright> -->
+
+# Screening
+
+Screening is a testing tool for Montaged-based applications.
+
+It runs as a Node.js web application and creates its own server.
+
+## Requirements
+
+Screening has a few requirements which must be met before you are able to install and use it.
+
+* Node.js - A JavaScript environment where the Screening server runs.
+* npm - The package manager for Node.js that is run through the command line and manages dependencies for an application.
+* MongoDB - The database used by the Screening server to store test scripts and results.
+
+## Installation
+
+The installation process varies slightly depending on the platform. As of now Screening only supports Ubuntu Linux and Mac OS X.
+
+The installation producedure for node and npm is different for Mac and Ubuntu Linux.
+
+### Install node and npm on Mac
+
+The easiest way is to download a package that includes both node and npm at:
+
+ https://sites.google.com/site/nodejsmacosx/
+
+Download version 0.4.x (stable)
+
+### Install node on Ubuntu Linux
+
+Open the Terminal and enter the following commands one at a time:
+
+ sudo apt-get update
+ sudo apt-get install git-core curl build-essential openssl libssl-dev
+ git clone https://github.com/joyent/node.git && cd node
+ git checkout v0.4.12
+ ./configure
+ make
+ sudo make install
+
+Then verify that the installation completed successfully by printing out the node version:
+
+ node -v
+
+### Install npm on Ubuntu Linux
+
+The installation is just a single command:
+
+ curl http://npmjs.org/install.sh | sudo sh
+
+Then verify that the installation was completed successfully by printing out the npm version:
+
+ npm -v
+
+## Install Screening
+
+Screening comes distributed as a tarball. You can uncompress it in the location of your choice by using a GUI or the
+command line.
+
+ tar -xzvf
+
+When uncompressed, it creates a structure similar to this:
+
+ SCREENING_HOME
+ ├── common
+ ├── docs
+ ├── public
+ ├── server
+ └── test
+
+We'll refer to the base directory as SCREENING_HOME from now on.
+
+### Install dependencies
+
+Use npm to install the Screening dependencies:
+
+From SCREENING_HOME:
+
+ cd server
+ npm install
+
+This will download all the libraries used by Screening into: SCREENING_HOME/server/node_modules.
+
+
+### Download and install MongoDB
+
+MongoDB can be downloaded from http://www.mongodb.org/downloads. Screening has been tested with version 2.0.
+Please use the 64-bit version if your system supports it.
+
+However it's also possible to download it automatically with the following command:
+
+From SCREENING_HOME:
+
+ cd server
+ npm run-script install-mongodb
+
+If the installation successfully completes, MongoDB will be located in a location similar to the following (it varies
+depending on the platform):
+
+ ~/mongodb-osx-x86_64-2.0.1
+
+We'll refer to this as MONGO_HOME.
+
+## Startup Screening
+
+### Startup the MongoDB server
+
+Important note: The MongoDB server must be started before the Screening server.
+
+Make sure that a directory called ~/data/db exists. This is created by the previous step, and if not then create it.
+
+From MONGO_HOME:
+
+ ./bin/mongod --dbpath ~/data/db/
+
+This will start MongoDB on the standard port (27017).
+
+### Startup the Screening Server
+
+From SCREENING_HOME:
+
+ cd server
+ npm start
+
+The output from the last command should look like this:
+
+ > screening@0.1.6 start /Users/BNH378/Documents/code/node/screening/server
+ > node index.js
+
+ [webdriver] express app was mounted.
+ [agents] express app was mounted.
+ [scripts] express app was mounted.
+ [test_results] express app was mounted.
+ info - socket.io started
+ Screening Server running on port 8081 [development]
+ Connected to MongoDB server on localhost:27017, database: screening
+
+Verify that the server was started up correctly by navigating to the Control Room at:
+
+ http://localhost:8081/screening/control-room/index.html
+
@@ -0,0 +1,42 @@
+<!-- <copyright>
+ This file contains proprietary software owned by Motorola Mobility, Inc.<br/>
+ No rights, expressed or implied, whatsoever to this software are provided by Motorola Mobility, Inc. hereunder.<br/>
+ (c) Copyright 2011 Motorola Mobility, Inc. All Rights Reserved.
+ </copyright> -->
+
+# MongoDB in Screening
+
+MongoDB is used to persist test scripts and test results.
+
+Screening will not start up if a MongoDB server is not up and running.
+
+## Installation
+
+1. Download MongoDB 2.0.0 for your platform from:
+
+ [MongoDB Downloads](http://www.mongodb.org/downloads)
+
+ **Note**: Make sure to download the 64-bit version.
+
+2. Uncompress the archive into it's own directory (~/Applications/mongodb-osx-x86_64-2.0.0 will be used for this example)
+
+3. Create the ~/data/db/ directory, this is where the database files will be stored
+
+ mkdir -p ~/data/db/
+
+## Running
+
+The installation process is only done once, afterwards you can start up MongoDB with the following command:
+
+ ~/Applications/mongodb-osx-x86_64-2.0.0/bin/mongod --dbpath ~/data/db/
+
+That starts up MongoDB in the default port (27017)
+
+## MongoDB Shell
+
+This is *not* required in order to run screening but if you're an advanced user and would like to interact directly
+with the DB then the shell is started with this command:
+
+ ~/Applications/mongodb-osx-x86_64-2.0.0/bin/mongo
+
+It automatically connects to localhost:27017
Oops, something went wrong.

0 comments on commit eb0e7c5

Please sign in to comment.