The `describe` Block

Summary

Sometimes, we might have many tests in a single Test Script, which can become unorganized and hard to manage. For an example, lets create a new file called math.js with a Math class in it:

js
Code kopiëren
99
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
class Math {
	static add(a, b) {
		return a + b;
	}
	
	static subtract(a, b) {
		return a - b;
	}
	
	static multiply(a, b) {
		return a * b;
	}
	
	static divide(a, b) {
		return a / b;
	}
}

module.exports = Math;

This class contains four methods and we write multiple test cases for each method. Since the test cases are related to a single class, therefore, conventionally we would store all the test cases related to it in a single file called math.test.js:

js
Code kopiëren
99
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
const Math = require('./math');

test('add two numbers', () => {
    expect(Math.add(1, 2)).toBe(3);
    expect(Math.add(-1, 1)).toBe(0);
    expect(Math.add(-1, -1)).toBe(-2);
});

test('add zero to a number', () => {
    expect(Math.add(0, 0)).toBe(0);
    expect(Math.add(5, 0)).toBe(5);
    expect(Math.add(0, 5)).toBe(5);
});

test('return the difference between two numbers', () => {
    expect(Math.subtract(5, 3)).toBe(2);
    expect(Math.subtract(3, 5)).toBe(-2);
    expect(Math.subtract(-1, -1)).toBe(0);
});

test('handle subtracting zero', () => {
    expect(Math.subtract(5, 0)).toBe(5);
    expect(Math.subtract(0, 5)).toBe(-5);
    expect(Math.subtract(0, 0)).toBe(0);
});

test('return the product of two numbers', () => {
    expect(Math.multiply(2, 3)).toBe(6);
    expect(Math.multiply(-2, 3)).toBe(-6);
    expect(Math.multiply(-2, -3)).toBe(6);
});

test('handle multiplying by zero', () => {
    expect(Math.multiply(0, 5)).toBe(0);
    expect(Math.multiply(5, 0)).toBe(0);
    expect(Math.multiply(0, 0)).toBe(0);

However, as you might notice, this can become confusing and unorganized since it contains test cases for multiple different methods. If we run the above tests using the verbose flag, you will see that the tests are all piled up in a sequence with no distinction.

In such situations it is imperative to group together the related test cases using describe blocks:

js
Code kopiëren
9
1
2
3
4
5
// General Syntax: describe(text, callback);

describe('summary of the contained test cases', () => {
    // Test Cases Here
});

Using the above syntax, we can group together the test cases of each method:

js
Code kopiëren
99
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
const Math = require('./math');

describe('add method', () => {
    test('add two numbers', () => {
        expect(Math.add(1, 2)).toBe(3);
        expect(Math.add(-1, 1)).toBe(0);
        expect(Math.add(-1, -1)).toBe(-2);
    });
    
    test('add zero to a number', () => {
        expect(Math.add(0, 0)).toBe(0);
        expect(Math.add(5, 0)).toBe(5);
        expect(Math.add(0, 5)).toBe(5);
    });
});

describe('subtract method', () => {
    test('return the difference between two numbers', () => {
        expect(Math.subtract(5, 3)).toBe(2);
        expect(Math.subtract(3, 5)).toBe(-2);
        expect(Math.subtract(-1, -1)).toBe(0);
    });
    
    test('handle subtracting zero', () => {
        expect(Math.subtract(5, 0)).toBe(5);
        expect(Math.subtract(0, 5)).toBe(-5);
        expect(Math.subtract(0, 0)).toBe(0);
    });
});

describe('multiply method', () => {
    test('return the product of two numbers', () => {
        expect(Math.multiply(2, 3)).toBe(6);
        expect(Math.multiply(-2, 3)).toBe(-6);
        expect(Math.multiply(-2, -3)).toBe(6);
    });

Now the code looks more organized, and if we run the tests with the verbose flag, you will notice that the output is more hierarchical as well, making it easier to see the different test cases for each method.

It is also important to note that we can nest describe blocks to further organize the hierarchy of Test Cases:

js
Code kopiëren
99
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
const Math = require('./math');

describe('Testing Math Class', () => {
    describe('add method', () => {
        test('add two numbers', () => {
            expect(Math.add(1, 2)).toBe(3);
            expect(Math.add(-1, 1)).toBe(0);
            expect(Math.add(-1, -1)).toBe(-2);
        });
        
        test('add zero to a number', () => {
            expect(Math.add(0, 0)).toBe(0);
            expect(Math.add(5, 0)).toBe(5);
            expect(Math.add(0, 5)).toBe(5);
        });
    });

    describe('subtract method', () => {
        test('return the difference between two numbers', () => {
            expect(Math.subtract(5, 3)).toBe(2);
            expect(Math.subtract(3, 5)).toBe(-2);
            expect(Math.subtract(-1, -1)).toBe(0);
        });
        
        test('handle subtracting zero', () => {
            expect(Math.subtract(5, 0)).toBe(5);
            expect(Math.subtract(0, 5)).toBe(-5);
            expect(Math.subtract(0, 0)).toBe(0);
        });
    });

    describe('multiply method', () => {
        test('return the product of two numbers', () => {
            expect(Math.multiply(2, 3)).toBe(6);
            expect(Math.multiply(-2, 3)).toBe(-6);
            expect(Math.multiply(-2, -3)).toBe(6);

The describe blocks also help in defining the scope of each Test Case. We will see some uses of the scopes of test cases in later topics.

Apart from that, since we typically group together test cases in a describe block, each describe block is referred to as a Test Suite in this case. It is important to note that, in other programming languages, a whole Test Script is typically referred to as a Test Suite.