Overview spelling, punctuation fixes (#1156)

* Passed text through spellchecker to identify & fix mistakes

I fixed the mistakes identified by the advanced spell-checker Grammarly.

* Update details.en.md

Passed through spell checker to fix errors and improve structure.

* New headings, grammar/punctuation fixes

Added new headings to very long text on page object models help.
Fixed spelling, grammar, and punctuation errors.

* Update fresh_browser_per_test.en.md

Added a comma to the first senctence

* Removed mistakenly duplicated paragraph

Author: naeemakram

website_and_docs/content/documentation/overview/_index.en.md

@@ -1,5 +1,5 @@
 ---
-title: "Selenium overview"
+title: "Selenium Overview"
 linkTitle: "Overview"
 weight: 2
 description: >
@@ -15,10 +15,10 @@ but it composes many tools.
 
 If you are beginning with desktop website or mobile website test automation, then you
 are going to be using WebDriver APIs. [WebDriver](/documentation/webdriver)
-uses browser automation APIs provided by browser vendors to control browser and
+uses browser automation APIs provided by browser vendors to control the browser and
 run tests. This is as if a real user is operating the browser. Since
 WebDriver does not require its API to be compiled with application
-code, it is not intrusive. Hence, you are testing the
+code; It is not intrusive. Hence, you are testing the
 same application which you push live.
 
 
@@ -41,6 +41,6 @@ when the test cases are triggered, they are automatically
 executed by the remote end.
 
 After the development of the WebDriver tests, you may face 
-the need of running your tests on multiple browser and 
+the need to run your tests on multiple browsers and 
 operating system combinations.
 This is where [Grid](/documentation/grid) comes into the picture.

website_and_docs/content/documentation/overview/components.en.md

@@ -9,41 +9,41 @@ aliases: [
 ---
 
 Building a test suite using WebDriver will require you to understand and 
-effectively use a number of different components. As with everything in 
+effectively use several components. As with everything in 
 software, different people use different terms for the same idea. Below is
 a breakdown of how terms are used in this description.
 
 ### Terminology
 
 * **API:** Application Programming Interface. This is the set of "commands" 
 you use to manipulate WebDriver.
-* **Library:** A code module which contains the APIs and the code necessary
+* **Library:** A code module that contains the APIs and the code necessary
 to implement them. Libraries are specific to each language binding, eg .jar 
 files for Java, .dll files for .NET, etc.
 * **Driver:** Responsible for controlling the actual browser. Most drivers 
 are created by the browser vendors themselves. Drivers are generally 
 executable modules that run on the system with the browser itself,
-not on the system executing the test suite. (Although those may be the 
+not the system executing the test suite. (Although those may be the 
 same system.) NOTE: _Some people refer to the drivers as proxies._
-* **Framework:** An additional library used as a support for WebDriver 
+* **Framework:** An additional library that is used as a support for WebDriver 
 suites. These frameworks may be test frameworks such as JUnit or NUnit. 
 They may also be frameworks supporting natural language features such 
 as Cucumber or Robotium. Frameworks may also be written and used for 
-things such as manipulating or configuring the system under test, data 
+tasks such as manipulating or configuring the system under test, data 
 creation, test oracles, etc.
 
 
 ### The Parts and Pieces
 At its minimum, WebDriver talks to a browser through a driver. Communication
-is two way: WebDriver passes commands to the browser through the driver, and 
+is two-way: WebDriver passes commands to the browser through the driver, and 
 receives information back via the same route.
 
 {{< figure src="/images/documentation/webdriver/basic_comms.png" class="img-responsive text-center" alt="Basic Communication">}}
 
 The driver is specific to the browser, such as ChromeDriver for Google's 
 Chrome/Chromium, GeckoDriver for Mozilla's Firefox, etc. The driver runs on 
-the same system as the browser. This may, or may not be, the same system where 
-the tests themselves are executing.
+the same system as the browser. This may or may not be the same system where 
+the tests themselves are executed.
 
 This simple example above is _direct_ communication. Communication to the 
 browser may also be _remote_ communication through Selenium Server or 
@@ -64,8 +64,8 @@ of the methods above. WebDriver does not know a thing about testing: it does not
 know how to compare things, assert pass or fail, and it certainly does not know
 a thing about reporting or Given/When/Then grammar.
 
-This is where various frameworks come in to play. At a minimum you will need a 
-test framework that matches the language bindings, e.g. NUnit for .NET, JUnit 
+This is where various frameworks come into play. At a minimum, you will need a 
+test framework that matches the language bindings, e.g., NUnit for .NET, JUnit 
 for Java, RSpec for Ruby, etc.
 
 The test framework is responsible for running and executing your WebDriver 
@@ -76,4 +76,4 @@ to the following image.
 
 Natural language frameworks/tools such as Cucumber may exist as part of that 
 Test Framework box in the figure above, or they may wrap the Test Framework 
-entirely in their own implementation.
+entirely in their custom implementation.

website_and_docs/content/documentation/overview/details.en.md

@@ -19,29 +19,29 @@ that uses the best techniques available
 to remotely control browser instances
 and emulate a user's interaction with the browser.
 
-It allows users to simulate common activities performed by end-users;
+Selenium allows users to simulate common activities performed by end-users;
 entering text into fields,
 selecting drop-down values and checking boxes,
 and clicking links in documents.
 It also provides many other controls such as mouse movement,
 arbitrary JavaScript execution, and much more.
 
 Although used primarily for front-end testing of websites,
-Selenium is at its core a browser user agent _library_.
+Selenium is, at its core, a browser user agent _library_.
 The interfaces are ubiquitous to their application,
-which encourages composition with other libraries to suit your purpose.
+encouraging composition with other libraries to suit your purpose.
 
 
 ### One interface to rule them all
 
 One of the project's guiding principles
 is to support a common interface for all (major) browser technologies.
 Web browsers are incredibly complex, highly engineered applications,
-performing their operations in completely different ways
+performing their operations in entirely different ways
 but which frequently look the same while doing so.
 Even though the text is rendered in the same fonts,
 the images are displayed in the same place
-and the links take you to the same destination.
+, and the links take you to the same destination.
 What is happening underneath is as different as night and day.
 Selenium “abstracts” these differences,
 hiding their details and intricacies from the person writing the code.
@@ -84,9 +84,9 @@ As it has grown in popularity, so have its requirements and challenges multiplie
 As the web becomes more complicated
 and new technologies are added to websites,
 it's the mission of this project to keep up with them where possible.
-Being an open source project,
+Being an open-source project,
 this support is provided through the generous donation of time from many volunteers,
-every one of which has a “day job”.
+every one of which has a “day job.”
 
 Another mission of the project is to encourage
 more volunteers to partake in this effort,

website_and_docs/content/documentation/test_practices/_index.en.md

@@ -8,18 +8,18 @@ description: >
 
 A note on "Best Practices": We've intentionally avoided the phrase "Best
 Practices" in this documentation. No one approach works for all situations.
-We prefer the idea of "Guidelines and Recommendations". We encourage
+We prefer the idea of "Guidelines and Recommendations." We encourage
 you to read through these and thoughtfully decide what approaches
 will work for you in your particular environment.
 
-Functional testing is difficult to get right for many reasons.
+Functional testing is challenging to get right for many reasons.
 As if application state, complexity, and dependencies do not make testing difficult enough,
 dealing with browsers (especially with cross-browser incompatibilities)
 makes writing good tests a challenge.
 
 Selenium provides tools to make functional user interaction easier,
 but does not help you write well-architected test suites.
-In this chapter we offer advice, guidelines, and recommendations
+In this chapte, we offer advice, guidelines, and recommendations
 on how to approach functional web page automation.
 
 This chapter records software design patterns popular

website_and_docs/content/documentation/test_practices/encouraged/avoid_sharing_state.en.md

@@ -9,12 +9,12 @@ aliases: [
 ---
 
 
-Although mentioned in several places it is worth mentioning again. Ensure 
-tests are isolated from one another.
+Although mentioned in several places, it is worth mentioning again. 
+We must ensure that the tests are isolated from one another.
 
 * Do not share test data. Imagine several tests that each query the database 
 for valid orders before picking one to perform an action on. Should two tests
-pick up the same order you are likely to get unexpected behaviour.
+pick up the same order you are likely to get unexpected behavior.
 
 * Clean up stale data in the application that might be picked up by another 
 test e.g. invalid order records.

website_and_docs/content/documentation/test_practices/encouraged/fresh_browser_per_test.en.md

@@ -8,7 +8,7 @@ aliases: [
 ]
 ---
 
-Start each test from a clean known state.
+Start each test from a clean, known state.
 Ideally, spin up a new virtual machine for each test.
 If spinning up a new virtual machine is not practical,
 at least start a new WebDriver for each test.

website_and_docs/content/documentation/test_practices/encouraged/page_object_models.en.md

@@ -13,33 +13,33 @@ the [Selenium wiki](https://github.com/SeleniumHQ/selenium/wiki/PageObjects)
 
 ## Overview
 
-Within your web app's UI there are areas that your tests interact with. 
-A Page Object simply models these as objects within the test code. 
+Within your web app's UI, there are areas where your tests interact with. 
+A Page Object only models these as objects within the test code. 
 This reduces the amount of duplicated code and means that if the UI changes, 
-the fix need only be applied in one place.
+the fix needs only to be applied in one place.
 
-Page Object is a Design Pattern which has become popular in test automation for
+Page Object is a Design Pattern that has become popular in test automation for
 enhancing test maintenance and reducing code duplication. A page object is an
 object-oriented class that serves as an interface to a page of your AUT. The
 tests then use the methods of this page object class whenever they need to
 interact with the UI of that page. The benefit is that if the UI changes for
 the page, the tests themselves don’t need to change, only the code within the
-page object needs to change. Subsequently all changes to support that new UI
+page object needs to change. Subsequently, all changes to support that new UI
 are located in one place.
 
 ### Advantages
 
-* There is a clean separation between test code and page specific code such as
+* There is a clean separation between the test code and page-specific code, such as
   locators (or their use if you’re using a UI Map) and layout.
-* There is a single repository for the services or operations offered by the page
+* There is a single repository for the services or operations the page offers
   rather than having these services scattered throughout the tests.
 
-In both cases this allows any modifications required due to UI changes to all
-be made in one place. Useful information on this technique can be found on
+In both cases, this allows any modifications required due to UI changes to all
+be made in one place. Helpful information on this technique can be found on
 numerous blogs as this ‘test design pattern’ is becoming widely used. We
-encourage the reader who wishes to know more to search the internet for blogs
+encourage readers who wish to know more to search the internet for blogs
 on this subject. Many have written on this design pattern and can provide
-useful tips beyond the scope of this user guide. To get you started, though,
+helpful tips beyond the scope of this user guide. To get you started,
 we’ll illustrate page objects with a simple example.
 
 ### Examples
@@ -178,6 +178,7 @@ There is a lot of flexibility in how the page objects may be designed, but
 there are a few basic rules for getting the desired maintainability of your
 test code.
 
+## Assertions in Page Objects
 Page objects themselves should never make verifications or assertions. This is
 part of your test and should always be within the test’s code, never in an page
 object. The page object will contain the representation of the page, and the
@@ -191,6 +192,7 @@ instantiating the page object. In the examples above, both the SignInPage and
 HomePage constructors check that the expected page is available and ready for
 requests from the test.
 
+## Page Component Objects
 A page object does not necessarily need to represent all the parts of a
 page itself. The same principles used for page objects can be used to
 create "Page _Component_ Objects" that represent discrete chunks of the
@@ -202,6 +204,7 @@ pages. If a page in the AUT has multiple components, or common
 components used throughout the site (e.g. a navigation bar), then it
 may improve maintainability and reduce code duplication.
 
+## Other Design Patterns Used in Testing
 There are other design patterns that also may be used in testing. Some use a
 Page Factory for instantiating their page objects. Discussing all of these is
 beyond the scope of this user guide. Here, we merely want to introduce the
@@ -211,11 +214,12 @@ reader to search for blogs on these topics.
 
 ## Implementation Notes
 
-PageObjects can be thought of as facing in two directions simultaneously. Facing towards the developer of a test, they represent the **services** offered by a particular page. Facing away from the developer, they should be the only thing that has a deep knowledge of the structure of the HTML of a page (or part of a page) It's simplest to think of the methods on a Page Object as offering the "services" that a page offers rather than exposing the details and mechanics of the page. As an example, think of the inbox of any web-based email system. Amongst the services that it offers are typically the ability to compose a new email, to choose to read a single email, and to list the subject lines of the emails in the inbox. How these are implemented shouldn't matter to the test.
 
-Because we're encouraging the developer of a test to try and think about the services that they're interacting with rather than the implementation, PageObjects should seldom expose the underlying WebDriver instance. To facilitate this, methods on the PageObject should return other PageObjects. This means that we can effectively model the user's journey through our application. It also means that should the way that pages relate to one another change (like when the login page asks the user to change their password the first time they log into a service, when it previously didn't do that) simply changing the appropriate method's signature will cause the tests to fail to compile. Put another way, we can tell which tests would fail without needing to run them when we change the relationship between pages and reflect this in the PageObjects.
+PageObjects can be thought of as facing in two directions simultaneously. Facing toward the developer of a test, they represent the **services** offered by a particular page. Facing away from the developer, they should be the only thing that has a deep knowledge of the structure of the HTML of a page (or part of a page) It's simplest to think of the methods on a Page Object as offering the "services" that a page offers rather than exposing the details and mechanics of the page. As an example, think of the inbox of any web-based email system. Amongst the services it offers are the ability to compose a new email, choose to read a single email, and list the subject lines of the emails in the inbox. How these are implemented shouldn't matter to the test.
 
-One consequence of this approach is that it may be necessary to model (for example) both a successful and unsuccessful login, or a click could have a different result depending on the state of the app. When this happens, it is common to have multiple methods on the PageObject:
+Because we're encouraging the developer of a test to try and think about the services they're interacting with rather than the implementation, PageObjects should seldom expose the underlying WebDriver instance. To facilitate this, methods on the PageObject should return other PageObjects. This means we can effectively model the user's journey through our application. It also means that should the way that pages relate to one another change (like when the login page asks the user to change their password the first time they log into a service when it previously didn't do that), simply changing the appropriate method's signature will cause the tests to fail to compile. Put another way; we can tell which tests would fail without needing to run them when we change the relationship between pages and reflect this in the PageObjects.
+
+One consequence of this approach is that it may be necessary to model (for example) both a successful and unsuccessful login; or a click could have a different result depending on the app's state. When this happens, it is common to have multiple methods on the PageObject:
 
 ```
 public class LoginPage {
@@ -253,9 +257,9 @@ public void testMessagesAreReadOrUnread() {
 }
 ```
 
-Of course, as with every guideline there are exceptions, and one that is commonly seen with PageObjects is to check that the WebDriver is on the correct page when we instantiate the PageObject. This is done in the example below.
+Of course, as with every guideline, there are exceptions, and one that is commonly seen with PageObjects is to check that the WebDriver is on the correct page when we instantiate the PageObject. This is done in the example below.
 
-Finally, a PageObject need not represent an entire page. It may represent a section that appears many times within a site or page, such as site navigation. The essential principle is that there is only one place in your test suite with knowledge of the structure of the HTML of a particular (part of a) page.
+Finally, a PageObject need not represent an entire page. It may represent a section that appears frequently within a site or page, such as site navigation. The essential principle is that there is only one place in your test suite with knowledge of the structure of the HTML of a particular (part of a) page.
 
 ## Summary
 
@@ -343,4 +347,4 @@ public class LoginPage {
 
 ## Support in WebDriver
 
-There is a PageFactory in the support package that provides support for this pattern, and helps to remove some boiler-plate code from your Page Objects at the same time.
+There is a PageFactory in the support package that provides support for this pattern and helps to remove some boiler-plate code from your Page Objects at the same time.