(Developer: Vilayat Kleer)

View the live website

1. Project Goals
   1. User Goals
   2. Website Owner Goals
2. User Experience
   1. Target Audience
   2. User Requirements and Expectations
   3. User Manual
3. User Stories
   1. User
   2. Website owner
4. Technical Design
   1. Flowchart
5. Technologies Used
   1. Languages
   2. Tools
   3. Libraries
      1. Built-in Python Libraries
      2. Third Party Libraries
6. Features
   1. Game logo
   2. Log in menu
   3. Log in
   4. Create new account
   5. Main menu
   6. Game instructions
   7. View win count
   8. Game
   9. Play again menu
7. Testing
   1. Python Validation
   2. Manual Testing - User Stories
   3. Automated Testing
8. Bugs
9. Deployment
   1. GitHub
   2. Heroku
10. Credits
    1. Code
11. Acknowledgements

• Play a simple and fun game for two players
• Be able to create and log in to an account that keeps my score

• Creating a fun game with clear instructions and simple mechanics
• Provide clear feedback to the players so they never get stuck

• People who like Tic-Tac-Toe
• People who want to play a simple and fun game
• Casual gamers

• A simple, fun game that anyone can play
• Clear options for each menu or interaction
• Clear feedback provided when necessary
• Providing a personal touch through unique usernames

1. As a user, I want to be able to read the game instructions
2. As a user, I want to be able to create an account
3. As a user, I want to be able to log in with my account
4. As a user, I want to be able to log out when I'm done
5. As a user, I want to be able to quit the game
6. As a user, I want to know how many games I've won
7. As a user, I want to receive feedback during and after the game
8. As a user, I want to be informed if I provide wrong input in the game

9. As the website owner, I want the game to be fair and have a random player get the first turn on each game
10. As the website owner, I want to provide feedback to users when they provide invalid input
11. As the website owner, I want usernames and email addresses to be saved to a Google Sheets file
12. As the website owner, I want users to be able to decide if they want to create one or two accounts during the registration process

A flowchart has been created to display the structure and logic of the program.

Flowchart

• Python

• Git was used for version control
• GitHub was used as a remote repository to store the all project files
• Gitpod was used as the IDE to write the project code
• Google Cloud was used to manage access to the Google Sheets and Google Drive API's using a service account key
• Google Sheets was used to store the players' account details
• Heroku was used to deploy the project
• PEP8 was used to validate my Python code
• LucidChart was used to create the flowchart

• os is used to clear the terminal
• sys is used to to exit the program
• random is used to change from player 1 to player 2 and vice versa
• unittest is used to create automated tests for player_validation.py
• patch from unittest.mock is used to to test my register_players and log_in functions from player_validation.py, which both require multiple inputs in a row to complete the test

• gpread is used to get, set and delete data in my Google Sheets file. The Google Sheets file contains the usernames, email addresses and win counts for each player that has registered.
• Credentials from google.oauth2.service_account is used for the authentification that's required to connect to my Google service account to the Google Drive and Google Sheets API. A service account key has been created in JSON with the name creds.json. The connection is set up in player_validation.py. To keep the creds.json file safe, it is put in the .gitignore file to prevent it from being pushed to GitHub. As the project is deployed on Heroku, the contents of the creds.json file have been stored in a Config Var inside the Heroku application settings to make the connection work.
• email_validator is used to validate the players' email address when entered on registration and log in. It must follow the format of '[email protected]'.

The website has a total of 9 main features:

• Logo created from ASCII characters
• Is present everywhere throughout the program except during the game to make room for the 5x5 grid

Screenshot of game logo

• Presents users with the option to log in, create an account or quit the game
• Validates the input, providing feedback if input was invalid. User will be prompted to try again if a non-existing option was selected.
• Covers user story 2, 3, 5 and 10

Screenshot of log in menu

Screenshot of log in menu validation

• Asks for a registered email address from player 1 and player 2, which must follow the format of '[email protected]'
• Validates the email address, providing feedback if input was invalid.
  • If the input follows the correct format, compare the entered email address to the list of email addresses in the database (Google Sheets file)
    • If the email address is not registered, present the player with the option to try a different email address or create a new account
• After successfully logging in, each player is greeted by their username
• Covers user story 3 and 10

Screenshot of log in

Screenshot of log in menu validation

• Allows users to create a new account for the game
• Asks for a username, which has to be unique and can only contain letters or digits
• Asks for an email address, which also has to be unique and must follow the format of '[email protected]'
• Validates the username and email address, providing feedback if input was invalid. User will be prompted to enter a new username of email address if invalid
• After validation, the user will be asked to confirm their username and email address respectively. This is done to minimize user errors.
• Once player 1 has completed their registration, ask if player 2 wants to create a new account or go back to the log in menu
• Covers user story 2, 10, 11 and 12

Screenshots of registration process

Screenshots of registration validation

• Presents users with the option to start the game, read the game instructions, view each players' win count or log out.
• Validates the input, providing feedback if input was invalid. User will be prompted to try again if a non-existing option was selected.
• Covers user story 1, 4, 6 and 10

Screenshot of main menu

Screenshot of main menu validation

• Displays the game instructions in a clear and easy to follow format
• Takes users back to the main menu after they've gone through the game instructions
• Covers user story 1

Screenshots of game instructions

• Displays each players total amount of wins
• Takes players back to the main menu after entering any key and pressing the enter key
• Covers user story 6

Screenshot of view win count

• A random player is picked to have the first turn at the start of each game
• The players' name will be displayed if it's their turn
• The game grid is printed when the game starts and is updated after each turn
• Players are asked to select a row number and column letter to place a mark on the grid
• Validates the row number and column letter, providing feedback if input was invalid. User will be prompted to enter a new row number or column letter if invalid
• After a mark is placed, it will then be the other players' turn
• Provides feedback when a game is won or a tie.
  • If a game is won, the player will receive a congratulatory message with their name and their new win count
  • If the game is a tie, a message will be displayed to inform the players and take them back to the main menu
• Covers user story 7, 8, 9 and 10

Screenshots of game

Screenshots of game validation

• Presents users with the option to play again, to to main menu, log out or quit the game.
• Validates the input, providing feedback if input was invalid. User will be prompted to try again if a non-existing option was selected.
• Covers user story 4, 5 and 10

Screenshot of play again menu

Screenshot of play menu validation

The Python code has been validated using Pep8 Validation Service - no errors or warnings were found.

Screenshot of run.py PEP8 Validation

Screenshot of player_validation.py PEP8 Validation

Screenshot of test_player_validation.py PEP8 Validation

1. As a user, I want to be able to read the game instructions

Supporting Screenshots - User Story 1

2. As a user, I want to be able to create an account

Supporting Screenshots - User Story 2

3. As a user, I want to be able to log in with my account

Supporting Screenshots - User Story 3

4. As a user, I want to be able to log out when I'm done

Supporting Screenshots - User Story 4

5. As a user, I want to be able to quit the game

Supporting Screenshots - User Story 5

6. As a user, I want to know how many games I've won

Supporting Screenshots - User Story 6

7. As a user, I want to receive feedback during and after the game

Supporting Screenshots - User Story 7

8. As a user, I want to be informed if I provide wrong input in the game

Supporting Screenshots - User Story 8

9. As the website owner, I want the game to be fair and have a random player get the first turn on each game

Supporting Screenshots - User Story 9

10. As the website owner, I want to provide feedback to users when they provide invalid input

Click here to go to the features section where you can find validation screenshots. Feedback is shown to users about their invalid input

11. As the website owner, I want usernames and email addresses to be saved to a Google Sheets file

Supporting Screenshots - User Story 11

12. As the website owner, I want users to be able to decide if they want to create one or two accounts during the registration process

Supporting Screenshots - User Story 12

To challenge myself, I decided to incorporate automated testing into my project. I used the built-in unittest and unittest.mock libraries to achieve this. I tested multiple seperate functions.

The validate_player_username and validate_player_email functions inside my player_validation.py file do exactly what their names suggest: they take a username or email address as an argument and return True if the format is valid. To test these I wrote a couple of simple unit tests by providing both valid and invalid input.

If the test input is supposed to be valid, assertTrue is used, returning True in the statement - if the input was supposed to be invalid, assertEqual was used, returning None in the statement

Screenshot of validate_player_username and validate_player_email unit testing code

The log_in function and register_players function inside my player_validation.py file required a more advanced method to be tested, since they both require multiple user inputs. This took me a while to get right, but in the end I solved it by importing patch from the unittest.mock library.

A patch decorator is used to access the built-in input function. The unit test is then declared, taking two parameters: self and mocked_input. The mocked_input is a Mock object - the side_effect function is called on this object, taking several string arguments. These arguments are iterated through when the unit test is called, providing input until the function has completed. Both functions use the same technique.

Screenshot of log_in and register_players unit testing code

GIF of the unit tests being run

Since both functions don't return a value on completion, assertEqual is used, returning None in the statement.

The register_players function asks player 1 for a username, then a username confirmation, then an email address, then an email address confirmation. It will then ask player 2 if they want to create an account as well or if they want to go to the login page. In the unit test I decided to create two test accounts.

The log_in function asks for two email addresses to log in the players. After the test accounts have successfully logged in, the accounts are deleted using the delete_test_data function in my player_validation.py file.

This website was deployed using Github Pages with the following steps:

1. Go to your Github Repository
2. Navigate to the 'Settings' page
3. On the left hand menu under 'Code and automationo', click on 'Pages'
4. Under 'Source', click on the 'Branch' dropdown element and set it to your main branch (in my case, this branch is called 'main')
5. Click on 'Save'
6. Refresh the page and you will be provided with a link to your deployed Github Page.

If you want to fork this repository, follow these steps:

1. Go to the Github repository (https://github.com/vkleer/CI_PP1_TD)
2. Click on the 'Fork' button in the top right corner under the navigation bar

If you want to clone this repository, follow these steps:

1. Go to the Github repository (https://github.com/vkleer/CI_PP1_TD)
2. Click on the 'Code' button above the list of files
3. Select your preferred way of cloning, I recommend using the 'GitHub CLI' option
4. Under 'GitHub CLI', click on the copy button to copy the clone command
5. In you IDE, open Git Bash
6. Navigate to the working directory where you want to clone this directory
7. Paste in the clone command you copied and press the 'enter' key to create the clone

This application has been deployed using Heroku with the following steps:

1. Login to Heroku
2. Go to your Heroku dashboard
3. In the top-right corner, click on the 'New' button, followed by the 'Create a new app' button
4. Enter an app name (it has to be unique) and choose your region under the 'Choose a region' dropdown menu.
5. Click on the 'Create app' button
6. On the next page, click on the 'Settings' tab
7. Under 'Config Vars', click on 'Reveal Config Vars' to add a new Config var - this is where you can store sensitive data, like your Google service account key
8. Under 'Buildpacks' click on the 'Add buildpack' button to install additional dependencies. For this project the 'python' and 'nodejs' buildpacks were added, in that specific order
9. Click on the 'Deploy' tab
10. Under 'Deployment method', click on 'Github'. You can then search for your repository under 'Search for a repository to connect to'
11. Click on the 'Connect' button to connect your repository
12. On the next page, under 'Choose a branch to deploy' you can choose the branch you want to deploy your app from
13. Either click on the 'Enable Automatic Deploys' button under 'Automatic deploys' to have the app deploy automatically on each push you make to the branch, or click on the 'Deploy Branch' button under 'Manual deploy'
14. Wait for the app to build and be deployed. Once the app is ready, a message will be displayed saying 'App was successfully deployed' along with a button which takes you to your newly deployed app

• The git template IDE from Code Institute
• The connection to my Google Sheets file was implemented using the 'Love Sandwiches Walkthrough Project' by Code institute
• Not exactly code, but the game logo in ASCII characters was created using the Text to ASCII Art Generator by Patrick Gillespie
• The clear_screen function was implemented using a solution on Stackoverflow solution by user Vasiliy Rusin. It's not complicated, but I liked how simple the solution was
• The Python Reference on the ord() function by W3Schools helped me understand how to convert column letters into integers
• To convert the integers from the ord() function into integers from 0 to 4, this ASCII table helped me to calculate the difference
• I learned how to rotate a list of lists by 90 degrees by following a solution on Stackoverflow by user Padraic Cunningham, which saved me a couple of lines of code in my check_for_win method in my Grid class, found in my run.py file
• I learned how to stop Python from running the main function after importing a module using a solution on Stackoverflow by anonymous user user166390
• The unittest and unittest.mock library documentation from the official Python documentation helped me understand how to use the libraries for my automated testing

I would like to thank:

• My mentor Mo Shami for providing me with advice and guidance for this project
• My partner Lauren Baker for helping me with testing and finding multiple bugs in the program