Proofread

README.md

@@ -2,31 +2,32 @@
 
 ## Requirements
 
-In this series of exercises we're going to run several automated tests against web application. To do
+In this series of exercises we're going to run several automated tests against a web application. To do
 that we're going to need to have the following items installed:
 
 - Python (version 3.7 or newer): https://www.python.org/downloads/
   - Remember to add Python folder to PATH environment variable.
 - Pip for Python 3
   - Windows: https://www.howtogeek.com/197947/how-to-install-python-on-windows/
   - Linux: `sudo apt-get install python3-pip && pip3 install --upgrade pip`
-  - macOS: `brew install python` pip is already included
+  - macOS: `brew install python` (pip is already included)
 - Node.js (version 12 or newer): https://nodejs.org/en/download/
 - System under test
   - Open a new terminal window, change directory to this repository root folder and run the application
     with: `python server/server.py`
 
 ### Recommended
 
-- In order to make installing with pip easier, use virtualenv (https://virtualenv.pypa.io/en/latest/)
-  - Short instruction to virtualenv use
+#### Use Virtualenv
+[VirtualEnv](https://virtualenv.pypa.io/en/latest/) creates a dependency "sandbox", keeping the rest of your computer clean from any dependencies you install during this tutorial. 
 
-    ```shell
-    pip install virtualenv --user
-    virtualenv <choose_a_folder_name>
-    source <chosen_folder_name>/bin/activate
-    ```
+```shell
+cd <path to repo>
+pip install virtualenv --user
+virtualenv . # initialize a virtual environment in the current folder
+source ./bin/activate
+```
 
 ## Get started
 
-After you have installed the requirements check the [Getting started exercise](exercises/00-getting-started.md) and proceed with the exercises.
+After you have installed the requirements, check the [Getting started exercise](exercises/00-getting-started.md) and proceed with the exercises.

exercises/00-getting-started.md

@@ -1,21 +1,23 @@
 # Getting started
 
-In this section we will install Robot Framework, needed test libraries and ensure that the environment
-is up and running in order to do web UI testing with Robot Framework.
+In this section we'll 
+ - install Robot Framework
+ - install some needed test libraries
+ - prepare the environment for web UI testing
 
 ## Terminology
 
-In this section, you will see a lot of Python, operating system and Robot Framework related jargon
+In this section, you will see a lot of Python, operating system, and Robot Framework related jargon
 which might be confusing to some. So before you go further, let's clarify some terminology that is
 used frequently in this ecosystem.
 
-- *pip* - Python package manager, this is a tool that is needed to install Robot Framework and needed test libraries
-- *shell* - The shell is the command interpreter in an operating system such as Unix or GNU/Linux, it is a program that executes other programs
-- *bat / batch file / cmd* - A batch file is a script file in DOS, OS/2 and Microsoft Windows. It consists of a series of commands to be executed by the command-line interpreter, stored in a plain text file.
-- *robot* - The command line tool that allows the user to run Robot Framework test cases and tasks
-- *test suite* - A Robot file that contains test cases
-- *keyword* - a component, similar to a function in programming, that robot uses to execute steps
-- *arguments* - Values that are given to keywords. Also known as parameters.
+- *pip* — Python package manager; this is a tool that is needed to install Robot Framework and needed test libraries.
+- *shell* — The shell is the command interpreter in an operating system such as Unix or GNU/Linux, it is a program that executes other programs. A.K.A.: Terminal, Command Prompt.
+- *bat / batch file / cmd* — A batch file is a script file in DOS, OS/2 and Microsoft Windows. It consists of a series of commands to be executed by the command-line interpreter, stored in a plain text file.
+- *`robot`* — The command line tool that allows the user to run Robot Framework test cases and tasks. 
+- *test suite* — A group of test cases. In Robot Framework, a test suite is contained in single file.
+- *keyword* — A defined step; similar to a function in programming. There are [built-in keywords](https://github.com/robotframework/QuickStartGuide/blob/master/QuickStart.rst#library-keywords) or you can [define your own](https://github.com/robotframework/QuickStartGuide/blob/master/QuickStart.rst#user-keywords).
+- *arguments*  — Values that are given to keywords. Also known as parameters.
 
 ## Get the Repository
 
@@ -26,30 +28,31 @@ local copy of the repo.
 
 ## Install Robot Framework
 
+### Using `pip`
 In order to run Robot Framework test cases we're going to need install Robot Framework. We install this by
-using `pip`. By default, the installation happens by calling `pip3 install <package_name>`, but if you are
+using `pip`. Usually you install something by calling `pip3 install <package_name>`, but if you are
 using a virtual environment, or have an alias defined, you can try `pip install <package_name>` instead.
 
-Install Robot Framework: `pip3 install robotframework`.
+### Installing Robot Framework
+Run `pip3 install robotframework`
 
-If the installation was successful, you can use `robot -h` command to verify that you get command line
-help for Robot Framework. Output should include Robot version number and some other helpful stuff,
-including the command line options (which are also available in [here](http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#all-command-line-options)).
+To check that it was installed, run the `robot --help` command. The output should include Robot Framework version number and some other helpful stuff,
+including the command line options (which are also available [here](http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#all-command-line-options)).
 
-To run automated test cases for web UIs, the current go-to library is the Browser-library.
-
-Install Browser: `pip3 install robotframework-browser`. After the installation has completed successfully,
-the library has to be initialized by running `rfbrowser init`.
-
-In order to ensure that you've done exercises as expected we need you to install robotframework-lint
+### Consistency Helper
+In order to ensure that you've done exercises as expected let's install the "robotframework-lint"
 tool. A linting tool is a lightweight static analysis tool to verify that you and your team are doing
 your code consistently.
 
-Install Robot Framework linter: `pip3 install robotframework-lint`.
+To install the linter, run `pip3 install robotframework-lint`
 
-## Install NodeJS
+### Testing in the Browser
+Robot Framework can test anything if you give it the right library. To run automated test cases for web UIs, we'll use the "Browser" library.
 
-Browser library has requirements for NodeJS. After installing NodeJS run command: `rfbrowser init` to install needed dependencies.
+To install this "Browser" library, run `pip3 install robotframework-browser`
+
+After the installation has completed successfully,
+the library has to be initialized by running `rfbrowser init`—you'll need [Node.js installed](https://nodejs.org/en/download/). It will take a a minute or two to run the command.
 
 ## Start server
 
@@ -67,7 +70,9 @@ Verify setup by running:
 - in Windows: run command `python verify.py 00`
 - in macOS/Linux: run command `python3 verify.py 00`
 
+> If you run into an `ImportError: cannot import name 'get_installed_distributions' from 'pip._internal.utils.misc'` error, the workaround is to downgrade your pip by running, `pip3 install pip==21.2.4`. See [issue #20](https://github.com/eficode-academy/rf-katas/issues/20) for details.
+
 This should take a few seconds. If the output of the script ends with `Setup in perfect condition!`
-we're good to go.
+you're good to go to the [next section](01-manual_testing.md).
 
 Otherwise, check the output and fix the missing packages.

exercises/01-manual_testing.md

@@ -1,23 +1,23 @@
 # Manual testing
 
-Manual testing is usually a part of test automation. We need to know the steps that are then going to
-be automated.
+Manual testing is usually a part of test automation. We need to know what the steps are 
+before we can automate them.
 
 Let us first go through our System Under Testing (SUT) before we proceed.
 
 ## System Under Testing (SUT)
 
-Our SUT is simple web application that is running at localhost:7272 address.
+Our SUT is a simple web application that is running on `http://localhost:7272`.
 
-Features:
+### Features
 
-- Index page contains login form
+- The index page contains a login form
   - Username: `demo`
   - Password: `mode`
   - Submit login form button
-- After successful login the user is redirected to the welcome page
-  - User can log out after successful login and will be redirected to the login page
-- After incorrect login credentials the user is redirected to the error page
+- After successful login, the user is redirected to the welcome page.
+  - User can log out after successful login and will be redirected to the login page.
+- After incorrect login credentials, the user is redirected to the error page.
 
 ## Exercise
 
@@ -27,11 +27,13 @@ How would you manually test the successful login use case?
 - Inside it add a text file, call it `login.robot` (note that `.robot` is the extension, not `.txt`).
 - Write line by line, all the steps that you would need to perform if you were manually testing the login feature.
 
-## Verify your results
+## Verify your solution
 
-After you've added steps that you think are needed to manually test login feature run:
+After you've added the steps that you think are needed to manually test the login feature, run:
 
 - in Windows: run command `python verify.py 01`
 - in macOS/Linux: run command `python3 verify.py 01`
 
-If the output is `Ready to proceed!` then you're good to go! Otherwise, the check the output about what is missing?
+If the final output is `Ready to proceed!` then you're good to go! Otherwise, check the output to see what is wrong.
+
+When you're ready, move on to the [next section](02-robot-syntax.md).