Developer: Aleksandra Haniok

💻 Visit live website

This is a command-line version of the classic Connect Four game for two players.

The classic game is played on a standing board with seven columns of six rows where two players take turns dropping coloured discs from the top to the bottom into a column of their choice. The piece falls straight down, occupying the next available space within the column.

The objective of the game is to be the first one to achieve a horizontal, vertical or diagonal line of four connected discs.

• Project Goals
  • User Goals
  • Site Owner Goals
• User Experience
  • Target Audience
  • User Requirements and Expectations
  • User Manual
• User Stories
  • Users
  • Site Owner
• Technical Design
  • Flowchart
• Technologies Used
  • Languages
  • Frameworks & Tools
  • Libraries
• Features
• Validation
• Testing
  • Manual Testing
  • Automated Testing
• Bugs
• Deployment
• Credits
• Acknowledgements

• Play a fun and easy game with other player
• Read the rules of the game
• Be able to log in to an existing account

• Create a game that is easy and clear to user
• Ensure that users understand the purpose of the game
• Create a game that gives feedback to the user whilst playing

There is no specific audience of this game. However, I would recommend that players are at least 6 years old, as per the classic board game.

• A simple, error-free game
• Straightforward navigation
• Game personalisation by entering players' names
• Feedback on game results

Back to Table Of Contents

1. I want to have clear options to select in the main menu
2. I want to be able to read the rules of the game
3. I want to personalise the game and enter my name
4. I want to be able to log-in if I return to the game
5. I want to receive a real time feedback throughout the game
6. I want to get a feedback when I win the game
7. I want to be able to play multiple games when I'm logged in
8. I want a random selection of the player to start a new game
9. I want to see how many games I've won so far

10. I want users to have a positive experience whilst playing the game
11. I want users to easily select options from the menu
12. I want user names and emails to be saved to Google Spreadsheet
13. I want the user to get feedback in case of wrong input
14. I want data entry to be validated, to guide the user on how to correctly format the input

Back to Table Of Contents

The following flowchart summarises the structure and logic of the application.

Flowchart

• Python programming language for the logic of the program

• Diagrams.net was used to draw program flowchart
• Font Awesome - icons from Font Awesome were used in the footer below the program terminal
• Git was used for version control within VSCode to push the code to GitHub
• GitHub was used as a remote repository to store project code
• Google Cloud Platform was used to manage access and permissions to the Google Services such as Google auth, sheets etc.
• Google Sheets were used to store players details
• Heroku Platform was used to deploy the project into live environment
• PEP8 was used to check my code against Python conventions
• Visual Studio Code (VSCode) VSCode was used to write the project code using Code Institute template

• os - used to clear terminal
• random - used to alternate first player to start the game
• sys & sleep - used to create a typing effect within the games rules
• time - used to displayed delayed messages in the terminal
• unittest - used to carry out testing on single units in validation.py file

• colorama - JUSTIFICATION: I used this library to add color to the terminal and enhance user experience. I marked warning/error information with color red and user feedback with blue and green
• email_validator - JUSTIFICATION: I used this library to validate if user email input is of the form [email protected]
• gspread - JUSTIFICATION: I used gspread to add and manipulate data in my Google spreadsheet and to interact with Google APIs
• google.oauth2.service_account - JUSTIFICATION: module used to set up the authentification needed to access the Google API and connect my Service Account with the Credentials function. A creds.json file is created with all details the API needs to access the google account. In deployment to heroku this information is stored in the config var section.

Back to Table Of Contents

• Provides user with graphic welcome message
• Gives user option to view game rules or start game
• User stories covered: 1, 2

• Displays clear game rules
• Allows user to return to the main menu once read
• User stories covered: 2

• Gives players options to either log in or create a new user
• User stories covered: 4

• Asks users for their email addresses
• Informs them if the email they input is incorrect or not registered
• Gives user alternative option to try another email or create a new player
• If correct, saves their details to Google Spreadsheet
• User stories covered: 4, 5, 12, 13, 14

• Asks user for their name and email address
• Validates user input values
• Informs user if the name they input is incorrect
• Informs user if the email is already taken and asks for another one
• User stories covered: 5, 12, 13, 14

• Displays a greeting message to the user once logged in
• User stories covered: 3, 10

• Displays the name of currect player
• Players are asked to select the column to insert their piece
• Display warning message of incorrect column selected
• Provide feedback on who's won the game
• Gives options to play again after finished game
• User stories covered: 3, 5, 6, 13, 14

• Restarts the game for the same players
• User stories covered: 7

• Brings players to the main menu of the program

• Display number of games won so far by each logged player
• User stories covered: 9

• Exits the program with a goodbye message

• Displays an error message if user input is not in a form that was expected
• Asks for a new input and provides guidance to user on how to correctly format the input
• User stories covered: 5, 13, 14

Back to Table Of Contents

PEP8 Validation Service was used to check the code for PEP8 requirements. All the code passes with no errors and no warnings to show.

PEP3 check for run.py

PEP3 check for validation.py

PEP3 check for colors.py

PEP3 check for test_validation.py

The testing approach is as follows:

1. Manual testing of user stories
2. Automated unit testing using the Python unittest library

See user stories testing

1. I want to have clear options to select in the main menu

Feature	Action	Expected Result	Actual Result
Main menu	Select option 1	Users are presented with game rules	Works as expected
Main menu	Select option 2	Users are asked if they played the game before	Works as expected

Screenshot

2. I want to be able to read the rules of the game

Feature	Action	Expected Result	Actual Result
Main menu	Select option 1	Users are presented with game rules	Works as expected

Screenshot

3. I want to personalise the game and enter my name

Feature	Action	Expected Result	Actual Result
Play game options	Select option 1 (log-in)	Users are asked to input their email addresses, and once validated, a greeting message with their name is displayed. Names are displayed during the game	Works as expected
Play game options	Select option 2 (sign-up)	Users are asked to input their names, once validated the names are saved and greeting message displayed. Names are displayed during the game	Works as expected

Screenshot

Screenshot

4. I want to be able to log-in if I return to the game

Feature	Action	Expected Result	Actual Result
Play game options	Select option 1 (log-in)	Returning users are asked to input the email address they registered before and once validated, a greeting message with their name is displayed	Works as expected

Screenshot

5. I want to receive a real time feedback throughout the game

Feature	Action	Expected Result	Actual Result
User Input Validation & Feedback through game play	Players will be informed if their input is invalid	Error messages displayed	Works as expected

Screenshots

6. I want to get a feedback when I win the game

Feature	Action	Expected Result	Actual Result
Game screen	Player has connected 4 pieces in a row	Message is displayed with the winning player's name	Works as expected

Screenshots

7. I want to be able to play multiple games when I'm logged in

Feature	Action	Expected Result	Actual Result
Finished Game options	User selects play again option	The game restarts for the same players	Works as expected

Screenshot

8. I want a random selection of the player to start a new game

Feature	Action	Expected Result	Actual Result
Game screen	Once players have logged-in or signed-up the game is loaded	Different user names display	Works as expected

Screenshots

9. I want to see how many games I've won so far

Feature	Action	Expected Result	Actual Result
Finished Game options	Select option 3	Display number of games won for Player1 & Player2	Works as expected

Screenshots

10. I want users to have a positive experience whilst playing the game

Feature	Action	Expected Result	Actual Result
Across all screen	Simple navigation and game play	Colored messages and straightforward instructions	Works as expected

Screenshots

11. I want users to easily select options from the menu

Feature	Action	Expected Result	Actual Result
Across all screen	User inputs invalid numeric value	Users are asked to try again between available options from the menu	Works as expected

Screenshots

12. I want user names and emails to be saved to Google Spreadsheet

Feature	Action	Expected Result	Actual Result
Log-in	Both users input their names and email address which has not been previously registered	Username and email addresses are saved to Google Spreadsheet to the next available rows in columns 1 & 2 respectively	Works as expected

Screenshot

13. I want the user to get feedback in case of wrong input

Feature	Action	Expected Result	Actual Result
Across all screen	User inputs invalid numeric value in the menu or game. User inputs invalid value during log-in or sign-up	Feedback message displayed to the user	Works as expected

Screenshots

14. I want data entry to be validated, to guide the user on how to correctly format the input

Feature	Action	Expected Result	Actual Result
Across all screen	User inputs invalid data	Feedback message with instructions diplayed to the user	Works as expected

Screenshots

Back to Table Of Contents

This application has been deployed from GitHub to Heroku by following the steps:

1. Create or log in to your account at heroku.com
2. Create a new app, add a unique app name (this project is named "ci-pp3-connect4") and choose your region
3. Click on create app
4. Go to "Settings"
5. Under Config Vars store any sensitive data you saved in .json file. Name 'Key' field, copy the .json file and paste it to 'Value' field. Also add a key 'PORT' and value '8000'.
6. Add required buildpacks (further dependencies). For this project, I set up 'Python' and 'node.js' in that order.
7. Go to "Deploy" and select "GitHub" in "Deployment method"
8. To link up our Heroku app to our Github repository code enter your repository name, click 'Search' and then 'Connect' when it shows below
9. Choose the branch you want to buid your app from
10. If prefered, click on "Enable Automatic Deploys", which keeps the app up to date with your GitHub repository
11. Wait for the app to build. Once ready you will see the “App was successfully deployed” message and a 'View' button to take you to your deployed link.

1. Go to the GitHub repository
2. Click on Fork button in top right corner
3. You will then have a copy of the repository in your own GitHub account.

1. Go to the GitHub repository
2. Locate the Code button above the list of files and click it
3. Highlight the "HTTPS" button to clone with HTTPS and copy the link
4. Open Git Bash
5. Change the current working directory to the one where you want the cloned directory
6. Type git clone and paste the URL from the clipboard ($ git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY)
7. Press Enter to create your local clone

Back to Table Of Contents

• Flaticon was used for the website favicon

• ASCII Art Generator was used to create game title
• Code Institute - for git template IDE and "Love Sandwiches - Essentials Project" which helped me with connecting the Google Spreadsheet to my project.
• ColorSpace was used to create a gradient button and background effect
• How to install a Python module, eg. email validation
• gspread documentation explained how to obtain a specific value from the google spreadsheet
• Instructions how to print colored text from this and this sources
• Stack overflow helped me create typing effect in games rules
• Stack overflow code used to clear the terminal console
• Youtube video on Unit Test in Python made by Socratica was very helpful to understand the concept of unit tesing
• Youtube tutorial “Python Connect 4 Tutorial” made by Spencer Lepine - I used a part of Spencer's code for display of the game board, moves of alternative players and saving last move's coordinates on the board
• Youtube tutorial “Creating a Connect 4 Game in Python” made by “Painless Programming” - inspired me to create a schemat for winning move logic

See winning move schemat

I would like to thank everyone who supported me in the development of this project:

• My mentor Mo for professional guidance, helpful feedback and words of encouragement whilst creating the project. Also, for encouraging me to learn about the unit test and including it within this project.
• My partner for his support and playing/testing the game with me
• Code Institute community on Slack for resources and support