BOTster is a gamified feedback system used to engage primary school students on the topics of problem solving and computational thinking skills through block-based logical programming. Students will control a robotic car to complete challenges using a web interface.
This documentation is mirrored on the project's GitHub Wiki page. You may use the Wiki version for a more organised look and feel of the documentation.
ICT2x01-p4-6
├── .github # Directory containing GitHub workflow files.
├── config # Directory containing PHP configuration files used for running BOTster.
├── docs # Directory containing resources for project documentation.
├── src # Directory containing project source code.
├── tests # Directory containing files related to testing and coverage.
├── README.md # This README file. Contains the key project documentation.
├── codeception.yml # Codeception test suite configuration.
├── start.bat # Used to run BOTster on Windows systems.
└── start.sh # Used to run BOTster on Linux systems.
This section will cover the setup instructions for BOTster.
The following software are required to be installed on the machine running BOTster:
The machine running BOTster shall also be connected to a network that has wireless connection capabilities (WiFi) for the Robotic Car to be able to communicate with the web component of this application.
On Windows, dependencies must be installed using XAMPP with default settings. Click here to download the correct version.
Ensure the user used for setting up BOTster is able to access root privileges via sudo
.
For Debian-based GNU/Linux systems, the dependencies can be installed using the following commands:
dev@p4-6:~$ sudo apt update && sudo apt install -y php7.4-cli php7.4-common php7.4-curl php7.4-fpm php7.4-json php7.4-mbstring php7.4-readline php7.4-sqlite3 sqlite3
Download the latest project files (Source code (zip)
) from here and extract the contents to a folder.
Open the folder containing the extracted project files using File Explorer by double-clicking it in the respective directory.
Double-click on start.bat
to start BOTster. A Command Prompt window will open with output similar to the following:
[*] Press Ctrl+C to stop BOTster Web.
[*] Document root is: C:\Users\dev\ICT2x01-p4-6\src
[Fri Nov 19 12:58:19 2021] PHP 7.4.25 Development Server (http://127.0.0.1:5000) started
Access BOTster by opening a web browser on the same machine and going to the URL http://127.0.0.1:5000
. The default credentials for Facilitator
is P@ssw0rd
Download the latest project files (Source code (zip)
) from here and extract the contents to a folder.
In a terminal, set your current working directory to the repository on your local file system.
dev@botster:~$ cd ICT2x01-p4-6
Run start.sh
to start BOTster.
dev@botster:~/ICT2x01-p4-6$ ./start.sh
PHP 7.4.26 Development Server started at Fri Nov 19 00:00:00 2021
Listening on http://127.0.0.1:5000
Document root is /home/dev/ICT2x01-p4-6/src
Press Ctrl-C to quit.
Access BOTster by opening a web browser on the same machine and going to the URL http://127.0.0.1:5000
. The default credentials for Facilitator
is P@ssw0rd
This section will contain the necessary information for the project development workflow.
master
or dev
branch.feature/
or bugfix/
branches respectively, which shall be derived from the dev
branch.hotfix/
branch, which shall be derived from the master
branch.docs-testsuite
branch, which shall be derived from the dev
branch.master
or dev
branches via Pull Requests (PR).master
branch can only be created by the Team Lead, unless it is a hotfix. Only the Team Lead is allowed to perform a merge into master
branch after approval is given by the assigned reviewer(s).master
: Contains production-ready code and/or other "critical" resources (Important for the progression of the project).dev
: Contains code and resources that are of "release-candidate" standards and ready to be staged for production.feature/x
: Contains development code for a feature x
as described in a related GitHub Issue. Branch will be merged into dev
when feature is deemed complete.bugfix/x
: Contains development code for a bug fix x
as described in a related GitHub Issue. Branch will be merged into dev
when bug fix is deemed complete.hotfix/x
: Contains development code for an urgent bug fix x
as described in a related GitHub Issue. A bug is defined as "urgent" if it severely degrades the functionality of the application in production (E.g. Causes the application to crash).docs-testsuite/x
: Contains documentation, workflow or test-suite code for an Issue x
as described in a related GitHub Issue. Branch will be merged into dev
when Issue is deemed resolved.Branch protection is enforced on the following branches:
master
dev
1. Open a new Issue on GitHub
bugfix
or feature
?).ICT2101/2201 Team Project
Project Board and set the appropriate column depending on the Issue status.Milestone 3 (Project Development)
Milestone.2. Branch off from dev
branch on GitHub
Create a new branch off from the dev
branch with a descriptive name starting with bugfix/
or feature/
(E.g. bugfix/command-parsing-issue
or feature/login
)
3. Work on the Issue in the new branch
Commit all additions or changes to the newly created branch. Only work within the scope of the described Issue (Do not make changes that are irrelevant to the Issue).
4. Create a Pull Request (PR) on GitHub
Once all the necessary commits are pushed, open a new PR (From feature/
or bugfix/
into dev
) and perform the following:
bugfix
or feature
?).ICT2101/2201 Team Project
Project Board and move it to the In-Progress
column.Milestone 3 (Project Development)
Milestone.5. Request for review and wait for Approval
When ready for code review, label the PR with the review-requested
label. 2 reviewers are to check and verify the changes before approving the PR. Reviewers have the right to request for changes to the PR by providing comments to support their justification.
6. Perform merge commit via GitHub
Once approval requirements have been met, use the Merge Commit
feature on the respective PR page to merge the approved changes into the dev
branch. Merging can be done by any of the code reviewers or the PR author. Only perform merging using the GitHub web interface! Once merged, do not delete the branch.
master
branchOnly production-ready code (Meant for release) and other critical resources shall be merged into master
from dev
. Only the Team Lead is allowed to create such PRs and complete the merge as these processes involes the master
branch.
1. Create a Pull Request on GitHub
The Team Lead will open a new PR (dev
into master
), labelling it with the review-requested
label and provide a summary of the features introduced. The Team Lead must assign a minimum of 1 reviewer to this PR.
2. Wait for PR approval
The assigned reviewer(s) are required to check and verify the changes before approving the PR. The reviewer have the right to request for changes to the PR by providing comments to support their justification.
3. Perform merge commit via GitHub
Once approval requirements have been met, the Team Lead will perform a merge from the dev
branch onto the master
branch.
Hotfixes are code that will be deployed to both dev
and master
branches to fix urgent issues that are present in production (master
). Hotfix deployment PRs requires the involvement of the Team Lead as it involves merging into the master
branch.
1. Open a new Issue on GitHub
hotfix
label.ICT2101/2201 Team Project
Project Board and set the appropriate column depending on Issue status.Milestone 3 (Project Development)
Milestone.2. Branch off from master
branch on GitHub
Create a new branch off from the master
branch with a descriptive name starting with hotfix/
(E.g. hotfix/connection-string-typo
)
3. Work on the hotfix in the new branch
Commit all additons or changes to the newly created branch. Only work within the scope of the described hotfix (Do not make changes that are irrelevant to the hotfix).
4. Create a Pull Request on GitHub
Open 2 new PRs (From hotfix
into dev
and hotfix
into master
) and perform the following:
hotfix
.ICT2101/2201 Team Project
Project Board and move it to the In-Progress
column.Milestone 3 (Project Development)
Milestone.5. Request for review and wait for approval
When ready for code review, label the PR with the review-requested
label. 2 reviewers are to check and verify the changes before approving the PRs. One of the reviewers must be the Team Lead. Reviewers have the right to request for changes to the PRs by providing comments to support their justification.
6. Perform merge commits via GitHub
Once approval requirements have been met, the Team Lead will perform a merge from the hotfix/
branch onto the dev
and master
branches.
This process is similar to how new Features or Bug Fixes are introduced into the project.
1. Open a new Issue on GitHub
docs-testsuite
label.ICT2101/2201 Team Project
Project Board and set the appropriate column depending on the Issue status.Milestone 3 (Project Development)
Milestone.2. Branch off from dev
branch on GitHub
Create a new branch off from the dev
branch with a descriptive name starting with docs-testsuite/
(E.g. docs-testsuite/readme
)
3. Work on the Issue in the new branch
Commit all additions or changes to the newly created branch. Only work within the scope of the described Issue (Do not make changes that are irrelevant to the Issue).
4. Create a Pull Request (PR) on GitHub
Once all the necessary commits are pushed, open a new PR (From docs-testsuite/
into dev
) and perform the following:
docs-testsuite
.ICT2101/2201 Team Project
Project Board and move it to the In-Progress
column.Milestone 3 (Project Development)
Milestone.5. Request for review and wait for Approval
When ready for code review, label the PR with the review-requested
label. 2 reviewers are to check and verify the changes before approving the PR. Reviewers have the right to request for changes to the PR by providing comments to support their justification.
6. Perform merge commit via GitHub
Once approval requirements have been met, use the Merge Commit
feature on the respective PR page to merge the approved changes into the dev
branch. Merging can be done by any of the code reviewers or the PR author. Only perform merging using the GitHub web interface! Once merged, do not delete the branch.
Changes have been made to the System State Diagram for Milestone 3 project deliverables. Refer to Section 1.2 of the latest UAT documentation for more details.
Click here to view the latest UAT documentation.
Testing is done on all Model classes (Entity/Control) and statement coverage is performed to ensure that adequete test cases have been written. Testing is done using Codeception, which wraps around PHPUnit and PCOV to automate unit testing as well as generation of code coverage statistics.
GitHub Actions are used to automate the execution of the test suite and publish code coverage statistics when Pull Requests are opened to merge into either the dev
or master
branches. See .github/workflows/testsuite.yml for the deployed GitHub Action workflow.
For the purpose of this project, the test suite for the ChallengeManagement control class will be the main focus. The following table contains test cases for the ChallengeManagement class (Click here to view the test case source code).
S/N | Test Description | Test Case |
---|---|---|
1 | There are no challenges yet | testThereAreNoChallengesYet() |
2 | Valid challenge max command block values | testValidChallengeMaxCommandBlockValues() |
3 | Max command block must be an integer | testMaxCommandBlockMustBeAnInteger() |
4 | Max command block cannot be less than zero | testMaxCommandBlockCannotBeLessThanZero() |
5 | Max command block limit constant check | testMaxCommandBlockLimitConstantCheck() |
6 | Valid map file | testValidMapFile() |
7 | Specified file is not an image file thus not a valid map file | testSpecifiedFileIsNotAnImageFileThusNotAValidMapFile() |
8 | Specified file has wrong extension thus not a valid map file | testSpecifiedFileHasWrongExtensionThusNotAValidMapFile() |
9 | Create two new challenges | testCreateTwoNewChallenges() |
10 | There are now two challenges | testThereAreNowTwoChallenges() |
11 | Valid challenge names | testValidChallengeNames() |
12 | Cannot use names belonging to existing challenges | testCannotUseNamesBelongingToExistingChallenges() |
13 | Challenge name cannot be empty | testChallengeNameCannotBeEmpty() |
14 | Delete challenges | testDeleteChallenges() |
15 | Deleting non existent challenge will throw exception | testDeletingNonExistentChallengeWillThrowException() |
16 | There should be no challenges remaining | testThereShouldBeNoChallengesRemaining() |
Click here to view the code coverage report for the ChallengeManagement control class.
The test suite for this project is executed on a Ubuntu 20.04 LTS (Focal) system. To setup a test environment, run the following commands on a root
terminal shell:
# Install PHP 7.4 and other test dependencies.
root@botster:~$ apt-get install -y curl php7.4-cli php7.4-curl php7.4-dev php7.4-fpm php7.4-json php7.4-mbstring php7.4-readline php7.4-sqlite3 php-pcov sqlite3
# Install Codeception.
root@botster:~$ curl -LsS https://codeception.com/codecept.phar -o /usr/local/bin/codecept
root@botster:~$ chmod a+x /usr/local/bin/codecept
Open a terminal shell in the repository directory and run the following command:
dev@botster:~/ICT2x01-p4-6$ codecept run unit --coverage --coverage-html
Code coverage statistics summary will be displayed on the console at the end. To view the complete report, open the file tests/_output/coverage/index.html
in a web browser.