TypeScript Tutorial: Building a Simple Web-Based Code Coverage Tool

Written by

learnmodernjavascript

in

In the world of software development, ensuring the quality and reliability of your code is paramount. One crucial aspect of this is understanding how much of your code is actually being tested. This is where code coverage tools come in. They measure the extent to which your code is executed when your tests are run. A high code coverage percentage generally indicates that your tests are thorough, giving you greater confidence in the stability and functionality of your application. In this tutorial, we will build a simple web-based code coverage tool using TypeScript, providing a hands-on learning experience for beginners and intermediate developers alike.

Why Code Coverage Matters

Imagine you’re building a complex application. Without code coverage, you might run your tests and get a green light, feeling confident that everything is working as expected. However, what if your tests only cover a small portion of your codebase? Critical bugs could be lurking in untested areas, waiting to be discovered by your users. Code coverage helps you avoid this scenario by:

  • Identifying Untested Code: It highlights parts of your code that haven’t been touched by your tests.
  • Improving Test Quality: It encourages you to write more comprehensive tests that cover all possible code paths.
  • Reducing Bugs: By testing more of your code, you increase the likelihood of catching bugs early in the development process.
  • Boosting Confidence: Knowing that your code is well-tested gives you and your team greater confidence in your application’s reliability.

Setting Up the Project

Let’s get started by setting up our project. We’ll use Node.js and npm (or yarn) to manage our dependencies. First, create a new directory for your project and navigate into it using your terminal:

mkdir code-coverage-tool
cd code-coverage-tool

Next, initialize a new npm project:

npm init -y

This will create a package.json file in your project directory. Now, let’s install the necessary dependencies:

  • TypeScript: For writing our code.
  • ts-node: To run TypeScript files directly without compiling.
  • express: For creating our web server.
  • @types/express: TypeScript typings for Express.
  • istanbul: A popular code coverage tool.
  • mocha: A testing framework for JavaScript.
  • chai: An assertion library for JavaScript.
npm install typescript ts-node express @types/express istanbul mocha chai --save-dev

Now, let’s create the necessary configuration files. First, create a tsconfig.json file in your project root. This file tells the TypeScript compiler how to compile your code. Here’s a basic example:

{
  "compilerOptions": {
    "target": "es2017",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"]
}

This configuration specifies that we’ll target ECMAScript 2017, use CommonJS modules, output compiled files to a dist directory, and include all files in the src directory. We also enable strict type checking.

Building the Server

Let’s create the basic structure for our web server. Create a directory named src in your project root. Inside src, create a file named index.ts. This will be the entry point for our application.

Here’s a simple Express server setup:

// src/index.ts
import express, { Request, Response } from 'express';

const app = express();
const port = process.env.PORT || 3000;

app.get('/', (req: Request, res: Response) => {
  res.send('Hello, Code Coverage Tool!');
});

app.listen(port, () => {
  console.log(`Server is running on port ${port}`);
});

This code imports the Express library, creates an Express application, defines a route for the root path (/), and starts the server on port 3000 (or the port specified in the PORT environment variable). To run this, you can add a script to your package.json file:

{
  "scripts": {
    "start": "ts-node src/index.ts",
    "build": "tsc",
    "test": "mocha"
  }
}

Now, run the server using npm start. You should see “Server is running on port 3000” in your console. Open your web browser and go to http://localhost:3000. You should see “Hello, Code Coverage Tool!”

Creating a Simple Function and Tests

To demonstrate code coverage, let’s create a simple function and write some tests for it. Create a new file in the src directory called calculator.ts:

// src/calculator.ts
export function add(a: number, b: number): number {
  return a + b;
}

export function subtract(a: number, b: number): number {
  return a - b;
}

This file exports two functions: add and subtract. Now, let’s write tests for these functions. Create a new directory called test in your project root. Inside test, create a file called calculator.test.ts:

// test/calculator.test.ts
import { expect } from 'chai';
import { add, subtract } from '../src/calculator';

describe('Calculator', () => {
  it('should add two numbers correctly', () => {
    expect(add(2, 3)).to.equal(5);
  });

  it('should subtract two numbers correctly', () => {
    expect(subtract(5, 2)).to.equal(3);
  });
});

This test file imports the add and subtract functions from calculator.ts and uses the chai assertion library to test their behavior. To run these tests, you can use the command npm test. You should see the test results in your console, indicating that both tests passed.

Integrating Code Coverage with Istanbul

Now, let’s integrate Istanbul to generate code coverage reports. First, update the test script in your package.json to include Istanbul:

{
  "scripts": {
    "start": "ts-node src/index.ts",
    "build": "tsc",
    "test": "nyc mocha"
  }
}

Here, we’ve replaced mocha with nyc mocha. nyc is the command-line interface for Istanbul. Make sure you have installed nyc as a development dependency: npm install nyc --save-dev

Run the tests again using npm test. After the tests run, Istanbul will generate a coverage report. By default, the report will be in the coverage directory in your project root. You’ll find an HTML report there that you can open in your browser to view the code coverage results.

Viewing the Code Coverage Report

Open the coverage/index.html file in your browser. You should see a report that shows the code coverage for your calculator.ts file. Initially, it should show 100% coverage because our tests cover all the code paths in the add and subtract functions.

Now, let’s introduce a scenario where our coverage might be less than 100%. Modify the subtract function in calculator.ts to include a conditional statement:

// src/calculator.ts
export function add(a: number, b: number): number {
  return a + b;
}

export function subtract(a: number, b: number): number {
  if (a > b) {
    return a - b;
  } else {
    return b - a;
  }
}

Now the subtract function has a conditional statement. If we run our tests again, the code coverage report will likely show a lower percentage for the subtract function, because our existing test only covers one branch of the if-else statement. This shows that we need more tests.

Improving Code Coverage

To improve code coverage, we need to write additional tests that cover the new conditional branch in the subtract function. Modify the calculator.test.ts file to include a test case where b is greater than a:

// test/calculator.test.ts
import { expect } from 'chai';
import { add, subtract } from '../src/calculator';

describe('Calculator', () => {
  it('should add two numbers correctly', () => {
    expect(add(2, 3)).to.equal(5);
  });

  it('should subtract two numbers correctly when a > b', () => {
    expect(subtract(5, 2)).to.equal(3);
  });

  it('should subtract two numbers correctly when b > a', () => {
    expect(subtract(2, 5)).to.equal(3);
  });
});

Now, when you run the tests again, the code coverage report should show 100% coverage for the subtract function as well.

Building a Web-Based Interface

Let’s enhance our tool by adding a simple web-based interface to display the code coverage report. We’ll use the Express server we created earlier. First, install the fs (file system) module:

npm install --save-dev @types/fs

Then, modify your index.ts file to serve the coverage report:

// src/index.ts
import express, { Request, Response } from 'express';
import * as fs from 'fs';
import path from 'path';

const app = express();
const port = process.env.PORT || 3000;

app.get('/', (req: Request, res: Response) => {
  res.send('Hello, Code Coverage Tool!');
});

app.get('/coverage', (req: Request, res: Response) => {
  const filePath = path.join(__dirname, '../coverage/index.html');
  fs.readFile(filePath, 'utf8', (err, data) => {
    if (err) {
      console.error(err);
      res.status(500).send('Error reading coverage report');
      return;
    }
    res.send(data);
  });
});

app.listen(port, () => {
  console.log(`Server is running on port ${port}`);
});

This code adds a new route /coverage that reads the coverage/index.html file and serves it to the client. After running your tests and generating the coverage report, you can now access the report by going to http://localhost:3000/coverage in your browser.

Advanced Features and Considerations

Our simple code coverage tool is a good starting point, but you can enhance it with more advanced features. Here are some ideas:

  • Real-time Coverage Updates: Implement a mechanism to automatically update the coverage report whenever tests are run. This could involve using web sockets or polling to notify the client of changes.
  • Code Highlighting: Integrate a library to highlight the code in the report, making it easier to identify uncovered lines.
  • Customizable Reporting: Allow users to configure the coverage thresholds and reporting formats.
  • Integration with CI/CD: Integrate the code coverage tool into your continuous integration and continuous deployment (CI/CD) pipeline. This will automatically generate and analyze code coverage reports whenever new code is pushed.
  • Branch Coverage and Function Coverage: Istanbul provides metrics for branch coverage (how many branches of your conditional statements are covered) and function coverage (how many functions are called). Consider displaying these metrics in your web interface.

Common Mistakes and How to Fix Them

Here are some common mistakes developers make when working with code coverage and how to avoid them:

  • Ignoring Code Coverage Reports: Don’t just generate the reports; actually review them and use them to guide your testing efforts.
  • Setting Unrealistic Coverage Goals: Aim for a reasonable coverage percentage, but don’t obsess over achieving 100% coverage, especially for complex or less critical code.
  • Writing Tests That Only Cover Happy Paths: Ensure your tests cover all possible code paths, including error conditions and edge cases.
  • Not Updating Tests When Code Changes: Keep your tests up-to-date as your code evolves. Refactor your tests along with your code to ensure they remain relevant.
  • Relying Solely on Code Coverage: Code coverage is a valuable metric, but it’s not the only indicator of code quality. Combine it with other testing techniques, such as unit tests, integration tests, and manual testing.

Key Takeaways

  • Code coverage tools are essential for measuring the effectiveness of your tests.
  • Istanbul is a popular and powerful code coverage tool for JavaScript and TypeScript projects.
  • Writing comprehensive tests is crucial for achieving high code coverage.
  • Regularly reviewing code coverage reports helps you identify untested code and areas for improvement.
  • Integrating code coverage into your CI/CD pipeline ensures that code coverage is continuously monitored.

FAQ

  1. What is code coverage? Code coverage measures the percentage of your codebase that is executed when your tests are run. It helps you identify untested code and improve the thoroughness of your tests.
  2. Why is code coverage important? Code coverage helps you catch bugs early, improve test quality, and increase confidence in your application’s reliability.
  3. What is Istanbul? Istanbul is a popular code coverage tool for JavaScript and TypeScript projects. It generates reports that show the code coverage for your project.
  4. How do I integrate code coverage into my CI/CD pipeline? You can integrate code coverage into your CI/CD pipeline by running your tests and generating coverage reports as part of your build process. You can then use the coverage data to set thresholds and fail the build if the coverage falls below a certain level.
  5. What is a good code coverage percentage? The ideal code coverage percentage depends on your project and your testing goals. However, a good starting point is often around 80% or higher.

By following the steps outlined in this tutorial, you’ve built a basic web-based code coverage tool using TypeScript. You’ve learned how to integrate Istanbul to generate coverage reports, and how to create a simple web interface to view these reports. This tool provides a good foundation for understanding and improving the quality of your code. Remember, code coverage is not just about numbers; it’s about writing better tests and building more reliable applications. Continuous monitoring and improvement of your code coverage will help you write robust and maintainable software. The journey of software development is a continuous cycle of learning, testing, and refining.

More posts