Software Quality

In this lab you will be expected to set up a linter to ensure the quality of your code. The first part of the lab comprises a set of exercises to help you understand the tools and technologies. The last section contains instructions explaining how to apply this to your own project.

Resources:

Lecture slides

1 Using a Linter

JavaScript is a powerful language and includes a number of powerful features but it also includes features that, whilst they may produce working code, will make your code difficult to read and debug! A linter is a program that analyses your scripts for programmatic and stylistic errors and will flag up anything that may cause problems. They define a professional subset of the language and reject any code that doesn't meet that standard.

There are a number of linters available for the JavaScript language. The original one was written by Douglas Crockford (the author of JavaScript: The Good Parts). This enforced his idea of good JavaScript and was notorously not configurable! There are now a number of popular linters available, your choice should be based on what will run in your IDE as well as your personal preferences. The most popular linters are:

JSLint, the original, by Douglas Crockford
JSHint
ESLint which is supported by many IDEs and code editors

EsLint is highly configurable through a hidden config file that needs to be added to the project root directory. When you submit your coursework you must demonstrate that it contains no errors or warnings when run using an identical configuration file.

1.1 The Linter Configuration

ESLint is completely configurable through a configuration file .eslintrc which is located in the 01 Introduction to NodeJS directory. By default any file or directory starting with the period (.) character is hidden. To display hidden files and directories click on the gear icon at the top of the Documents Tree and choose Show Hidden Files.

the env object imports groups of pre-defined global variables based on the environment they are used in. In our example we will be writing scripts using the NodeJS environment so we want the linter to recognise any NodeJS global variables.
the rules object defines any additional rules we want to enforce. In this example we are specifying that we don't want semicolons at the end of each line, that we will use a 2 space tab for indenting, we will use single quotes for strings and that we are using UNIX line endings.

Near the bottom of the file list you should see a file called .eslintrc, the initial dot (.) in the filename caused it to be hidden by default.

Notice that the file contents are using the JSON format which should be familiar to you.
There are two JSON objects, env and rules.
1. The env object describes the environment you are using. In our example we indicate that we will be using the ECMA6 syntax, are writing NodeJS code, and will be using Jasmine tests.
2. The rules object defines the rules we want to apply. As you can see we are requiring tab indentation, single quotes and avoiding the use of semicolons on each line. The full list of rules can be found in the ESLint Documentation.
3. Each rule has a reporting level where 0 means disabled, 1 means warning and 2 means error. This affects how the rule violations are reported.
4. Some rules allow for additional options. If these are specified, both the reporting level and options need to be in an array.

Whilst you need to use the supplied configuration file in your assignment you should take time to understand the range of rules available and adding them to your .eslintrc configuration file. To make this process easier you can use this handy ESLint Rule Generator.

1.2 Running ESLint

Although there are plugins for many popular IDEs you should get used to running the linter from the terminal. ESLint is available as a NodeJS package which allows you to run it from the terminal. Since you may find yourself using an editor with support baked in, why would you want to do this?

Some editors don't have ESLint support.
Running ESLint in the Terminal gives a summary of the linting errors.to check if all the scripts are fixed.
It can be configured to fix many of the most common error such as whitespace and semicolon usage.
The linting can be run as part of the Continous Integration and Continous Deployment process (more on this in a later worksheet)
Finally, it will be used during the marking of your assignment to make sure your code is formatted correctly!

1.2.1 Test Your Knowledge

lets install, configure and run the console-based linter.

Start by opening a terminal window and navigating to the shopping/ directory.
Install the NodeJS ESLint package npm install eslint --save-dev. This installs it and adds it to your package.json file in the devDependencies section.
Run the executable node_modules/.bin/eslint index.js. This runs the eslint executable located in the hidden .bin/ directory in the node_modules/ directory.
You will see a list of all the errors and warnings found together with a summary with the total number of errors and the total number of warnings.
Open the index.js file and, using the linter report, fix the issues. You should re-run the linter regularly to check your progress.
Run the linter on the module using node_modules/.bin/eslint modules/shopping.js and note the errors it finds.
Now run the same command but this time pass the fix flag, node_modules/.bin/eslint --fix modules/shopping.js
Open the shopping.js file and notice that most of the issues have gone. The fix tool is not perfect, it may have introduced new errors so use it with caution!
Manually correct any errors until the linter reports 0 errors and warnings.
Finally run the linter against all the files in the project using node_modules/.bin/eslint . to ensure there are absolutely no linting errors in your code. Well done!

2 The Assignment

This week you are starting the development process. You are advised to use the koa framework rather than express or restify. Follow the steps listed below. You can find examples of all the files in the TEACHING-MATERIALS repository:

Ensure you have private repo(s) in the 340CT-1819OCTJAN organisation (where the TEACHING-MATERIALS repo is found). Names should be in the format xxx-yyy where xxx is your university username. Clone this into your chosen IDE.
Create a .gitignore file in the root of your repository and add the files and directories you don't want git to add to the repository. Use the example in this repository as a starting point.
Create a package.json file by running the npm init command.
Install any packages needed by your script using the npm install --save xxx command, where xxx is the package name. Make sure this has added the package to your package.json file.
Install any developer tools (such as eslint and jest) using the npm install --save-dev xxx command. This will add the module to the dev-dependency section of your package.json file.
Set up your .eslintrc.json file with the rules you want to use.
Add a .eslintignore file containing the files and directories you want to be ignored by the linter.
Add a jest section to your package.json that includes the coverage thresholds you are aiming for (100%).
Create a pre-commit hook:
1. Create a .githooks directory in the root of your project.
2. Create a pre-commit file in this new directory and add:
  1. A shebang. If you are on Windows this will be #!C:/Program\ Files/Git/usr/bin/sh.exe, on Mac or Linux it is #!/bin/sh.
  2. the line echo "pre-commit hook working".
3. Save the changes in the file and make sure it is executable.
4. Set your hooksPath configuration variable to point to your new directory: git config core.hooksPath .githooks
5. Stage and commit this new file using the git CLI. When you commit the changes yu should see the message pre-commit hook working, this indicates the hook is being triggered correctly.
Create a README.md file and add the name of your project.
Stage and commit the file using the terminal commands:
1. You should see the message pre-commit hook working in the terminal.
Create a pre-push hook file and add a suitable message. Test it is working.
Start developing your code. Make sure you apply TDD (write a test to define your next piece of functionality before implementing).
Modify the pre-commit hook to run the linter.
Modify the pre-push hook to run the jest test suite with code coverage.

2.1 Preparing for Test-Driven Development

At this stage you can start building your system. Each time you commit code the linter will run. Each time you push your code it will run the unit tests.

Every time you add a new .js file to your code you should:

Create a matching test file using the format xxx.test.js.
Import the test frameworks and your js file into the test suite.
Run the test suites and check that it is picking up the new test suite.

As you write the code, keep the test running going using watch mode. This means that every time you save a file the entire test suite will run. Keep an eye on the code coverage and make sure it never drops below 100%.