This repository is an implementation of the Battleship game in TypeScript.
It was meant to learn some useful programming workflow concepts such as Test Driven Development (TDD), unit testing, code coverage, documentation generation, CI/CD, git hooks...
This project can be bootstraped with NPM or Yarn in order to install the dependencies listed in the package.json
file:
$ git clone https://github.com/johhnry/battleship-game
$ cd battleship-game
$ yarn # or npm install
A very nice feature of Git is that you can add hooks to various events and actions you do (push, commit, branch...).
An easy way to add hooks is to use Husky which for example adds a pre-commit
hook to run the tests each time.
Conventional Commits is a commit message specification which makes them human and machine readable and unify the development process.
Here is an example of a valid commit message:
docs: :memo: add readme and license
To validate that commit message with a git hook, we use commitlint.
To add meaningful emojis to the messages, we use gitmoji with the VSCode extension to make it easier 😍
This project was developed with Test Driven Development in mind which means that the tests are written before or at the same time with the code itself.
The test framework is Mocha in combination with Chai which enables us to write human readable tests according to the BDD (Behavior-driven development) practice. For example:
expect(() => grid.hitAt(location)).to.throw(SquareAlreadyMissError);
To run the tests, do:
$ yarn run test
Code coverage is the process of measuring how much code is being tested.
To do this, we use Istanbul with its nyc command line tool that we plug with the test framework, in this case Mocha.
By tracking which parts of the code is being imported in the tests, it can generate multiple output targets including a textual report in the command line:
------------------|---------|----------|---------|---------|-------------------
File | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
------------------|---------|----------|---------|---------|-------------------
All files | 86.73 | 86.3 | 81.63 | 86.73 |
src | 85.71 | 86.3 | 80.43 | 85.79 |
Boat.ts | 100 | 100 | 100 | 100 |
Game.ts | 0 | 0 | 0 | 0 | 1-97
Grid.ts | 100 | 100 | 100 | 100 |
GridLocation.ts | 100 | 100 | 100 | 100 |
Player.ts | 92 | 75 | 85.71 | 95.65 | 90
Square.ts | 100 | 100 | 100 | 100 |
errors.ts | 100 | 100 | 100 | 100 |
src/utils | 100 | 100 | 100 | 100 |
array.ts | 100 | 100 | 100 | 100 |
index.ts | 100 | 100 | 100 | 100 |
------------------|---------|----------|---------|---------|-------------------
It also generates a HTML report with source code highlights (in the coverage
directory):
To generate the documentation from the code, we use TypeDoc. It's really easy to use and the TSDoc standard is quite familiar with other docs generators.
For example:
/**
* Put a boat on the square
* @param boat the boat to put
*/
placeBoat(boat: Boat): void {
this.status = SquareStatus.Boat;
this.content = boat.id;
}
To generate the documentation, use yarn run docs:generate
. It will output it in a docs
directory.
The linting is handled by ESLint and its VSCode integration.
This is the same for Prettier that formats code.
To run them:
$ yarn run lint && yarn run format
The TypeScript logo and design were gracefully taken from their branding page.
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Please make sure to update tests as appropriate.