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,6 +70,8 @@ Verify setup by running:
 - in Windows: double click 00-verify_setup.cmd
 - in macOS/Linux: run command `./exercises/verify/00-verify_setup.sh`
 
+> 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.
 

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,11 @@ 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:
 
 - Windows: double click `01-manual_testing.cmd`
 - Linux/macOS: `./exercises/verify/01-manual_testing.sh`
 
-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.

exercises/02-robot-syntax.md

@@ -1,7 +1,7 @@
 # Robot Syntax
+In the previous exercise, you wrote some manual instructions in a <code>robot/login.robot</code> file.
 
-<details>
-    <summary>In the previous exercise we created <code>robot/login.robot</code> file and the content was most likely something like this</summary>
+<details><summary>Our Solution</summary>
 
 ```text
 Open browser
@@ -14,17 +14,16 @@ Check that welcome page text is visible
 
 </details>
 
-If you now run command `robot robot/login.robot` you should get something like this:
+
+If you now run the command `robot robot/login.robot`, you should get something like this:
 
 `[ ERROR ] Parsing 'robot/login.robot' failed: File has no tests or tasks.`
 
 or
 
 `[ ERROR ] Suite 'Login' contains no tests or tasks.`
 
-The reason is that this is not in Robot syntax.
-
-Check out Robot Framework user guide: [Creating test data](http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#creating-test-data).
+The reason is that your steps are not in Robot syntax—yet.
 
 ## Terminology
 
@@ -33,30 +32,31 @@ Each table starts with `***` and ends with `***`.
 
 There are 5 types of tables:
 
-- `*** Settings ***` - to define libraries, resources, suite/test setups, documentation, etc:
+- `*** Settings ***` — to define libraries, resources, suite/test setups, documentation, etc:
 [See all available settings](http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#all-available-settings-in-test-data).
-- `*** Variables ***` - to define suite level variables:
+- `*** Variables ***` — to define suite level variables:
 [See different variables](http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#variable-section).
-- `*** Keywords ***` - user defined keywords:
+- `*** Keywords ***` — user defined keywords:
 [See creating keywords](http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#creating-user-keywords).
-- `*** Test Cases ***` - All the suite (file) test cases goes below this one:
+- `*** Test Cases ***` — groups of steps (a group = a test case):
 [See test case syntax](http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#test-case-syntax).
-- `*** Tasks ***` - Alternative to test cases, used in Robotic Process Automation (RPA):
+- `*** Tasks ***` — alternative name for test cases table; used in Robotic Process Automation (RPA):
 [See creating tasks](http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#creating-tasks).
 
 For more details, check the Robot Framework user guide about
 [test data syntax](http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#test-data-syntax).
 
 ## Exercise
 
-In order to fix the Robot output from `robot/login.robot`, let's add the missing test case table
-`*** Test Cases ***` to define we have test cases in the file. This tells Robot that the file contains a **test suite**.
+Let's add the missing `*** Test Cases ***` table header and see how far that gets us. This tells the Robot Framework that the file contains a **test suite**.
 
-- Add a test case table to your test suite.
+- Add a test case table header to your test suite.
 
-Once you've added the test case table let's run the command `robot robot/login.robot`
+Once you've added the test case table, let's run the command `robot robot/login.robot`
 
-Using the snippet from earlier we should get output:
+## Explanation
+
+The snippet from earlier gives this output:
 
 ```text
 ==============================================================================
@@ -88,18 +88,21 @@ Login                                                                 | FAIL |
 The reason Robot thinks we have 6 test cases is because each unindented line in the `Test Cases` table is
 considered as a new test case. When a line is indented by 4 spaces, it indicates to Robot that this
 line belongs to the previous unindented line, be it test case, task, or keyword depending on the table it
-belongs. Each indented line is called a **keyword**.
+belongs to. Each indented line is called a **keyword**.
 
-In order to make Robot understand that want to have 1 test case with 6 steps we need to define it like this:
+In order to make Robot understand that you want to have 1 test case with 6 steps, we need to define it like this:
 
 ```robot
 *** Test Cases ***
 
-Welcome Page Should Be Visible After Successful Login
-    Open browser
-    ...
+Welcome Page Should Be Visible After Successful Login # <-Test Case
+    Open browser # <-Step
+    Navigate to localhost:7272 # <-Step
+    # ... and so on
 ```
 
+## Exercise
+
 If we take a closer look at the Browser library documentation, we notice that there isn't
 a keyword called `Open browser`. However, there is a keyword called
 [`New Page`](https://marketsquare.github.io/robotframework-browser/Browser.html#New%20Page),
@@ -114,7 +117,7 @@ and `NeW pAgE` will all work. However, the recommended way is to capitalize the
 each word, like `New Page` in this case. More information can be found from the
 *[How to write good test cases using Robot Framework](https://github.com/robotframework/HowToWriteGoodTestCases/blob/master/HowToWriteGoodTestCases.rst#naming)*-guide.
 
-After that run `robot robot/login.robot` and the output should be something like this:
+After that, run `robot robot/login.robot` and the output should be something like this:
 
 ```text
 ==============================================================================

setup/01-manual_testing.py

@@ -1,46 +1,30 @@
 import os
 import sys
-import re
 from static import LOGIN_ROBOT_FILE
 
 def check_file_exists():
     if not os.path.isfile(LOGIN_ROBOT_FILE):
-        print(f"login.robot not found under {LOGIN_ROBOT_FILE}, please create one")
+        print(f"Hmm. I don't see your 'login.robot' file. I was expecting to see it at, '{LOGIN_ROBOT_FILE}'")
+        print("Double-check that it's in the right place and named correctly and try again.")
         sys.exit(1)
 
-def check_content():
-    is_browser = False
-    is_url = False
-    is_password = False
-    is_username = False
-    is_login = False
-    is_welcome = False
-    data = None
-    with open(LOGIN_ROBOT_FILE, "r") as f:
-        data = f.readlines()
-    for line in data:
-        lowered_line = line.lower()
-        if re.search(r"(new|open) (page|browser)", lowered_line):
-            is_browser = True
-        elif re.search(r"localhost:7272", lowered_line):
-            is_url = True
-        elif "username" in lowered_line:
-            is_username = True
-        elif "password" in lowered_line:
-            is_password = True
-        elif "click" in lowered_line or "login" in lowered_line:
-            is_login = True
-        elif "welcome" in lowered_line:
-            is_welcome = True
-    if is_browser and is_url and is_password and is_username and is_login and is_welcome:
-        print("Ready to proceed!")
-    else:
-        print("Not quite there yet! Did you remember browser, username, password or perhaps missing url? Did you verify your login succeeded?")
-        sys.exit(1)
+def demonstrate_our_solution():
+    print("Nice job!")
+    print("If you'd like to compare answers, here's our solution:")
+    print("""
+    Open browser
+    Navigate to localhost:7272
+    Enter username
+    Enter password
+    Submit login form
+    Check that welcome page text is visible
+    """)
 
 def main():
     check_file_exists()
-    check_content()
+    demonstrate_our_solution()
+    print("Ready to proceed!")
+
 
 
 if __name__ == "__main__":