feat(config): add exmples for dealing with log-in

Adds examples for how to log in when the login page is not written
in Angular. New examples are in spec/login.

Author: juliemr

docs/faq.md

@@ -8,3 +8,16 @@ Protractor attempts to wait until the page is completely loaded before
 performing any action (such as finding an element or sending a command to
 an element). If your application continuously polls $timeout or $http, it will
 never be registered as completely loaded. Discussion of this is in [issue 59](https://github.com/angular/protractor/issues/49).
+
+
+_How do I deal with my log-in page?_
+
+If your app needs log-in, there are a couple ways to deal with it. If your login
+page is not written with Angular, you'll need to interact with it via 
+unwrapped webdriver, which can be accessed like `ptor.driver.get()`. 
+
+You can put your log-in code into an `onPrepare` function, which will be run
+once before any of your tests. See [this example](https://github.com/angular/protractor/blob/master/spec/login/viaConfigConf.js).
+
+If you would like to do your login in your test suite itself, see
+[this example](https://github.com/angular/protractor/blob/master/spec/login/viaTestSpec.js).

lib/cli.js

@@ -145,8 +145,9 @@ var startJasmineTests = function() {
       usingServer(config.seleniumAddress).
       withCapabilities(config.capabilities).build();
 
-  driver.manage().timeouts().setScriptTimeout(100000);
   driver.getSession().then(function(session) {
+    driver.manage().timeouts().setScriptTimeout(100000);
+
     id = session.getId();
 
     protractor.setInstance(protractor.wrapDriver(driver, config.baseUrl, config.rootElement));
@@ -163,11 +164,19 @@ var startJasmineTests = function() {
 
     // Let the configuration configure the protractor instance before running
     // the tests.
-    if (config.onPrepare) {
-      config.onPrepare();
-    }
-    
-    minijn.executeSpecs(options);
+    webdriver.promise.controlFlow().execute(function() {
+      if (config.onPrepare) {
+        if (typeof config.onPrepare == 'function') {
+          config.onPrepare();
+        } else if (typeof config.onPrepare == 'string') {
+          require(path.resolve(process.cwd(), config.onPrepare));
+        } else {
+          throw 'config.onPrepare must be a string or function';
+        }
+      }
+    }).then(function() {
+      minijn.executeSpecs(options);
+    });
   });
 }
 

referenceConf.js

@@ -62,6 +62,8 @@ exports.config = {
 
   // A callback function called once protractor is ready and available, and
   // before the specs are executed
+  // You can specify a file containing code to run by setting onPrepare to
+  // the filename string.
   onPrepare: function() {
     // At this point, global 'protractor' object will be set up, and jasmine
     // will be available. For example, you can add a Jasmine reporter with:

spec/login/viaConfigConf.js

@@ -0,0 +1,36 @@
+// This is the configuration file showing how a suite of tests might
+// handle log-in using the onPrepare field.
+exports.config = {
+  seleniumServerJar: './selenium/selenium-server-standalone-2.35.0.jar',
+  chromeDriver: './selenium/chromedriver',
+
+  seleniumAddress: 'http://localhost:4444/wd/hub',
+
+  specs: [
+    'viaConfigSpec.js'
+  ],
+
+  capabilities: {
+    'browserName': 'chrome'
+  },
+
+  onPrepare: function() {
+    var ptor = protractor.getInstance();
+    ptor.driver.get('http://localhost:8000/app/login.html');
+
+    ptor.driver.findElement(protractor.By.id('username')).sendKeys('Jane');
+    ptor.driver.findElement(protractor.By.id('password')).sendKeys('1234');
+    ptor.driver.findElement(protractor.By.id('clickme')).click();
+
+    // Login takes some time, so wait until it's done.
+    // For the test app's login, we know it's done when it redirects to
+    // index.html.
+    ptor.wait(function() {
+      return ptor.driver.getCurrentUrl().then(function(url) {
+        return /index/.test(url);
+      });
+    });
+  },
+
+  baseUrl: 'http://localhost:8000',
+};

spec/login/viaConfigSpec.js

@@ -0,0 +1,19 @@
+describe('pages with login', function() {
+  var ptor;
+
+  beforeEach(function() {
+    ptor = protractor.getInstance();
+  })
+
+  it('should log in with a non-Angular page', function() {
+    ptor.get('http://localhost:8000/app/index.html');
+
+    var angularElement = ptor.findElement(protractor.By.input('url'));
+    expect(angularElement.getAttribute('value')).toEqual('/fastcall');
+
+    // Make sure the cookie is still set.
+    ptor.manage().getCookie('testcookie').then(function(cookie) {
+      expect(cookie.value).toEqual('Jane-1234');
+    });
+  });
+});

spec/login/viaTestConf.js

@@ -0,0 +1,18 @@
+// This is the configuration file showing how a suite of tests might
+// handle log-in using the onPrepare field.
+exports.config = {
+  seleniumServerJar: './selenium/selenium-server-standalone-2.35.0.jar',
+  chromeDriver: './selenium/chromedriver',
+
+  seleniumAddress: 'http://localhost:4444/wd/hub',
+
+  specs: [
+    'viaTestSpec.js'
+  ],
+
+  capabilities: {
+    'browserName': 'chrome'
+  },
+
+  baseUrl: 'http://localhost:8000',
+};

spec/login/viaTestSpec.js

@@ -0,0 +1,40 @@
+describe('pages with login', function() {
+  var ptor;
+
+  beforeEach(function() {
+    ptor = protractor.getInstance();
+  })
+
+  it('should log in with a non-Angular page', function() {
+    ptor.driver.get('http://localhost:8000/app/login.html');
+
+    ptor.driver.findElement(protractor.By.id('username')).sendKeys('Jane');
+    ptor.driver.findElement(protractor.By.id('password')).sendKeys('1234');
+    ptor.driver.findElement(protractor.By.id('clickme')).click();
+
+    // Login takes some time, so wait until it's done.
+    // For the test app's login, we know it's done when it redirects to
+    // index.html.
+    ptor.wait(function() {
+      return ptor.driver.getCurrentUrl().then(function(url) {
+        return /index/.test(url);
+      });
+    });
+
+    // The login should have set a cookie. Make sure it's there.
+    ptor.manage().getCookie('testcookie').then(function(cookie) {
+      expect(cookie.value).toEqual('Jane-1234');
+    });
+
+
+    ptor.get('http://localhost:8000/app/index.html');
+
+    var angularElement = ptor.findElement(protractor.By.input('url'));
+    expect(angularElement.getAttribute('value')).toEqual('/fastcall');
+
+    // Make sure the cookie is still set.
+    ptor.manage().getCookie('testcookie').then(function(cookie) {
+      expect(cookie.value).toEqual('Jane-1234');
+    });
+  });
+});

spec/onPrepare/startup.js

@@ -0,0 +1,5 @@
+var ptor = protractor.getInstance();
+ptor.elem = ptor.findElement;
+ptor.elems = ptor.findElements;
+global.by = protractor.By;
+global.ptor = ptor;

spec/onPrepareStringConf.js

@@ -0,0 +1,21 @@
+// Configuration using a string in onPrepare to load a file with code to
+// execute once before tests.
+exports.config = {
+  seleniumServerJar: './selenium/selenium-server-standalone-2.35.0.jar',
+  chromeDriver: './selenium/chromedriver',
+
+  seleniumAddress: 'http://localhost:4444/wd/hub',
+
+  // Spec patterns are relative to this directory.
+  specs: [
+    'onPrepare/*_spec.js'
+  ],
+
+  capabilities: {
+    'browserName': 'chrome'
+  },
+
+  baseUrl: 'http://localhost:8000',
+  
+  onPrepare: 'onPrepare/startup.js'
+};

testapp/app/login.html

@@ -0,0 +1,25 @@
+<html>
+  <head>
+    <title>Test Application Login</title>
+    <script>
+      function login() {
+        // Make sure everything works when the login is slow.
+        window.setTimeout(function() {
+          // Set a simple cookie.
+          var username = document.getElementById('username').value;
+          var password = document.getElementById('password').value;
+
+          document.cookie = 'testcookie=' + username + '-' + password;
+
+          window.location.assign('index.html');
+        }, 2000);
+      };
+    </script>
+  </head>
+  <body>
+    <div>Login</div>
+    <div><label>Username</label><input id="username" type="text"/></div>
+    <div><label>Password</label><input id="password" type="text"/></div>
+    <div><button id="clickme" onClick="login()">Go</button></div>
+  </body>
+</html>