From 4f710d2c8c1786d46e1248d1366962f596608cee Mon Sep 17 00:00:00 2001 From: Sammy Jelin Date: Tue, 7 Feb 2017 14:50:35 -0800 Subject: [PATCH] chore(docs): Document disabling the control flow * Added information about `SELENIUM_PROMISE_MANAGER` to `docs/control-flow.md`, including pointing to `/spec/ts/` for examples * Added `docs/async-await.md`, which redirects to `exampleTypescript/asyncAwait/README.md`. * Updated `exampleTypescript/asyncAwait/README.md`, including pointing to `/spec/ts/` for more examples. * Added `docs/typescript.md`, which redirects to `/exampleTypescript/`. * Added information about `@types/jasminewd2` to `exampleTypescript/README.md`. Website updates to come in a future change. Closes https://github.com/angular/protractor/issues/3692. --- docs/async-await.md | 4 +++ docs/control-flow.md | 16 ++++++++++++ docs/typescript.md | 4 +++ exampleTypescript/README.md | 7 ++++- exampleTypescript/asyncAwait/README.md | 36 +++++++++++++------------- exampleTypescript/asyncAwait/conf.ts | 3 ++- exampleTypescript/package.json | 1 + exampleTypescript/tsconfig.json | 3 +-- 8 files changed, 52 insertions(+), 22 deletions(-) create mode 100644 docs/async-await.md create mode 100644 docs/typescript.md diff --git a/docs/async-await.md b/docs/async-await.md new file mode 100644 index 000000000..e4ecd2e57 --- /dev/null +++ b/docs/async-await.md @@ -0,0 +1,4 @@ +`async`/`await` +=============== + +Please see [our TypeScript examples which use `async`/`await`](/exampleTypescript/asyncAwait/). diff --git a/docs/control-flow.md b/docs/control-flow.md index 4d8c9e65e..08f6f0973 100644 --- a/docs/control-flow.md +++ b/docs/control-flow.md @@ -6,6 +6,22 @@ which are managed by a [control flow](https://github.com/SeleniumHQ/selenium/wik and adapted for [Jasmine](http://jasmine.github.io/2.3/introduction.html). A short summary about how Protractor interacts with the control flow is presented below. +Disabling the Control Flow +-------------------------- + +In the future, the control flow is being removed (see +[SeleniumHQ's github issue](https://github.com/SeleniumHQ/selenium/issues/2969) +for details). To disable the control flow in your tests, you can use the +`SELENIUM_PROMISE_MANAGER: false` [config option](/lib/config.ts#L644). + +Instead of the control flow, you can synchronize your commands +with promise chaining or the upcomming ES7 feature `async`/`await`. See +[`/spec/ts/`](/spec/ts/) for examples of tests with the control flow disabled. + +Because `async`/`await` uses native promises, it will make the Control Flow +unreliable. As such, if you're writing a library or plugin which needs to work +whether or not the Control Flow is enabled, you'll need to handle +synchronization using promise chaining. Promises and the Control Flow ----------------------------- diff --git a/docs/typescript.md b/docs/typescript.md new file mode 100644 index 000000000..81c896d36 --- /dev/null +++ b/docs/typescript.md @@ -0,0 +1,4 @@ +TypeScript +========== + +Please see [our TypeScript examples](/exampleTypescript/). diff --git a/exampleTypescript/README.md b/exampleTypescript/README.md index 48b33153b..288a110e3 100644 --- a/exampleTypescript/README.md +++ b/exampleTypescript/README.md @@ -65,8 +65,13 @@ export let config: Config = { ## Ambient typings -Protractor also uses ambient types including jasmine and node. These are brought in via the `tsconfig.json` file, which uses npm module resolution to get types from `node_modules/@types`. +Protractor also uses ambient types including jasmine, jasminewd2, and node. These are brought in via the `tsconfig.json` file, which uses npm module resolution to get types from `node_modules/@types`. +If you are using the jasmine framework for your tests, make sure to do: + +``` +npm install --save-dev @types/jasmine @types/jasminewd2 +``` ## Compiling your code diff --git a/exampleTypescript/asyncAwait/README.md b/exampleTypescript/asyncAwait/README.md index 2c482e5ed..abea7f149 100644 --- a/exampleTypescript/asyncAwait/README.md +++ b/exampleTypescript/asyncAwait/README.md @@ -2,28 +2,28 @@ =============================================== The Web Driver Control Flow is used to synchronize your commands so they reach -the browser in the correct order (see [control-flow.md]( -../../docs/control-flow.md) for details). In the future, the control flow is -being removed, however (see [github issue]( -https://github.com/SeleniumHQ/selenium/issues/2969) for details). Instead of -the control flow, you can synchronize your commands with promise chaining or the -upcomming ES7 feature `async`/`await`. However, you cannot use a mix of -`async`/`await` and the control flow: `async`/`await` causes the control flow to -become unreliable (see [github issue]( -https://github.com/SeleniumHQ/selenium/issues/3037)). So if you `async`/`await` -anywhere in a spec, you should use `await` or promise chaining to handle all -asynchronous activity (e.g. any command interacting with the browser) for the -rest of that test. - -In the near future there will be an option to disable the Web Driver control -flow entierly (see https://github.com/angular/protractor/issues/3691). If you -are using `async`/`await`, it is highly recommended that you disable the Web -Driver control flow. +the browser in the correct order (see +[/docs/control-flow.md](/docs/control-flow.md) for details). In the future, the +control flow is being removed (see [SeleniumHQ's github issue]( +https://github.com/SeleniumHQ/selenium/issues/2969) for details). Instead of the +control flow, you can synchronize your commands with promise chaining or the +upcomming ES7 feature `async`/`await`. +However, you cannot use a mix of `async`/`await` and the control flow: +`async`/`await` causes the control flow to become unreliable (see +[github issue]( https://github.com/SeleniumHQ/selenium/issues/3037)). So if you +`async`/`await` anywhere in a spec, you should use the +`SELENIUM_PROMISE_MANAGER: false` [config option](/lib/config.ts#L644). Compiling `async`/`await` syntax ================================ `async`/`await` syntax is currently accessible via typescript if you compile -using `tsc -t ES2015 `. You can also compile it using [regenerator]( +using `--target ES2015` or above. You can also compile it using [regenerator]( https://github.com/facebook/regenerator). + + +More Examples +============= + +More examples can be found under [`/spec/ts/`](/../../spec/ts). diff --git a/exampleTypescript/asyncAwait/conf.ts b/exampleTypescript/asyncAwait/conf.ts index 14d32e8a1..e73e026c3 100644 --- a/exampleTypescript/asyncAwait/conf.ts +++ b/exampleTypescript/asyncAwait/conf.ts @@ -11,5 +11,6 @@ export let config: Config = { browserName: 'chrome' }, specs: [ 'spec.js' ], - seleniumAddress: 'http://localhost:4444/wd/hub' + seleniumAddress: 'http://localhost:4444/wd/hub', + SELENIUM_PROMISE_MANAGER: false }; diff --git a/exampleTypescript/package.json b/exampleTypescript/package.json index d01641fd6..117506c1e 100644 --- a/exampleTypescript/package.json +++ b/exampleTypescript/package.json @@ -11,6 +11,7 @@ }, "dependencies": { "@types/jasmine": "^2.5.38", + "@types/jasminewd2": "^2.0.0", "jasmine": "^2.4.1", "protractor": "file:../", "typescript": "~2.0.0" diff --git a/exampleTypescript/tsconfig.json b/exampleTypescript/tsconfig.json index aa7469576..8b088c60e 100644 --- a/exampleTypescript/tsconfig.json +++ b/exampleTypescript/tsconfig.json @@ -6,8 +6,7 @@ "sourceMap": false, "declaration": false, "noImplicitAny": false, - "outDir": "tmp", - "types": ["node", "jasmine"] + "outDir": "tmp" }, "exclude": [ "node_modules",