chore: support e2e-specs written in TypeScript

Update gulpfile and project to add a tsconfig to protractor test folders
Change all sample e2e-spec.js -> e2e-spec.ts
Split typings between e2e-spec & app code
Use same config for all e2e tests
Only 1/3 e2e specs truly converted.
Most don't pass because they fail TS transpile by Protractor due to missing type annotations

Author: wardbell

.travis.yml

@@ -18,7 +18,8 @@ before_script:
 install:
   - npm install --no-optional
   - npm install --prefix public/docs/_examples
-  - npm run webdriver:update --prefix public/docs/_examples 
+  - npm install --prefix public/docs/_examples/_protractor
+  - npm run webdriver:update --prefix public/docs/_examples/_protractor
   - gulp add-example-boilerplate
 script:
   - gulp $SCRIPT

gulpfile.js

@@ -38,6 +38,7 @@ var TEMP_PATH = './_temp';
 var DOCS_PATH = path.join(PUBLIC_PATH, 'docs');
 
 var EXAMPLES_PATH = path.join(DOCS_PATH, '_examples');
+var EXAMPLES_PROTRACTOR_PATH = path.join(EXAMPLES_PATH, '_protractor');
 var NOT_API_DOCS_GLOB = path.join(PUBLIC_PATH, './{docs/*/latest/!(api),!(docs)}/**/*');
 var RESOURCES_PATH = path.join(PUBLIC_PATH, 'resources');
 var LIVE_EXAMPLES_PATH = path.join(RESOURCES_PATH, 'live-examples');
@@ -86,123 +87,150 @@ var _exampleBoilerplateFiles = [
 
 var _exampleDartWebBoilerPlateFiles = ['styles.css'];
 
+var _exampleProtractorBoilerplateFiles = [
+  'tsconfig.json'
+];
+
+/**
+ * Run Protractor End-to-End Specs for Doc Samples
+ * Alias for 'run-e2e-tests'
+ */
+gulp.task('e2e', runE2e);
+
+gulp.task('run-e2e-tests', runE2e);
+
 /**
  * Run Protractor End-to-End Tests for Doc Samples
  *
  * Flags
  *   --filter to filter/select _example app subdir names
- *    e.g. gulp run-e2e-tests --filter=foo  // all example apps with 'foo' in their folder names.
+ *    e.g. gulp e2e --filter=foo  // all example apps with 'foo' in their folder names.
  *
  *    --fast by-passes the npm install and webdriver update
  *    Use it for repeated test runs (but not the FIRST run)
- *    e.g. gulp run-e2e-tests --fast
+ *    e.g. gulp e2e --fast
  *
  *   --lang to filter by code language
- *     e.g. gulp run-e2e-tests --lang=ts  // only TypeScript apps
+ *     e.g. gulp e2e --lang=ts  // only TypeScript apps
  *     default is (ts|js)
  *     all means (ts|js|dart)
  */
-gulp.task('run-e2e-tests', function() {
+function runE2e() {
   var promise;
   if (argv.fast) {
     // fast; skip all setup
     promise = Promise.resolve(true);
   } else  {
-    // Not 'fast'; do full setup
+    /*
+       // Not 'fast'; do full setup
     var spawnInfo = spawnExt('npm', ['install'], { cwd: EXAMPLES_PATH});
     promise = spawnInfo.promise.then(function() {
       copyExampleBoilerplate();
       spawnInfo = spawnExt('npm', ['run', 'webdriver:update'], {cwd: EXAMPLES_PATH});
       return spawnInfo.promise;
     });
-  }
+    */
+    // Not 'fast'; do full setup
+    gutil.log('runE2e: install _protractor stuff');
+    var spawnInfo = spawnExt('npm', ['install'], { cwd: EXAMPLES_PROTRACTOR_PATH});
+    promise = spawnInfo.promise
+      .then(function() {
+        gutil.log('runE2e: install _examples stuff');
+        spawnInfo = spawnExt('npm', ['install'], { cwd: EXAMPLES_PATH})
+        return spawnInfo.promise;
+      })
+      .then(function() {
+        copyExampleBoilerplate();
+        gutil.log('runE2e: update webdriver');
+        spawnInfo = spawnExt('npm', ['run', 'webdriver:update'], {cwd: EXAMPLES_PROTRACTOR_PATH});
+        return spawnInfo.promise;
+      });
+  };
+
+  var outputFile = path.join(process.cwd(), 'protractor-results.txt');
 
   promise.then(function() {
-    return findAndRunE2eTests(argv.filter);
+    return findAndRunE2eTests(argv.filter, outputFile);
   }).then(function(status) {
-    reportStatus(status);
+    reportStatus(status, outputFile);
     if (status.failed.length > 0){
       return Promise.reject('Some test suites failed');
     }
   }).catch(function(e) {
     gutil.log(e);
-    process.exit(1);
+    process.exitCode = 1;
   });
-});
+  return promise;
+}
 
 // finds all of the *e2e-spec.tests under the _examples folder along
 // with the corresponding apps that they should run under. Then run
 // each app/spec collection sequentially.
-function findAndRunE2eTests(filter) {
+function findAndRunE2eTests(filter, outputFile) {
+
+  // create an output file with header.
   var lang = (argv.lang || '(ts|js)').toLowerCase();
   if (lang === 'all') { lang = '(ts|js|dart)'; }
   var startTime = new Date().getTime();
-  // create an output file with header.
-  var outputFile = path.join(process.cwd(), 'protractor-results.txt');
-
   var header = `Doc Sample Protractor Results for ${lang} on ${new Date().toLocaleString()}\n`;
   header += argv.fast ?
     '  Fast Mode (--fast): no npm install, webdriver update, or boilerplate copy\n' :
     '  Slow Mode: npm install, webdriver update, and boilerplate copy\n';
   header += `  Filter: ${filter ? filter : 'All tests'}\n\n`;
-
   fs.writeFileSync(outputFile, header);
 
   // create an array of combos where each
   // combo consists of { examplePath: ... , protractorConfigFilename:  ... }
-  var exeConfigs = [];
+  var examplePaths = [];
   var e2eSpecPaths = getE2eSpecPaths(EXAMPLES_PATH);
-  var srcConfig = path.join(EXAMPLES_PATH, 'protractor.config.js');
-  e2eSpecPaths.forEach(function(specPath) {
+   e2eSpecPaths.forEach(function(specPath) {
     var destConfig = path.join(specPath, 'protractor.config.js');
-    fsExtra.copySync(srcConfig, destConfig);
     // get all of the examples under each dir where a pcFilename is found
-    examplePaths = getExamplePaths(specPath, true);
+    localExamplePaths = getExamplePaths(specPath, true);
     // Filter by language
-    examplePaths = examplePaths.filter(function (fn) {
+    localExamplePaths = localExamplePaths.filter(function (fn) {
       return fn.match('/'+lang+'$') != null;
     });
     if (filter) {
-      examplePaths = examplePaths.filter(function (fn) {
+      localExamplePaths = localExamplePaths.filter(function (fn) {
         return fn.match(filter) != null;
       })
     }
-    examplePaths.forEach(function(exPath) {
-      exeConfigs.push( { examplePath: exPath, protractorConfigFilename: destConfig });
+    localExamplePaths.forEach(function(examplePath) {
+      examplePaths.push(examplePath);
     })
   });
 
   // run the tests sequentially
   var status = { passed: [], failed: [] };
-  return exeConfigs.reduce(function (promise, combo) {
+  return examplePaths.reduce(function (promise, examplePath) {
     return promise.then(function () {
-      var isDart = combo.examplePath.indexOf('/dart') > -1;
+      var isDart = examplePath.indexOf('/dart') > -1;
       var runTests = isDart ? runE2eDartTests : runE2eTsTests;
-      return runTests(combo.examplePath, combo.protractorConfigFilename, outputFile).then(function(ok) {
+      return runTests(examplePath, outputFile).then(function(ok) {
         var arr = ok ? status.passed : status.failed;
-        arr.push(combo.examplePath);
+        arr.push(examplePath);
       })
     });
   }, Q.resolve()).then(function() {
     var stopTime = new Date().getTime();
     status.elapsedTime = (stopTime - startTime)/1000;
-    fs.appendFileSync(outputFile, '\nElaped Time: ' + status.elapsedTime + ' seconds');
     return status;
   });
 }
 
 // start the example in appDir; then run protractor with the specified
 // fileName; then shut down the example.  All protractor output is appended
 // to the outputFile.
-function runE2eTsTests(appDir, protractorConfigFilename, outputFile) {
+function runE2eTsTests(appDir, outputFile) {
   // start the app
   var appRunSpawnInfo = spawnExt('npm',['run','http-server:e2e', '--', '-s' ], { cwd: appDir });
   var tscRunSpawnInfo = spawnExt('npm',['run','tsc'], { cwd: appDir });
 
-  return runProtractor(tscRunSpawnInfo.promise, appDir, appRunSpawnInfo, protractorConfigFilename, outputFile);
+  return runProtractor(tscRunSpawnInfo.promise, appDir, appRunSpawnInfo, outputFile);
 }
 
-function runProtractor(prepPromise, appDir, appRunSpawnInfo, protractorConfigFilename, outputFile) {
+function runProtractor(prepPromise, appDir, appRunSpawnInfo, outputFile) {
   return prepPromise
     .catch(function(){
       var emsg = `AppDir failed during compile: ${appDir}\n\n`;
@@ -212,10 +240,10 @@ function runProtractor(prepPromise, appDir, appRunSpawnInfo, protractorConfigFil
     })
     .then(function (data) {
       // start protractor
-      var pcFilename = path.resolve(protractorConfigFilename); // need to resolve because we are going to be running from a different dir
-      var spawnInfo = spawnExt('npm', [ 'run', 'protractor', '--', pcFilename, 
-        '--params.appDir=' + appDir, '--params.outputFile=' + outputFile], { cwd: EXAMPLES_PATH });
-      return spawnInfo.promise
+      var specFilename = path.resolve(`${appDir}/../e2e-spec.ts`);
+      var spawnInfo = spawnExt('npm', [ 'run', 'protractor', '--', 'protractor.config.js',
+        `--specs=${specFilename}`, '--params.appDir=' + appDir, '--params.outputFile=' + outputFile], { cwd: EXAMPLES_PROTRACTOR_PATH });
+      return spawnInfo.promise;
     })
     .then(
        function() { return finish(true);},
@@ -233,7 +261,7 @@ function runProtractor(prepPromise, appDir, appRunSpawnInfo, protractorConfigFil
 // start the server in appDir/build/web; then run protractor with the specified
 // fileName; then shut down the example.  All protractor output is appended
 // to the outputFile.
-function runE2eDartTests(appDir, protractorConfigFilename, outputFile) {
+function runE2eDartTests(appDir, outputFile) {
   var deployDir = path.resolve(path.join(appDir, 'build/web'));
   gutil.log('AppDir for Dart e2e: ' + appDir);
   gutil.log('Deploying from: ' + deployDir);
@@ -247,24 +275,28 @@ function runE2eDartTests(appDir, protractorConfigFilename, outputFile) {
   var prepPromise = pubUpgradeSpawnInfo.promise.then(function (data) {
     return spawnExt('pub', ['build'], { cwd: appDir }).promise;
   });
-  return runProtractor(prepPromise, appDir, appRunSpawnInfo, protractorConfigFilename, outputFile);
+  return runProtractor(prepPromise, appDir, appRunSpawnInfo, outputFile);
 }
 
-function reportStatus(status) {
-  gutil.log('Suites passed:');
+function reportStatus(status, outputFile) {
+  var log = [''];
+  log.push('Suites passed:');
   status.passed.forEach(function(val) {
-    gutil.log('  ' + val);
+    log.push('  ' + val);
   });
 
   if (status.failed.length == 0) {
-    gutil.log('All tests passed');
+    log.push('All tests passed');
   } else {
-    gutil.log('Suites failed:');
+    log.push('Suites failed:');
     status.failed.forEach(function (val) {
-      gutil.log('  ' + val);
+      log.push('  ' + val);
     });
   }
-  gutil.log('Elapsed time: ' +  status.elapsedTime + ' seconds');
+  log.push('\nElapsed time: ' +  status.elapsedTime + ' seconds');
+  var log = log.join('\n');
+  gutil.log(log);
+  fs.appendFileSync(outputFile, log);
 }
 
 // returns both a promise and the spawned process so that it can be killed if needed.
@@ -312,7 +344,7 @@ gulp.task('help', taskListing.withFilters(function(taskName) {
   return shouldRemove;
 }));
 
-// requires admin access
+// requires admin access because it adds symlinks
 gulp.task('add-example-boilerplate', function() {
   var realPath = path.join(EXAMPLES_PATH, '/node_modules');
   var nodeModulesPaths = getNodeModulesPaths(EXAMPLES_PATH);
@@ -332,11 +364,18 @@ gulp.task('add-example-boilerplate', function() {
   return copyExampleBoilerplate();
 });
 
+
+// copies boilerplate files to locations
+// where an example app is found
+gulp.task('_copy-example-boilerplate', copyExampleBoilerplate);
+
+
 // copies boilerplate files to locations
 // where an example app is found
 // also copies certain web files (e.g., styles.css) to ~/_examples/**/dart/**/web
 // also copies protractor.config.js file
 function copyExampleBoilerplate() {
+  gutil.log('Copying example boilerplate files');
   var sourceFiles = _exampleBoilerplateFiles.map(function(fn) {
     return path.join(EXAMPLES_PATH, fn);
   });
@@ -351,12 +390,14 @@ function copyExampleBoilerplate() {
     .then(function() {
       return copyFiles(dartWebSourceFiles, dartExampleWebPaths);
     })
-    // copy protractor.config.js from _examples dir to each subdir that
+    // copy files from _examples/_protractor dir to each subdir that
     // contains a e2e-spec file.
     .then(function() {
-      var sourceFiles = [ path.join(EXAMPLES_PATH, 'protractor.config.js') ];
+      var protractorSourceFiles =
+        _exampleProtractorBoilerplateFiles
+          .map(function(name) {return path.join(EXAMPLES_PROTRACTOR_PATH, name);});;
       var e2eSpecPaths = getE2eSpecPaths(EXAMPLES_PATH);
-      return copyFiles(sourceFiles, e2eSpecPaths);
+      return copyFiles(protractorSourceFiles, e2eSpecPaths);
     });
 }
 
@@ -371,6 +412,15 @@ gulp.task('remove-example-boilerplate', function() {
     fsUtils.removeSymlink(linkPath);
   });
 
+  deleteExampleBoilerPlate();
+});
+
+// deletes boilerplate files that were added by copyExampleBoilerplate
+// from locations where an example app is found
+gulp.task('_delete-example-boilerplate', deleteExampleBoilerPlate);
+
+function deleteExampleBoilerPlate() {
+  gutil.log('Deleting example boilerplate files');
   var examplePaths = getExamplePaths(EXAMPLES_PATH);
   var dartExampleWebPaths = getDartExampleWebPaths(EXAMPLES_PATH);
 
@@ -379,10 +429,11 @@ gulp.task('remove-example-boilerplate', function() {
       return deleteFiles(_exampleDartWebBoilerPlateFiles, dartExampleWebPaths);
     })
     .then(function() {
+      var protractorFiles = _exampleProtractorBoilerplateFiles;
       var e2eSpecPaths = getE2eSpecPaths(EXAMPLES_PATH);
-      return deleteFiles(['protractor.config.js'], e2eSpecPaths);
-    })
-});
+      return deleteFiles(protractorFiles, e2eSpecPaths);
+    });
+}
 
 gulp.task('serve-and-sync', ['build-docs'], function (cb) {
   // watchAndSync({devGuide: true, apiDocs: true, apiExamples: true, localFiles: true}, cb);
@@ -744,7 +795,7 @@ function deleteFiles(baseFileNames, destPaths) {
 // TODO: filter out all paths that are subdirs of another
 // path in the result.
 function getE2eSpecPaths(basePath) {
-  var paths = getPaths(basePath, '*e2e-spec.js', true);
+  var paths = getPaths(basePath, '*e2e-spec.+(js|ts)', true);
   return _.uniq(paths);
 }
 

public/docs/_examples/_protractor/e2e.d.ts

@@ -0,0 +1,14 @@
+/// <reference path="typings/index.d.ts" />
+
+// Defined in protractor.config.js
+declare function setProtractorToNg1Mode(): void;
+declare function sendKeys(element: protractor.ElementFinder, str: string): webdriver.promise.Promise<void>;
+declare function describeIf(cond: boolean, name: string, func: Function): void;
+declare function itIf(cond: boolean, name: string, func: Function): void;
+
+declare namespace protractor {
+  interface IBrowser {
+    appIsTs: boolean;
+    appIsJs: boolean;
+  }
+}

public/docs/_examples/_protractor/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "angular2-examples-protractor",
+  "version": "1.0.0",
+  "description": "Manage _protractor folder installations",
+  "scripts": {
+    "postinstall": "typings install",
+    "typings": "typings",
+    "protractor": "protractor",
+    "webdriver:update": "webdriver-manager update"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "protractor": "^3.3.0",
+    "typings": "^1.0.4"
+  },
+  "repository": {}
+}