protractor - npm Package Compare versions

Comparing version 0.11.0 to 0.12.0

bin/elementexplorer.js

@@ -17,14 +17,14 @@ #!/usr/bin/env node
  * This will load up the URL on webdriver and put the terminal into a REPL loop.
- * You will see a > prompt. The `ptor` and `protractor` variables will
- * be available. Enter a command such as:
+ * You will see a > prompt. The `browser`, `element` and `protractor` variables
+ * will be available. Enter a command such as:
  *
- *     > ptor.findElement(protractor.By.id('foobar')).getText()
+ *     > element(by.id('foobar')).getText()
  *
  * or
  *
- *     > ptor.get('http://www.angularjs.org')
+ *     > browser.get('http://www.angularjs.org')
  *
  * try just
  *
- *     > ptor
+ *     > browser
  *
@@ -43,19 +43,19 @@ * to get a list of functions you can call.
 
-var driver, ptor;
+var driver, browser;
 
 var INITIAL_SUGGESTIONS = [
-  'ptor.findElement(protractor.By.id(\'\'))',
-  'ptor.findElement(protractor.By.css(\'\'))',
-  'ptor.findElement(protractor.By.name(\'\'))',
-  'ptor.findElement(protractor.By.binding(\'\'))',
-  'ptor.findElement(protractor.By.input(\'\'))',
-  'ptor.findElement(protractor.By.select(\'\'))',
-  'ptor.findElement(protractor.By.textarea(\'\'))',
-  'ptor.findElement(protractor.By.xpath(\'\'))',
-  'ptor.findElement(protractor.By.tagName(\'\'))',
-  'ptor.findElement(protractor.By.className(\'\'))'
+  'element(by.id(\'\'))',
+  'element(by.css(\'\'))',
+  'element(by.name(\'\'))',
+  'element(by.binding(\'\'))',
+  'element(by.input(\'\'))',
+  'element(by.select(\'\'))',
+  'element(by.textarea(\'\'))',
+  'element(by.xpath(\'\'))',
+  'element(by.tagName(\'\'))',
+  'element(by.className(\'\'))'
 ];
 
 var list = function(locator) {
-  return ptor.findElements(locator).then(function(arr) {
+  return browser.findElements(locator).then(function(arr) {
     var found = [];
@@ -129,13 +129,18 @@ for (var i = 0; i < arr.length; ++i) {
 
-    ptor = protractor.wrapDriver(driver);
+    browser = protractor.wrapDriver(driver);
 
     // Set up globals to be available from the command line.
     global.driver = driver;
-    global.ptor = ptor;
     global.protractor = protractor;
+    global.browser = browser;
+    global.$ = browser.$;
+    global.$$ = browser.$$;
+    global.element = browser.element;
+    global.by = protractor.By;
     global.list = list;
 
+
     util.puts('Type <tab> to see a list of locator strategies.');
     util.puts('Use the `list` helper function to find elements by strategy:');
-    util.puts('  e.g., list(protractor.By.binding(\'\')) gets all bindings.');
+    util.puts('  e.g., list(by.binding(\'\')) gets all bindings.');
     util.puts('');
@@ -142,0 +147,0 @@

CHANGELOG.md

@@ -0,1 +1,35 @@
+# 0.12.0
+
+_Note: Major version 0 releases are for initial development, and backwards compatible changes may be introduced at any time._
+
+This change introduces major syntax updates. Using the new syntax is recommeded, but the old version is still supported for now. Note also that the test application, docs, and example tests have been updated.
+
+## Features
+
+- ([a2cd6c8](https://github.com/angular/protractor/commit/a2cd6c8baf242a81c4efea1f55249d597de95329)) feat(syntax): big syntax reboot, expose global $, $$, element, and by
+
+In an effort to make tests more readable and clear, a few more global variables
+will now be exported.
+
+`browser` is an instance of protractor. This was previously accessed using
+`protractor.getInstance`.
+
+`by` is a collection of element locators. Previously, this was `protractor.By`.
+
+`$` is a shortcut for getting elements by css. `$('.foo')` === `element(by.css('.foo'))`
+
+All changes should be backwards compatible, as tested with the new 'backwardscompat'
+tests.
+
+## Bug fixes
+
+- ([8c87ae6](https://github.com/angular/protractor/commit/8c87ae6b430479445744a2f5c8eaca7f5f03d61d)) fix(onPrepare): onPrepare with a string argument should resolve from the config directory
+
+onPrepare can take a string, which is a filename containing a script to load adn execute
+before any tests run. This fixes the string to resolve the filename relative to the
+config file, instead of relative to the current working directory where protractor
+is called.
+
+
+
 # 0.11.0
@@ -2,0 +36,0 @@

docs/control-flow.md

@@ -20,9 +20,9 @@ The Webdriver Control Flow
   it('should find an element by text input model', function() {
-    ptor.get('app/index.html#/form');
+    browser.get('app/index.html#/form');
 
-    var username = ptor.findElement(protractor.By.input('username'));
+    var username = element(by.input('username'));
     username.clear();
     username.sendKeys('Jane Doe');
 
-    var name = ptor.findElement(protractor.By.binding('username'));
+    var name = element(by.binding('username'));
 
@@ -35,3 +35,3 @@ expect(name.getText()).toEqual('Jane Doe');
 
-At Point A, none of the tasks have executed yet. The `ptor.get` call is at
+At Point A, none of the tasks have executed yet. The `browser.get` call is at
 the front of the control flow queue, and the `name.getText()` call is at the
@@ -38,0 +38,0 @@ back. The value of `name.getText()` at point A is an unresolved promise

docs/debugging.md

@@ -28,3 +28,3 @@ Debugging Protractor Tests
    If your test needs to interact with a non-angular page, access the webdriver
-   instance directly with `ptor.driver`.
+   instance directly with `browser.driver`.
 -  An expectation failure. This shows what a normal expectation failure looks
@@ -37,10 +37,8 @@ like.
 Protractor allows you to pause your test at any point and interact with the
-browser. To do this insert `ptor.debugger();` into your test where you wish
+browser. To do this insert `browser.debugger();` into your test where you wish
 to break.
 
 ```javascript
-ptor = protractor.getInstance();
-
 it('should fail to find a non-existent element', function() {
-  ptor.get('app/index.html#/form');
+  browser.get('app/index.html#/form');
 
@@ -51,6 +49,6 @@ // Run this statement before the line which fails. If protractor is run
   // element.
-  ptor.debugger();
+  browser.debugger();
 
   // This element doesn't exist, so this fails.
-  var nonExistant = ptor.findElement(protractor.By.binding('nopenopenope'));
+  var nonExistant = element(by.binding('nopenopenope'));
 });
@@ -68,3 +66,3 @@ ```
 
-We use `ptor.debugger();` instead of node's `debugger;` statement so that
+We use `browser.debugger();` instead of node's `debugger;` statement so that
 the test pauses after the get command has beenexecuted*. Using `debugger;`
@@ -109,3 +107,2 @@ pauses the test after the get command isscheduled* but has not yet
 
-
 Currently, the explorer runs only with chrome and expects a selenium standalone
@@ -119,14 +116,14 @@ server to be running at http://localhost:4444.
 This will load up the URL on webdriver and put the terminal into a REPL loop.
-You will see a > prompt. The `ptor` and `protractor` variables will
+You will see a > prompt. The `browser`, `element` and `protractor` variables will
 be available. Enter a command such as:
 
-    > ptor.findElement(protractor.By.id('foobar')).getText()
+    > element(by.id('foobar')).getText()
 
 or
 
-    > ptor.get('http://www.angularjs.org')
+    > browser.get('http://www.angularjs.org')
 
 try just
 
-    > ptor
+    > browser
 
@@ -141,3 +138,3 @@ to get a list of functions you can call.
 
-Webdriver can snap a screenshot with `WebDriver.prototype.takeScreenshot()`.
+Webdriver can snap a screenshot with `browser.takeScreenshot()`.
 This returns a promise which will resolve to the screenshot as a base-64
@@ -144,0 +141,0 @@ encoded PNG.

docs/faq.md

 FAQ
 ===
 
-My tests time out in Protractor, but everything's working fine when running
-manually. What's up?
+My tests time out in Protractor, but everything's working fine when running manually. What's up?
 --------------------
@@ -49,3 +48,3 @@
 page is not written with Angular, you'll need to interact with it via 
-unwrapped webdriver, which can be accessed like `ptor.driver.get()`. 
+unwrapped webdriver, which can be accessed like `browser.driver.get()`. 
 
@@ -52,0 +51,0 @@ You can put your log-in code into an `onPrepare` function, which will be run

docs/getting-started.md

@@ -28,4 +28,4 @@ Getting Started
 
-Setup and Run
--------------
+Setup and Config
+----------------
 
@@ -52,3 +52,3 @@ Install Protractor with
 
-    protractor example/protractorConf.js
+    protractor node_modules/protractor/example/protractorConf.js
 
@@ -73,3 +73,3 @@ The configuration file tells Protractor what tests to run, how to connect to a
   // include glob patterns.
-  specs: ['onProtractorRunner.js'],
+  specs: ['example-spec.js'],
 
@@ -87,5 +87,18 @@ // Options to be passed to Jasmine-node.
 By default, Protractor uses [Jasmine](http://pivotal.github.io/jasmine/) as its
-test scaffolding. The `protractor` variable is exposed globally and can be used
-to grab an instance of Protractor (which is called `ptor` in the docs). 
+test scaffolding. Protractor exposes several global variables.
 
+ * `browser` this is the a wrapper around an instance of webdriver. Used for
+ navigation and page-wide information.
+
+ * `element` is a helper function for finding and interacting with elements
+ on the page you are testing.
+
+ * `by` is a collection of element locator strategies. For example, elements
+ can be found by CSS selector, by ID, or by the attribute they are bound to with
+ ng-model.
+
+ * `protractor` is the protractor namespace which wraps the webdriver namespace.
+ This contains static variables and classes, such as `protractor.Key` which
+ enumerates the codes for special keybord signals.
+
 Take this example, which tests the 'Basics' example on the AngularJS homepage:
@@ -95,17 +108,13 @@
 describe('angularjs homepage', function() {
-  var ptor;
-
-  it('should greet using binding', function() {
-    ptor = protractor.getInstance();
-
+  it('should greet the named user', function() {
     // Load the AngularJS homepage.
-    ptor.get('http://www.angularjs.org');
+    browser.get('http://www.angularjs.org');
 
     // Find the element with ng-model matching 'yourName', and then
     // type 'Julie' into it.
-    ptor.findElement(protractor.By.input("yourName")).sendKeys("Julie");
+    element(by.model('yourName')).sendKeys('Julie');
 
     // Find the element with binding matching 'yourName' - this will
     // find the <h1>Hello {{yourName}}!</h1> element.
-    var greeting = ptor.findElement(protractor.By.binding("yourName"));
+    var greeting = element(by.binding('yourName'));
 
@@ -117,33 +126,68 @@ // Assert that the text element has the expected value.
 });
+
 ```
 
-The `get` method loads a page. Protractor expects Angular to be present on a
-page, so it will throw an error if the page it is attempting to load does
-not containt he Angular library. (If you need to interact with a non-Angular
+The `browser.get` method loads a page. Protractor expects Angular to be present on a page, so it will throw an error if the page it is attempting to load does
+not contain the Angular library. (If you need to interact with a non-Angular
 page, you may access the wrapped webdriver instance directly with
-`ptor.driver`).
+`browser.driver`).
 
-The `findElement` method searches for an element on the page. It requires one
-parameter, a *locator strategy* for locating the element. Protractor offers Angular
-specific strategies:
+The `element` method searches for an element on the page. It requires one
+parameter, a *locator* strategy for locating the element. Protractor offers Angular specific strategies:
 
--  `protractor.By.binding` searches for elements by matching binding names,
+-  `by.binding` searches for elements by matching binding names,
    either from `ng-bind` or `{{}}` notation in the template.
--  `protractor.By.input` searches for elements by input `ng-model`.
--  `protractor.By.repeater` seraches for `ng-repeat` elements. For example,
-   `protractor.By.repeater('phone in phones').row(12).column('price')` returns
+-  `by.model` searches for elements by input `ng-model`.
+-  `by.repeater` searches for `ng-repeat` elements. For example,
+   `by.repeater('phone in phones').row(12).column('price')` returns
    the element in the 12th row of the `ng-repeat = "phone in phones"` repeater
    with the binding matching `{{phone.price}}`.
 
-You may also use plain old WebDriver strategies such as `protractor.By.id` and
-`protractor.By.css`.
+You may also use plain old WebDriver strategies such as `by.id` and
+`by.css`. Since locating by CSS selector is so common, the global variable `$` is an alias for `element.by.css`.
 
-Once you have an element, you can interact with it with methods such as
+`element` returns an ElementFinder. This is an object which allows you to interact with the element on your page, but since all interaction with the browser must be done over webdriver, it is important to remember that this is *not* a DOM element. You can interact with it with methods such as
 `sendKeys`, `getText`, and `click`. Check out the [API](/api.md) for a list of
 all available methods.
 
-See Protractor's [findelements test suite](https://github.com/angular/protractor/blob/master/spec/findelements_spec.js)
+See Protractor's [findelements test suite](https://github.com/angular/protractor/blob/master/spec/basic/findelements_spec.js)
 for more examples.
 
 
+Organizing Real Tests: Page Objects
+-----------------------------------
+
+When writing real tests scripts for your page, it's best to use the [Page Objects](https://code.google.com/p/selenium/wiki/PageObjects) pattern to make your tests more readable. In Protractor, this could look like:
+
+```javascript
+var AngularHomepage = function() {
+  this.nameInput = element(by.model('yourName'));
+  this.greeting = element(by.binding('yourName'));
+
+  this.get = function() {
+    browser.get('http://www.angularjs.org');
+  };
+
+  this.setName = function(name) {
+    this.nameInput.sendKeys(name);
+  };
+};
+```
+
+Your test then becomes:
+
+```javascript
+describe('angularjs homepage', function() {
+  it('should greet the named user', function() {
+    var angularHomepage = new AngularHomepage();
+    angularHomepage.get();
+
+    angularHomepage.setName('Julie');
+
+    expect(angularHomepage.greeting.getText()).toEqual('Hello Julie!');
+  });
+});
+```
+
+
 Further Reading
@@ -150,0 +194,0 @@ ---------------

lib/cli.js

@@ -31,3 +31,3 @@ /**
     boolean('includeStackTrace').
-    alias('verbose', 'jasmineNodeOpts.verbose').
+    alias('verbose', 'jasmineNodeOpts.isVerbose').
     alias('includeStackTrace', 'jasmineNodeOpts.includeStackTrace').
@@ -34,0 +34,0 @@ check(function(arg) {

lib/locators.js

@@ -25,3 +25,3 @@ var util = require('util');
  *   <span>{{status}}</span>
- *   var status = ptor.findElement(protractor.By.binding('{{status}}'));
+ *   var status = element(by.binding('{{status}}'));
  *
@@ -47,4 +47,4 @@ * Note: This ignores parent element restrictions if called with
  * Usage:
- * <select ng-model="user" ng-options="user.name for user in users"></select>
- * ptor.findElement(protractor.By.select("user"));
+ *   <select ng-model="user" ng-options="user.name for user in users"></select>
+ *   element(by.select("user"));
  */
@@ -66,4 +66,4 @@ ProtractorBy.prototype.select = function(model) {
  * Usage:
- * <select ng-model="user" ng-options="user.name for user in users"></select>
- * ptor.findElements(protractor.By.selectedOption("user"));
+ *   <select ng-model="user" ng-options="user.name for user in users"></select>
+ *   element(by.selectedOption("user"));
  */
@@ -82,6 +82,8 @@ ProtractorBy.prototype.selectedOption = function(model) {
 };
+
 /**
+ * @DEPRECATED - use 'model' instead.
  * Usage:
- * <input ng-model="user" type="text"/>
- * ptor.findElement(protractor.By.input("user"));
+ *   <input ng-model="user" type="text"/>
+ *   element(by.input('user'));
  */
@@ -103,5 +105,23 @@ ProtractorBy.prototype.input = function(model) {
  * Usage:
- * <textarea ng-model="user"></textarea>
- * ptor.findElement(protractor.By.textarea("user"));
+ *   <input ng-model="user" type="text"/>
+ *   element(by.model('user'));
  */
+ProtractorBy.prototype.model = function(model) {
+  return {
+    findOverride: function(driver, using) {
+      return driver.findElement(
+          webdriver.By.js(clientSideScripts.findInput), using, model);
+    },
+    findArrayOverride: function(driver, using) {
+      return driver.findElements(
+          webdriver.By.js(clientSideScripts.findInputs), using, model);
+    }
+  };
+};
+
+/**
+ * Usage:
+ *   <textarea ng-model="user"></textarea>
+ *   element(by.textarea("user"));
+ */
 ProtractorBy.prototype.textarea = function(model) {
@@ -118,19 +138,18 @@ return {
  * Usage:
- * <div ng-repeat = "cat in pets">
- *   <span>{{cat.name}}</span>
- *   <span>{{cat.age}}</span>
- * </div>
+ *   <div ng-repeat = "cat in pets">
+ *     <span>{{cat.name}}</span>
+ *     <span>{{cat.age}}</span>
+ *   </div>
  *
  * // Returns the DIV for the second cat.
- * var secondCat = ptor.findElement(
- *     protractor.By.repeater("cat in pets").row(2));
+ * var secondCat = element(by.repeater("cat in pets").row(2));
  * // Returns the SPAN for the first cat's name.
- * var firstCatName = ptor.findElement(
- *     protractor.By.repeater("cat in pets").row(1).column("{{cat.name}}"));
+ * var firstCatName = element(
+ *     by.repeater("cat in pets").row(1).column("{{cat.name}}"));
  * // Returns a promise that resolves to an array of WebElements from a column
- * var ages = ptor.findElements(
- *     protractor.By.repeater("cat in pets").column("{{cat.age}}"));
+ * var ages = element(
+ *     by.repeater("cat in pets").column("{{cat.age}}"));
  * // Returns a promise that resolves to an array of WebElements containing
  * // all rows of the repeater.
- * var rows = ptor.findElements(protractor.By.repeater("cat in pets"));
+ * var rows = element(by.repeater("cat in pets"));
  */
@@ -137,0 +156,0 @@ ProtractorBy.prototype.repeater = function(repeatDescriptor) {

lib/protractor.js

@@ -10,2 +10,7 @@ var url = require('url');
 
+var WEB_ELEMENT_FUNCTIONS = [
+  'click', 'sendKeys', 'getTagName', 'getCssValue', 'getAttribute', 'getText',
+  'getSize', 'getLocation', 'isEnabled', 'isSelected', 'submit', 'clear',
+  'isDisplayed', 'getOuterHtml', 'getInnerHtml'];
+
 /**
@@ -21,2 +26,4 @@ * Mix in other webdriver functionality to be accessible via protractor.
  * called in the context of the original object.
+ *
+ * @private
  * @param {Object} to
@@ -33,6 +40,108 @@ * @param {Object} from
     return from[fnName].apply(from, arguments);
+  };
+};
+
+/**
+ * Build the helper 'element' function for a given instance of Protractor.
+ *
+ * @private
+ * @param {Protractor} ptor
+ * @return {function(webdriver.Locator): ElementFinder}
+ */
+var buildElementHelper = function(ptor) {
+  var element = function(locator) {
+    var elementFinder = {};
+    var webElementFns = WEB_ELEMENT_FUNCTIONS.concat(
+        ['findElements', 'isElementPresent', 'evaluate', '$$']);
+    webElementFns.forEach(function(fnName) {
+      elementFinder[fnName] = function() {
+        var args = arguments;
+        return ptor.findElement(locator).then(function(element) {
+          return element[fnName].apply(element, args);
+        }, function(error) {
+          throw error;
+        });
+      };
+    });
+
+    // This is a special case since it doesn't return a promise, instead it
+    // returns a WebElement.
+    elementFinder.findElement = function(subLocator) {
+      return ptor.findElement(locator).findElement(subLocator);
+    };
+
+    // This is a special case since it doesn't return a promise, instead it
+    // returns a WebElement.
+    elementFinder.$ = function(cssSelector) {
+      return ptor.findElement(locator).
+          findElement(webdriver.By.css(cssSelector));
+    };
+
+    elementFinder.find = function() {
+      return ptor.findElement(locator);
+    };
+
+    elementFinder.isPresent = function() {
+      return ptor.isElementPresent(locator);
+    };
+
+    return elementFinder;
+  };
+
+  /**
+   * @type {function(webdriver.Locator): ElementArrayFinder}
+   */
+  element.all = function(locator) {
+    var elementArrayFinder = {};
+
+    elementArrayFinder.count = function() {
+      return ptor.findElements(locator).then(function(arr) {
+        return arr.length;
+      });
+    };
+
+    elementArrayFinder.get = function(index) {
+      var id = ptor.findElements(locator).then(function(arr) {
+        return arr[index];
+      });
+      return new webdriver.WebElement(ptor.driver, id);
+    };
+
+    elementArrayFinder.then = function() {
+      return ptor.findElements(locator);
+    };
+
+    return elementArrayFinder;
   }
+
+  return element;
 };
 
 /**
+ * Build the helper '$' function for a given instance of Protractor.
+ *
+ * @private
+ * @param {Protractor} ptor
+ * @return {function(string): ElementFinder}
+ */
+var buildCssHelper = function(ptor) {
+  return function(cssSelector) {
+    return buildElementHelper(ptor)(webdriver.By.css(cssSelector));
+  };
+};
+
+/**
+ * Build the helper '$$' function for a given instance of Protractor.
+ *
+ * @private
+ * @param {Protractor} ptor
+ * @return {function(string): ElementArrayFinder}
+ */
+var buildMultiCssHelper = function(ptor) {
+  return function(cssSelector) {
+    return buildElementHelper(ptor).all(webdriver.By.css(cssSelector));
+  };
+};
+
+/**
  * @param {webdriver.WebDriver} webdriver
@@ -70,2 +179,23 @@ * @param {string=} opt_baseUrl A base URL to run get requests against.
   /**
+   * Helper function for finding elements.
+   *
+   * @type {function(webdriver.Locator): ElementFinder}
+   */
+  this.element = buildElementHelper(this);
+
+  /**
+   * Helper function for finding elements by css.
+   *
+   * @type {function(string): ElementFinder}
+   */
+  this.$ = buildCssHelper(this);
+
+  /**
+   * Helper function for finding arrays of elements by css.
+   *
+   * @type {function(string): ElementArrayFinder}
+   */
+  this.$$ = buildMultiCssHelper(this);
+
+  /**
    * All get methods will be resolved against this base URL. Relative URLs are =
@@ -141,10 +271,6 @@ * resolved the way anchor tags resolve.
   var thisPtor = this;
-  // Before any of these WebElement functions, Protractor will wait to make sure
+  // Before any of the WebElement functions, Protractor will wait to make sure
   // Angular is synched up.
-  var functionsToSync = [
-    'click', 'sendKeys', 'getTagName', 'getCssValue', 'getAttribute', 'getText',
-    'getSize', 'getLocation', 'isEnabled', 'isSelected', 'submit', 'clear',
-    'isDisplayed', 'getOuterHtml', 'getInnerHtml'];
   var originalFns = {};
-  functionsToSync.forEach(function(name) {
+  WEB_ELEMENT_FUNCTIONS.forEach(function(name) {
     originalFns[name] = element[name];
@@ -263,14 +389,2 @@ element[name] = function() {
 /**
- * Shortcut for querying the document directly with css.
- *
- * @param {string} selector a css selector
- * @see webdriver.WebDriver.findElement
- * @return {!webdriver.WebElement}
- */
-Protractor.prototype.$ = function(selector) {
-  var locator = protractor.By.css(selector);
-  return this.findElement(locator);
-};
-
-/**
  * Waits for Angular to finish rendering before searching for elements.
@@ -294,15 +408,2 @@ * @see webdriver.WebDriver.findElement
 /**
- * Shortcut for querying the document directly with css.
- *
- * @param {string} selector a css selector
- * @see webdriver.WebDriver.findElements
- * @return {!webdriver.promise.Promise} A promise that will be resolved to an
- *     array of the located {@link webdriver.WebElement}s.
- */
-Protractor.prototype.$$ = function(selector) {
-  var locator = protractor.By.css(selector);
-  return this.findElements(locator);
-};
-
-/**
  * Waits for Angular to finish rendering before searching for elements.
@@ -309,0 +410,0 @@ * @see webdriver.WebDriver.findElements

lib/runner.js

@@ -194,12 +194,17 @@ var util = require('util');
 
-    var ptor = protractor.wrapDriver(
+    var browser = protractor.wrapDriver(
         driver,
         config.baseUrl,
         config.rootElement)
-    ptor.params = config.params;
+    browser.params = config.params;
 
-    protractor.setInstance(ptor);
+    protractor.setInstance(browser);
 
     // Export protractor to the global namespace to be used in tests.
     global.protractor = protractor;
+    global.browser = browser;
+    global.$ = browser.$;
+    global.$$ = browser.$$;
+    global.element = browser.element;
+    global.by = protractor.By;
 
@@ -213,3 +218,3 @@ // Let the configuration configure the protractor instance before running
         } else if (typeof config.onPrepare == 'string') {
-          require(path.resolve(process.cwd(), config.onPrepare));
+          require(path.resolve(config.specFileBase, config.onPrepare));
         } else {
@@ -216,0 +221,0 @@ throw 'config.onPrepare must be a string or function';

package.json

@@ -39,3 +39,3 @@ {
   "license" : "MIT",
-  "version": "0.11.0"
+  "version": "0.12.0"
 }

README.md

 Protractor
 ==========
 
-Protractor is an end to end test framework for [Angular](http://angularjs.org/) applications built on top of [WebDriverJS](https://code.google.com/p/selenium/wiki/WebDriverJs).
+Protractor is an end to end test framework for [AngularJS](http://angularjs.org/) applications built on top of [WebDriverJS](https://code.google.com/p/selenium/wiki/WebDriverJs).
 
-Protractor can be run as a standalone binary runner, or included into your tests as a library. Use Protractor as a library if you would like to manage WebDriver and your test setup yourself.
+Protractor can be run as a standalone binary runner, or included into your tests as a library. Use [Protractor as a library](https://github.com/angular/protractor/blob/master/docs/library-only.md) if you would like to manage WebDriver and your test setup yourself.
 
@@ -16,40 +16,35 @@ For more information, [read the docs](https://github.com/angular/protractor/tree/master/docs), or head over to the [FAQ](https://github.com/angular/protractor/blob/master/docs/faq.md).
 
-    npm install protractor
+    npm install -g protractor
 
 Start up a selenium server (See the appendix below for help with this). By default, the tests expect the selenium server to be running at `http://localhost:4444/wd/hub`.
 
-The example folder contains multiple versions of a simple test suite which runs against angularjs.org.
+The example folder contains a simple test suite which runs against angularjs.org. Run with: 
 
-`onJasmineNodeSpec.js` and `onMocha.js` show how to use the Protractor library with jasmine-node and mocha. Run these with:
+    protractor example/conf.js
 
-    jasmine-node example/onJasmineNodeSpec.js
-    mocha example/onMocha.js
 
-You can also run the example suite using the Protractor runner. The runner accepts a configuration file, which runs the tests at `example/onProtractorRunner.js`.
-
-    bin/protractor example/protractorConf.js
-
-
 Using the Protractor runner
 ---------------------------
 
-The Protractor runner is a binary which accepts a config file. The Protractor runner runs tests written in Jasmine, but other adapters may be added in the future.
+The Protractor runner is a binary which accepts a config file. Install protractor with
 
-Install protractor with
+    npm install -g protractor
+    # Run the line below to see command line options
+    protractor
 
-    npm install protractor
+You will need a *configuration file* containing setup info and *test files* containing the actual test scripts. The config file specifies how the runner should start webdriver, where your test files are, and global setup options. The test files use Jasmine framework, but other adapters may be added in the future.
 
-Create a configuration file - an example is shown in `node_modules/protractor/referenceConf.js`.
+Create a configuration file - an example with detailed comments is shown in `node_modules/protractor/referenceConf.js`. Edit the configuration file to point to your test files.
 
-    cp node_modules/protractor/referenceConf.js myConf.js
+```javascript
+// myConf.js
+exports.config = {
+  seleniumAddress: 'http://localhost:4444/wd/hub',
+  jasmineNodeOpts: {
+    specs: ['myTest.js', 'myTestFolder/*Test.js']
+  }
+}
+```
 
-Edit the configuration file to point to your tests.
-
-    exports.config = {
-      jasmineNodeOpts: {
-        specs: ['myTest.js', 'myFolder/myOtherTest.js']
-      }
-    }
-
-The configuration file must also specify a way of connection to webdriver. This can be
+The configuration file must specify a way to connection to webdriver. This can be
  *   `seleniumAddress`: The address of a running selenium standalone server.
@@ -59,30 +54,24 @@ *   `seleniumServerJar`: The location of the selenium standalone .jar file on your machine. Protractor will use this to start up the selenium server.
 
-Run with
+The runner exposes global variables `browser`, `by` and `element`. Check out [getting started docs](https://github.com/angular/protractor/blob/master/docs/getting-started.md) to learn how to write a test.
 
-    node_modules/.bin/protractor myConf.js
+```javascript
+// myTest.js
+describe('angularjs homepage', function() {
+  it('should greet the named user', function() {
+    browser.get('http://www.angularjs.org');
 
-Or, if you installed protractor globally (using `npm install -g protractor`)
+    element(by.model('yourName')).sendKeys('Julie');
 
-    protractor myConf.js
+    var greeting = element(by.binding('yourName'));
 
-When using the runner, the protractor library is exported to the global namespace as `protractor`. The current instance can be grabbed with `ptor = protractor.getInstance()`.
+    expect(greeting.getText()).toEqual('Hello Julie!');
+  });
+});
+```
 
+Run with
 
-Using the Protractor library
-----------------------------
+    protractor myConf.js
 
-Use the Protractor library if you would like to manage webdriverJs yourself.
 
-Install protractor with
-
-    npm install protractor
-
-In your test, set up a webdriver instance, then wrap it with protractor.
-
-    var protractor = require('protractor');
-    var driver;
-    // Set up driver as a webdriver however you'd like.
-    var ptor = protractor.wrapDriver(driver);
-
-
 Cloning and running Protractor's own tests
@@ -89,0 +78,0 @@ ------------------------------------------

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Dynamic require

Supply chain risk

Dynamic require can indicate the package is performing dangerous or unsafe dynamic code execution.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Dynamic require

Supply chain risk

Dynamic require can indicate the package is performing dangerous or unsafe dynamic code execution.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

128197

increased by5.45%

Number of package files

29

increased by3.57%

Lines of code

2065

increased by3.25%

Worsened metrics

Number of lines in readme file

113

decreased by-8.87%

No dependency changes