Document re-org

docs/acceptance.md

@@ -2,16 +2,13 @@
 
 How does your client, manager, or tester, or any other non-technical person, know your web application is working? By opening the browser, accessing a site, clicking on links, filling in the forms, and actually seeing the content on a web page.
 
-Acceptance (also called End to End) tests can cover standard but complex scenarios from a user's perspective. With acceptance tests you can be confident that users, following all defined scenarios, won't get errors. We check **not just functionality of application but a user interface** (UI) as well.
+*Acceptance tests* (also called *End-to-End tests*) can cover standard but complex scenarios from a user's perspective. With acceptance tests you can be confident that users, following all defined scenarios, won't get errors. We check **not just functionality of application but a user interface** (UI) as well.
 
-By default CodeceptJS uses [WebDriver](/helpers/WebDriver/) helper and **Selenium** to automate browser. Within web page you can locate elements, interact with them, and check that expected elements are present on a page.
-However, you can also choose [Nightmare](/helpers/Nightmare) or [Protractor](/helpers/Protractor) helpers, driven by corresponding libraries.
-No matter of helper and library you use for acceptance testing, CodeceptJS should execute same actions in similar manner.
+No matter of helper and driver you use for acceptance testing, CodeceptJS should execute same actions in similar manner.
 
-In case of CodeceptJS you can be sure that in code it will be as easy as it sounds. You just describe a test scenario with JavaScript DSL and allow the framework to handle the rest.
+In case of CodeceptJS you can be sure that in code it will be as easy as it sounds. You just describe a test scenario with JavaScript and allow the framework to handle the rest.
 
 Within web page you can locate elements, interact with them, and check that expected elements are present on a page. That is what a test look like.
-That is what a test look like.
 
 ```js
 I.amOnPage('/login');
@@ -21,7 +18,7 @@ I.click('Login');
 I.see('Welcome, John');
 ```
 
-This is how we can check that login form of a simple web application works. At first we opened `/login` page, then filled forms and in the end we saw the greetings text.
+This is how we can check that login form of a simple web application works. At first we opened the `/login` page, then filled in form fields, clicked a button, and in the end we check that we saw the greeting text.
 
 ## Locating Element
 
@@ -50,7 +47,7 @@ I.seeElement({name: 'password'});
 I.seeElement({id: 'users'});
 ```
 
-In [mobile testing](http://codecept.io/mobile/#locating-elements) you can use `~` to specify accessibility id to locate an element. In web application you can locate element by their `aria-label` value.
+In [mobile testing](mobile.md#locating-elements) you can use `~` to specify accessibility id to locate an element. In web application you can locate element by their `aria-label` value.
 
 ```js
 // locate element by [aria-label] attribute in web
@@ -247,7 +244,7 @@ If it's hard to define what to wait, it is recommended to use [retries](https://
 
 ## IFrames
 
-[within](/basics/#within) operator can be used to work inside IFrames. Special `frame` locator is required to locate the iframe and get into its context.
+[within](locators.md#within) operator can be used to work inside IFrames. Special `frame` locator is required to locate the iframe and get into its context.
 
 See example:
 
@@ -265,80 +262,9 @@ within({frame: [".content", "#editor"]}, () => {
 });
 ```
 
-## Multiple Sessions
-
-CodeceptJS allows to run several browser sessions inside a test. This can be useful for testing communication between users inside a system, for instance in chats. To open another browser use `session()` function as shown in example:
-
-```js
-Scenario('test app', (I) => {
-  I.amOnPage('/chat');
-  I.fillField('name', 'davert');
-  I.click('Sign In');
-  I.see('Hello, davert');
-  session('john', () => {
-    // another session started
-    I.amOnPage('/chat');
-    I.fillField('name', 'john');
-    I.click('Sign In');
-    I.see('Hello, john');
-  });
-  // switching back to default session
-  I.fillField('message', 'Hi, john');
-  // there is a message from current user
-  I.see('me: Hi, john', '.messages');
-  session('john', () => {
-    // let's check if john received it
-    I.see('davert: Hi, john', '.messages');
-  });
-});
-```
-
-`session` function expects a first parameter to be a name of a session. You can switch back to session by using the same name.
-
-You can override config for session by passing second parameter:
-
-```js
-session('john', { browser: 'firefox' } , () => {
-  // run this steps in firefox
-  I.amOnPage('/');
-});
-```
-
-or just start session without switching to it. Call `session` passing only its name:
-
-```js
-Scenario('test', (I) => {
-  // opens 3 additional browsers
-  session('john');
-  session('mary');
-  session('jane');
-
-  I.amOnPage('/');
-
-  // switch to session by its name
-  session('mary', () => {
-    I.amOnPage('/login');
-  });
-}
-```
-`session` can return value which can be used in scenario:
-
-```js
-// inside async function
-const val = await session('john', () => {
-  I.amOnPage('/info');
-  return I.grabTextFrom({ css: 'h1' });
-});
-I.fillField('Description', val);
-```
-
-Function passed into session can use `I`, page objects, and any objects declared for the scenario.
-This function can also be declared as async (but doesn't work as generator).
-
-Also, you can use `within` inside a session but you can't call session from inside `within`.
 
 ---
 
-### done()
+### Next: [BDD Testing >>>](bdd.md)
 
-CodeceptJS through helpers provides user friendly API to interact with a webpage. In this section we described using WebDriver helper which allows to control browser through Selenium WebDriver.
+---