While this brings an increase in productivity, there's a growing downside. AI-generated code is prone to errors, unexpected bugs, or poor integration with the rest of your code.

Because of these risks, it’s more important than ever to establish robust testing practices to make sure your code is high quality and properly functioning. Various testing tools are available to help solve these challenges, and pytest stands out in the Python ecosystem for its simplicity, flexibility, and powerful features.

In this article, we'll explore the following topics:

Table of Contents

• Why Use pytest?

• How to Write Your First Tests with pytest

• How to Run pytest Tests

• How to Interpret pytest Results

• How to Handle Exceptions in pytest

• Advanced pytest Features

  • 1. pytest Markers

  • 2. pytest Fixtures

  • 3. Parametrization

  • 4. pytest Plugins

• Conclusion

By the end of this article, you will have a comprehensive knowledge of pytest and be able to use it in your Python development process.

Pre-requisites

• Must have Python installed

• An understanding of the Python programming language

Why Use pytest?

pytest is a popular testing framework for Python that makes it easy to write and run tests. Unlike unittest and other Python testing frameworks, pytest’s simple syntax allows developers to write tests directly as functions or within classes. This lets you write clean, readable code without complexities.

pytest also supports popular Python frameworks like Flask, Django, and more. Combined with other rich features, pytest equips you with the tools you need to ship reliable software in today’s AI-driven era.

Key features of pytest that make it a preferred testing tool include:

• Flexibility: it provides flexibility in test structure by supporting tests for functions, classes, and modules.

• Detailed test output: it provides a detailed and readable test output, making it easy to understand test failures and errors.

• Automatic test discovery: it automatically discovers tests by looking for files that start with "test_" or end with "_test.py". This eliminates the need for manually specifying test files**.**

• Parameterization: it supports parameterized tests, which allow you to run a single test function with multiple sets of inputs.

• Fixtures: it fixtures provide setup and tearDown methods that help prevent code repetition. This enables you to set up baseline conditions for your tests and also delete them after each test.

• Plugins and extensions: it has a rich ecosystem of plugins and extensions that add extra functionalities, such as detailed tests reporting, and integration with other tools and Python frameworks like Django and Flask.

• Compatibility: it is compatible with other testing frameworks like unittest , allowing you to migrate tests from different testing frameworks and run them seamlessly on it.

How to Write Your First Tests with pytest

This section will guide you through writing your first set of tests using the pytest framework.

pytest is a Python package, and you’ll need to install it before using it. You can do that with the following command:

pip install pytest

NOTE: Following Python's best practices, it’s recommended you install pytest within a virtual environment. Here's a guide to help you set it up.

Next, create a Python file where you will write your tests and import pytest into it using:

import pytest

pytest has 2 basic methods of writing tests, which include:

• The function-based method: This method is straightforward for writing tests because you write the tests in individual functions.

  Note: Each function name must be prefixed with the word test_ for pytest to discover and run these tests automatically.

  Here’s an example of a function-based test:

    def test_addition():
        assert 1 + 1 == 2
  

  Note: In the code above, the assert statement used here in pytest is Python’s built-in “assert”. It’s more convenient and doesn’t require the specific methods like assertEqual and assertTrue which are common with unittest. Another advantage of using the assert statement is that it provides more detailed error messages when an assertion fails.

• Class-based method: This method is similar to the way of writing tests in unittest, except that your test class does not inherit any methods. An example is shown below:

    class TestMathOperations:
        def test_addition(self):
            assert 1 + 1 == 2
  

  This method of writing tests in pytest is useful when you want to group related tests together.

How to Run pytest Tests

Running pytest differs slightly from the normal convention of running regular Python scripts.

The general method of running pytest tests is by running the pytest command in your terminal. pytest will automatically look for and run all files of the form test_*.py or *_test.py in the current directory and subdirectories. But while this may be a great way to run tests, pytest offers more flexibility beyond this general method of running tests.

Depending on preferences, you may want to run your test files based on the following:

1. To run a specific test file: To run tests in a specific file, use the pytest command followed by the file name. For example: pytest test_example.py.

2. To run tests in a directory: Let’s say you have a directory named Tests that contains some test files. To run all the tests in that directory, use the pytest command followed by the directory and a forward slash. For example: pytest Tests/.

3. To run tests using specific keywords: To run tests based on a certain keyword, use the command pytest -k "keyword". Pytest will automatically look for and run function names, class names, or file names matching that keyword in the current directory and subdirectories. But to run tests matching a certain keyword in a specific file, you’d have to specify the file name after the pytest command. For example: pytest test_example.py -k "keyword".

4. Run a specific test within a test file: To run only a specific test inside a test file, use the command pytest test_example.py::test_addition. This will run only the test_addition test function within the test_example.py module.

5. To run all test methods in a specific class: To run all the tests within a specific class, use pytest test_example.py::TestClass. This command would run all the test methods inside the TestClass class in the test_example.py module.

6. To run a specific test method inside a specific class: To run a specific test inside a specific class, use pytest test_example.py::TestClass::test_addition. This command would run the specific test_addition method within the TestClass class in the test_example.py module.

How to Interpret pytest Results

One major advantage pytest has over other Python testing frameworks is the rich output it provides, which gives very detailed information about the status of your tests.

Let’s use a basic test to understand how to interpret pytest’s output:

import pytest

def test_addition():
    assert 1 + 1 == 3

Run this test, and we get an output similar to the one below:

============================== test session starts ====================================
platform win32 -- Python 3.10.5, pytest-8.4.1, pluggy-1.6.0
rootdir: C:\\Users\\hp\\Desktop\\Pytest
collected 1 items

                                                                                  [ 50%]
test_example.py F                                                                 [100%]

===================================== FAILURES =========================================
____________________________________test_addition ______________________________________

    def test_addition():
>       assert 1 + 1 == 3
E       assert (1 + 1) == 3

test_example.py:4: AssertionError
============================== short test summary info =================================
FAILED test_example.py::test_addition - assert (1 + 1) == 3
========================= 1 failed, 1 passed in 0.13s ==================================

The above output is divided into several sections. Here’s a breakdown of what each section means:

1. Test session information:

    =============================== test session starts ===============================
    platform win32 -- Python 3.10.5, pytest-8.4.1, pluggy-1.6.0
    rootdir: C:\\Users\\hp\\Desktop\\TDD pytest
    collected 1 item
   

   • This section displays a summary of the test environment. It begins with a line marker that indicates the beginning of the test session.

   • Below the marker, pytest displays information about the operating system, along with the installed versions of Python, pytest and pluggy. (Pluggy is a pytest dependency used to manage plugins.)

   • The next line indicates the root directory where the test is being run.

   • The last line in this section displays the number of tests found in this directory.

2. Test status:

    test_example.py F                                                              [100%]
   
    ================================== FAILURES =========================================
    ________________________________ test_addition ______________________________________
   
        def test_addition():
    >       assert 1 + 1 == 3
    E       assert (1 + 1) == 3
   
    test_example.py:4: AssertionError
   

   • This section displays information about the status of our tests

   • The first line in this section specifies the test file which is being run, followed by the status (F in this case, which indicates a test failure).

   • The next set of lines gives specific information about the failed tests. This includes the function where the failure occurred (test_addition), and the exact line of code responsible for the error.

   • The last line gives a concise summary of this section. It indicates that the error occurred in test_example.py on line 4 and it was an AssertionError.

3. Test summary:

    ============================= short test summary info =============================
    FAILED test_example.py::test_addition - assert (1 + 1) == 3
    ================================ 1 failed in 0.13s ================================
   

   • This section provides an overall summary of the test.

   • It indicates that the failed test occurred in test_example.py file in the test_addition function because of an incorrect assertion (1 + 1) == 3 which isn’t true.

Edit the code with the correct assertion assert(1 + 1) == 2 and rerun the code. This time, the code passes with a different output.

=============================== test session starts ==================================
platform win32 -- Python 3.10.5, pytest-8.3.2, pluggy-1.5.0
rootdir: C:\\Users\\hp\\Desktop\\TDD pytest
collected 1 items

test_example.py .                                                               [100%]

=============================== 1 passed in 0.01s =================================

How to Handle Exceptions in pytest

Exceptions are unexpected errors that occur while running our tests, and they prevent our code from performing as expected. As a result, pytest offers several built-in mechanisms for handling these exceptions (but we’ll just cover one of them in this article).

pytest.raises Context Manager is a tool that checks if your code raises specific exceptions. If the specified exception is raised, that test passes, confirming that the expected error occurred. But if the specified exception is not raised, that test fails.

Usage Examples of pytest.raises

1. Checking for ValueError: In Python, a ValueError is raised when a function receives an argument with an incorrect value. In the example below, we can verify that a ValueError is raised when attempting to calculate the square root of a negative number.

    import pytest
    import math
   
    def calculate_square_root(value):
        if value < 0:
            raise ValueError("Cannot calculate the square root of a negative number")
        return math.sqrt(value)
   
    def test_calculate_square_root():
        with pytest.raises(ValueError):
            calculate_square_root(-1)
   

2. Checking for ZeroDivisionError: Dividing a number by zero raises a ZeroDivisionError. In this example, we check that this error is raised when dividing a number by zero.

    import pytest
   
    def divide_numbers(numerator, denominator):
        return numerator / denominator
   
    def test_divide_numbers():
        with pytest.raises(ZeroDivisionError):
            divide_numbers(10, 0)
   

3. Checking for TypeError: A TypeError is raised when an operation is applied to an object of an inappropriate type. Here, we check that this error is raised when adding incompatible data types, such as a string and an integer given in the example.

    import pytest
   
    def add_numbers(a, b):
        return a + b
   
    def test_add_numbers():
        with pytest.raises(TypeError):
            add_numbers("10", 5)
   

4. Checking for KeyError: A KeyError is raised when we try to access a dictionary key that doesn’t exist. We can verify and handle this error using the following code:

    import pytest
   
    def get_value(dictionary, key):
        return dictionary[key]
   
    def test_get_value():
        with pytest.raises(KeyError):
            get_value({"name": "Alice"}, "age")
   

Advanced pytest Features

As a robust testing framework, pytest offers some advanced features that help you manage complex test scenarios. In this section, we will explore some of these advanced features at a beginner-friendly level and demonstrate how you can start applying them in your tests.

1. pytest Markers

When working with a large codebase, sometimes running every single test can be time-consuming. This is where pytest markers come in handy.

A marker is just like a label that you can attach to a test function to categorise it. Once a test is labelled, you can instruct pytest to run only tests with certain markers. For example, you may label some tests as "slow" if they take longer to execute and run them separately from the faster ones.

One advantage to using Markers is that it allows you to run specific tests based on categories or specific parameters, and also skip tests if certain conditions aren’t met.

pytest comes along with some built-in markers that can be quite useful:

1. @pytest.mark.skip: This marker allows you to skip a test unconditionally, and can be useful when you know a test will fail due to an external issue or incomplete code.

   Example:

    @pytest.mark.skip(reason="Feature not yet implemented")
    def test_feature():
        pass
   

2. @pytest.mark.skipif: This marker allows you to skip a test conditionally if certain conditions are met.

   Example:

    import sys
   
    @pytest.mark.skipif(sys.platform == "win32", reason="does not run on windows")
    class TestClass:
        def test_function(self):
            "This test will not run under 'win32' platform"
   

3. @pytest.mark.xfail: This marker is attached to tests that are expected to fail, probably due to a bug or incomplete feature. So when pytest runs such tests, it won’t count it as a failure.

   Example:

    @pytest.mark.xfail(reason="division by zero not handled yet")
    def test_divide_by_zero():
        assert divide(10, 0) == 0
   

   Note: Detailed information about skipped/failed tests is not shown by default to avoid cluttering the output.

While pytest comes along with some built-in markers, you can also create your own custom marker (but we won’t cover that in this tutorial). Kindly refer to the documentation for more information on working with custom markers

2. pytest Fixtures

In pytest, fixtures allow you to create reusable default data that can be shared across multiple tests. By using fixtures, you can reduce code repetition, making your tests cleaner and more maintainable.

In pytest, fixtures are defined with the @pytest.fixture decorator as shown in the example below:

Let’s say we have several tests that rely on a list of user data. Instead of repeating the same data in each test, we can create a fixture to hold this data, and the fixture is passed across the tests that need it.

import pytest

@pytest.fixture
def user_data():
    return [
        {"name": "Alice", "age": 30},
        {"name": "Bob", "age": 25},
        {"name": "Charlie", "age": 35}
    ]

# Test function to check for a specific user by name and age
def test_user_exists(user_data):
    user = {"name": "Alice", "age": 30}

    # Check if the target user is in the list
    assert user in user_data

# Test average age of users
def test_average_age(user_data):
    ages = [user["age"] for user in user_data]
    avg_age = sum(ages) / len(ages)
    assert avg_age == 30

Note: The @pytest.fixture decorator in the code above marks the user_data function as a fixture in pytest. This fixture provides reusable data that can be shared across multiple test functions, allowing them to share the same setup without repeating code.

3. Parametrization

Parametrization is a pytest feature that allows you to run a test function with different sets of data at once.

For example: Let’s say you have a function that calculates the square of a number. To provide enough coverage while testing, you would want to test the function with zero, positive, and negative numbers.

Instead of writing separate test functions for each scenario, you can use parametrization to run a test function with different sets of data at once. This approach is more concise, and reduces code duplication.

To use parametrization in pytest, we use the @pytest.mark.parametrize decorator as shown in the example below:

import pytest

# Function to calculate the square of a number
def square_numbers(num):
    return num * num

#Parametrize decorator to test the square function with different inputs
@pytest.mark.parametrize("input_value, expected_output", [
    (2, 4),     
    (-3, 9),    
    (0, 0)    
])

def test_square(input_value, expected_output):
    assert square_numbers(input_value) == expected_output

In the example above, the different input values and expected values are listed in the @pytest.mark.parametrize decorator. We’re testing the square_numbers() function with three different input values: 2, -3, and 0.

For each value, pytest calls the test_square() function and compares the result of square_numbers(input_value) to expected_output.

This approach is more efficient and ensures the function behaves as expected across a variety of cases.

4. pytest Plugins

Plugins are an extension mechanism that allows you to add new functionality to pytest or modify its existing behaviour. These plugins work by providing additional features that extend pytest’s capabilities, which can be useful, especially in complex test scenarios.

pytest has a vast ecosystem of plugins, each designed to suit your different testing needs. You can find the full list of available plugins on PyPI in the pytest Plugin List.

To use a plugin, simply install it with pip.

For example:

pip install pytest-NAME
pip uninstall pytest-NAME

Note: NAME in the code above should be replaced with the name of the plugin you want to install.

After installing a plugin, pytest automatically finds and integrates it. There’s no need for any additional configuration.

In this section, we explored some of pytest's advanced features. By leveraging these features, you can now significantly improve the quality of your tests by ensuring they’re more efficient, scalable, and easier to maintain over time.

Conclusion

In this article, you’ve learned the basics of testing with pytest, from writing and interpreting tests to handling exceptions and using advanced features like fixtures and parametrization.

Whether your code is written manually or generated by AI, learning how to write tests empowers you to detect bugs early, and build more reliable software. Testing acts as a safety net that boosts you confidence during development and ensures your code works as expected.

If you're ready to go a step further, I’ve written an in-depth article on Test Driven Development in Python. It is a powerful approach where writing tests guides your entire coding process.

If you found this helpful, let me know, share it with your network, or give it a like to help others discover it too.

From healthcare to finance, robust software systems power our daily operations, making good software design essential to avoid inefficiencies and bottlenecks. This involves not just writing code but also designing systems that are easy to scale, maintain, and debug, while allowing others to contribute effectively.

Inefficient or ineffective software design can lead to significant issues, like scope creep, miscommunication within teams, project delays, resource misallocation, and complex systems that are difficult to maintain or understand. Without a strong design, teams often accumulate technical debt, which hinders long-term progress and increases maintenance costs.

This article will introduce you to key software design elements that will help you and your team address these challenges and guide you in building efficient, scalable systems. By understanding and applying these elements correctly, you can set up a project for both short-term and long-term success.

Prerequisites

I’ll explain these concepts through examples, but a basic understanding of programming in any language is required for this article (knowledge of Python will be especially beneficial).

Scope

The article will introduce key software design elements and explain them using an example. While I won’t provide a full software design for the example problem, I will include enough details to effectively illustrate each design element.

Table of Contents

• Overview of Key Software Design Elements

• A Walkthrough of the Software Design Process

  • Problem Statement

  • Use Cases

  • Requirements

  • High Level System Architecture

  • Detailed Software Design and Component Breakdown

• Conclusion: The Value of Thoughtful Software Design

Overview of Key Software Design Elements

To fully understand the benefits of the software design process, you’ll need to understand some key elements and their scope.

Once you have a good grasp of these, the next step is to define them for the specific problem at hand. Accurately defining these elements reduces risks and simplifies the implementation phase.

Doing this groundwork before implementation helps prevent late discoveries, minimizes the need for rewriting, and makes sure that the design can handle constraints and corner cases.

Now let’s briefly go over the key elements of the software design process:

1. Creating a problem statement: This step involves creating a clear and concise description of the problem that needs to be solved, along with its scope. The scope is essential because it focuses on the exact problem to be addressed and includes assumptions that must be considered during design.

2. Identifying use cases: This step outlines all possible user interactions with the software to achieve the desired outcome. It is a critical input to the architecture, as it helps create a design that addresses both general and edge-case use cases.

3. Stating requirements: This step defines the expectations of the software, such as its limitations, behaviors, and capabilities for different use cases.

4. Designing the architecture: This step provides a high-level structure of the software design, focusing on how to meet the requirements. The architecture typically includes components, how they interact, and how data flows through the system.

5. Drafting a detailed design: This step refines the high-level architecture into detailed, component-specific designs, ready for implementation.

In addition to these core elements, there are two important factors you need to consider throughout the design phase.

First, you’ll need to identify and state any assumptions you have. Assumptions can be present at any stage in the design process. Making correct assumptions increases the likelihood of success, improves focus, and reduces complexity in the design.

Second, you’ll need to create good documentation. Documentation is one of the most important elements in the software design process. It’s essential to document each stage as you go along. Documentation serves as the only formal record of the software design and is invaluable for presentations to management, for onboarding new team members, and for anyone returning to the project after a break. It saves valuable time and ensures continuity, as we often overestimate our own memory.

The figure below provides a visual summary of the key software design elements discussed in this section.

Next, we’ll apply these key software design elements to a practical example, demonstrating how each element contributes to building a robust and scalable system.

A Walkthrough of the Software Design Process

In any well-structured software project, clearly defining the problem is the first crucial step before diving into design and implementation. A well-defined problem ensures that the software meets user needs, remains maintainable, and scales effectively over time.

For this walkthrough, we will focus on designing a financial expense categorization system that processes and analyzes transaction data. This system is a part of a larger financial management solution and needs to be easy to debug, maintain, and scale.

Problem Statement

The problem statement provides a high-level goal for the software that we’ll design.

For this example, here’s our statement: Design a software solution that categorizes monthly expenses and generates a report from a list of transactions.

Define the scope

Defining the scope clarifies the smaller tasks that must be accomplished to meet the high-level goal. It outlines the focus of the software design and includes some assumptions.

Includes:

1. Implementing a parser to process a list of transactions provided as input.

2. Filtering transactions for a given month.

3. Analyzing, categorizing, and generating a report for each expense category.

Excludes:

Performance and memory optimization (excluded due to the limited scope of this article). While performance and memory optimizations are not the primary focus here, it’s important to keep future scalability in mind. Small design choices made now, such as selecting data structures, can help avoid significant refactoring later when the system grows.

Assumptions:

1. The list of transactions will be provided as a CSV file in the following format:
   Columns: "Date, Description, Amount, Type, Category Label".

2. Expense categories will be provided as input through a JSON file.

3. The software will run in a shell environment, and inputs will be taken as command-line arguments.

Now that the scope is clear, let’s examine how users will interact with the system through various use cases.

Use Cases

Use cases define how users will interact with the system to accomplish specific goals. Identifying accurate and valid use cases is critical to creating comprehensive requirements. Failing to capture enough use cases can lead to a design that is incomplete and lacks robustness. This may result in the need for redesigns, which increases time and resource consumption.

On the other hand, identifying too many use cases without considering their feasibility can lead to overly complex designs that are difficult to maintain and implement in the short term.

For our specific problem, the user will need to provide the following inputs while running the software in a shell:

1. A CSV file containing a list of transactions.

2. A month number.

3. A JSON file containing expense categories.

We need to consider all possible ways the user can interact with the script to achieve the desired outcome. For each of the three inputs, there are two possibilities: valid input or invalid input. This gives us 8 potential use cases (2 possibilities per input: valid and invalid). It's important to define what constitutes valid and invalid inputs for this problem:

• CSV File: Valid if it is in the format described in Assumption 1 (columns: "Date, Description, Amount, Type, Category Label").

• Month Number: Valid if the value is between 1 and 12.

• JSON File: Valid if it contains expense categories in the correct JSON format.

An input is invalid if it doesn't meet these definitions or if the input is absent.

It’s also crucial to consider the correlation between inputs when evaluating the feasibility of certain use cases, as they may interact with each other in unforeseen ways. Based on these use cases, we can now define the specific requirements that the system must meet.

Requirements

Now, let’s define the expected behaviors, limitations, and capabilities for each use case. Requirements serve as the foundation for architecture, specifications, and implementation. Based on our problem statement, the software will need to accomplish the following tasks:

1. The script shall take three inputs: a CSV file of transactions, a month number, and a JSON file of expense categories.

2. The script shall verify all inputs.

3. The script shall throw an error and exit if the CSV file cannot be opened or if it does not match the format in Assumption 1.

4. The script shall throw an error and exit if the JSON file cannot be opened.

5. The script shall throw an error if the month number is not between 1 and 12.

6. The script shall parse each transaction and load it into a data structure.

7. The script shall filter transactions by the specified month.

8. The script shall load the expense categories from the JSON file into a data structure.

9. The script shall categorize transactions based on the category label provided in the CSV file.

10. The script shall throw an exception if a category label in the CSV file is not present in the expense categories.

11. The script shall use a categorizing function to assign transactions to categories from the JSON file.

12. A class shall encapsulate categorized transactions, providing APIs to modify or access them.

13. The script shall support statistics calculation and report generation for categorized transactions.

With the requirements in place, we can now design a high-level architecture to meet those needs.

High Level System Architecture

In this stage, we will design the system at a high level, much like creating a master plan. Architecture involves organizing the software's functions into distinct components, illustrating how they interact, and mapping the flow of control and data through the system. While designing the architecture in this tutorial, we’ll incorporate good design principles.

For this example, the high-level requirements include:

1. Loading inputs and verifying them.

2. Applying time-based filtering.

3. Categorizing transactions based on category labels and descriptions.

4. Managing categorized transactions in a finance registry.

5. Generating reports from the categorized data.

One important component of software architecture is telemetry. Telemetry gathers data on the software's behavior, which is invaluable for debugging and performance assessment in real-world environments.

For smaller systems, simpler logging mechanisms may be sufficient to track basic errors and monitor performance. The decision to implement telemetry should depend on the complexity of the system and operational requirements.

Since telemetry provides such a helpful feedback loop for improving the design in future iterations, we’ll add it to the list of components here.

We’ll build our system architecture around a Test-Driven Development (TDD) approach. We’ll design each component with testing in mind to ensure it meets our requirements.

Just keep in mind that while TDD is a strong practice for ensuring code quality, it may not be the best fit for all projects. In scenarios where you need rapid prototyping or exploratory development, testing might be prioritized after initial iterations. Balancing between TDD and other methodologies depends on the project context and team preferences.

Our architecture will follow a modular structure, meaning the system will be divided into self-contained components. Each component will be responsible for specific functionality, making the system easier to test, maintain, and scale.

To achieve this, the architecture will emphasize loose coupling between components. Each component will interact with others through well-defined interfaces or APIs, ensuring minimal dependencies. We’ll abstract and encapsulate internal implementation details, exposing only the necessary information for interaction. Also, each component will handle its own errors and exceptions to ensure robustness and fault isolation.

But it is also important to consider a centralized error-handling strategy in some cases. Centralizing error handling can reduce redundancy, improve consistency, and make maintenance easier. The choice between local and centralized error handling should depend on the system's complexity and how components interact. This will contribute to the overall scalability and maintainability of the system.

Below is a summary of each component's functionality in this architecture:

• Load and verify input: This component will take the CSV file, JSON file, and month number as input, verify their validity, and load the data into structures.

• Time-based filter: This component will filter transactions based on the input month and store the filtered transactions in a data structure.

• Label-based categorization: This component will categorize transactions based on the category label in the CSV file.

• Description-based categorization: This component will categorize transactions using an algorithm based on the transaction description.

• Finance registry: This component will store all categorized transactions for further processing. It isolates the post-processing of categorized transactions from the categorization process and provides methods for updating or retrieving datasets.

• Report generation: This component will generate expense reports from the categorized transaction data.

• Telemetry: This component will monitor the performance of other components. It will track the flow of transactions, ensuring that all transactions are categorized either by label or description. Additional parameters can be added as needed to monitor specific functionalities.

The diagram below demonstrates the flow of data through these components:

Detailed Software Design and Component Breakdown

While we won't cover the full system design, this section will highlight key components and their specifications. For this example, I will assume the role of both the designer and implementer of the software.

Software design and specifications depend on several factors, including the designer's knowledge, skill set, available time, and resources. We’ll define some of the design details for the system, starting with the choice of the implementation language.

Choosing the right language is based on several important factors:

1. The language must meet the software requirements.

2. It should be stable, and have strong support from an active developer community.

3. Additional considerations include performance (speed and memory), scalability (ability to grow with future requirements), and platform support (ability to run on all major operating systems).

If you’re the one implementing this design, you’ll need to be familiar with and confident using that programming language. For this project, I chose Python because it meets all the project requirements, has a robust developer community for support, it’s stable, and I’m confident in using it to complete the implementation successfully.

Data Structures

Now, let’s look at the fundamental data structures that we’ll use in the design. We need to load the contents of the CSV file into a data structure for further analysis and processing. In Python, the Pandas DataFrame from the Pandas library is ideal for analyzing and processing tables, so we will use it to store the transactions.

For generating report, we will encapsulate categorized transactions along with relevant statistics, such as the total number of transactions, mean amount, and maximum amount, within a dedicated dataset class. This approach ensures a clear separation of concerns, where the dataset class manages data processing, while the reporting component focuses on presentation.

By structuring the system this way, we enhance reusability, maintainability, and scalability, making it easier to extend and modify in the future.

This dataset class will include:

• Member variables: category name, category description, a Pandas DataFrame for transactions, total number of transactions, mean amount, and max amount of transactions.

• Member functions: set/get DataFrame, save dataset to CSV (useful for debugging).

Here’s an example of a Dataset class in Python for structured data management and processing:

import pandas as pd  # Import Pandas for data handling

class Dataset:
    """
    A class representing a structured dataset with a name, predefined keys, 
    and a Pandas DataFrame.
    """

    def __init__(self, name, keys):
        """
        Initializes the Dataset object.

        Parameters:
        name (str): The name of the dataset.
        keys (list): A list of expected column names for the dataset.

        Attributes:
        self.name (str): Stores the dataset name as a string.
        self.keys (list): Stores the expected column names for data organization.
        self.mean_amt (float): Tracks the mean (average) transaction amount.
        self.max_amt (float): Tracks the maximum transaction amount.
        self.count (int): Stores the total number of transactions in the dataset.
        self.dataframe (pd.DataFrame): A Pandas DataFrame initialized with the specified column names.
        """
        self.name = str(name)  # Convert and store dataset name as a string
        self.keys = keys  # Store expected column names for consistency
        self.mean_amt = 0  # Initialize mean transaction amount to zero
        self.max_amt = 0  # Initialize max transaction amount to zero
        self.count = 0  # Initialize transaction count to zero
        self.dataframe = pd.DataFrame(columns=keys)  # Initialize empty DataFrame with predefined columns

    def getName(self):
        """
        Returns the name of the dataset.

        Returns:
        str: The name of the dataset.
        """
        return self.name  # Fixed: Removed incorrect parentheses

    def getValue(self, key):
        """
        Retrieves a specific column from the DataFrame.

        Parameters:
        key (str): The column name to retrieve.

        Returns:
        pandas.Series or None: The column data if the key exists, otherwise None.
        """
        if key in self.dataframe.columns:
            return self.dataframe[key]
        else:
            print(f"Warning: Key '{key}' not found in DataFrame.")
            return None  # Prevents KeyError

    def getKeys(self):
        """
        Returns the list of expected keys (column names) of the dataset.

        Returns:
        list: The keys defining the dataset.
        """
        return self.keys

    def setDataFrame(self, dataframe):
        """
        Sets the dataset's DataFrame while ensuring it contains only expected keys.

        Parameters:
        dataframe (pandas.DataFrame): The DataFrame to assign to the dataset.
        """
        if not isinstance(dataframe, pd.DataFrame):
            raise TypeError("Provided data is not a valid pandas DataFrame.")

        # Ensure only the expected columns are included
        self.dataframe = dataframe[self.keys].copy() if set(self.keys).issubset(dataframe.columns) else dataframe.copy()

    def getDataFrame(self):
        """
        Returns the DataFrame associated with the dataset.

        Returns:
        pandas.DataFrame: The dataset's DataFrame.
        """
        return self.dataframe

    def save_to_csv(self, file_name):
        """
        Saves the dataset's DataFrame to a CSV file.

        Parameters:
        file_name (str): The name of the CSV file to save.
        """
        self.dataframe.to_csv(file_name, mode='w', index=False)  # Save the DataFrame to CSV

In the previous section, we outlined the high-level system architecture, detailing the core components and their interactions. Now, let’s dive into the detailed design of some of the individual components, specifying how we’ll implement each one and how it’ll function within the system. We’ll also break down the components to explain how they work together to process the input and generate the report.

Below, you can see the flow diagram for the software, illustrating the interaction between the core components and the flow of data through the system.

Category Label-Based Filtering Component

The Category Label-Based Filtering Component classifies transactions by matching their "Category Label" with predefined expense categories from a JSON file. Transactions with valid category labels are stored in the finance registry, while unmatched ones remain for further processing.

• Input: DataFrame of time-filtered transactions, expense categories from JSON.

• Libraries used: Pandas DataFrame.

• Software design: Filters transactions based on the "Category Label" column and assigns them to corresponding categories. Transactions that cannot be categorized remain for further processing.

• Output: DataFrame of remaining transactions with empty values in the "Category Label" field.

• Component tests: Validate handling of valid, invalid, and missing category labels.

Finance Registry Component

The Finance Registry Component manages categorized transactions by storing them as datasets for each expense category. It maintains a structured collection of DataFrames, each containing transactions and summary statistics such as total count, max amount, and mean amount.

• Input: Expense categories from JSON.

• Libraries used: Pandas DataFrame.

• Software design: Implements a class that organizes datasets for all expense categories, providing methods to set and retrieve DataFrames.

• Component tests: Validate dataset creation, ensuring correct storage and retrieval of categorized transactions.

Here’s a simple and efficient Finance Registry implementation in Python for managing categorized financial datasets:

from Dataset import Dataset
import pandas as pd  # Ensure Pandas is imported if used elsewhere

# Define column structure for datasets
KEYS = ("Date", "Description", "Amount", "Transaction Type", "Category", "Account Name", "Labels", "Notes")

# Define dataset names for different financial categories
EXAMPLE_DATASET_NAMES = ("Investment", "Expense", "Savings")

class FinanceRegistry:
    """
    A class to manage categorized financial datasets, including investment, expense, and savings datasets.
    This registry allows structured access to transaction data and maintains aggregated financial metrics.
    """

    def __init__(self):
        """
        Initializes the FinanceRegistry object.

        Attributes:
        self.example_dataset (dict): A dictionary storing Dataset objects for financial datasets.
        """
        self.example_dataset = {name: Dataset(name, KEYS) for name in EXAMPLE_DATASET_NAMES}  # Create datasets for categories

    def setExampleDatasetToRegistry(self, name, dataframe):
        """
        Merges a new dataframe into the existing dataset for a given financial category.

        Parameters:
        name (str): The category name (e.g., "Investment", "Expense", or "Savings").
        dataframe (pd.DataFrame): The new data to be added.

        If the dataset already contains data, it concatenates the new dataframe to the existing one.

        Raises:
        ValueError: If the provided name is not a valid dataset category.
        """
        if name not in self.example_dataset:
            raise ValueError(f"Invalid dataset name: '{name}'. Expected one of {EXAMPLE_DATASET_NAMES}")

        df = self.example_dataset[name].getDataFrame()  # Get existing dataset

        if not dataframe.empty:  # Ensure the new dataframe is not empty
            dataframe = pd.concat([df, dataframe], axis=0, ignore_index=True)  # Append new data

        self.example_dataset[name].setDataFrame(dataframe)  # Update dataset in registry

    def getExampleDatasetFromRegistry(self, name):
        """
        Retrieves the dataset for a given financial category.

        Parameters:
        name (str): The category name (e.g., "Investment", "Expense", or "Savings").

        Returns:
        Dataset: The dataset corresponding to the given name.

        Raises:
        ValueError: If the provided name is not a valid dataset category.
        """
        if name not in self.example_dataset:
            raise ValueError(f"Invalid dataset name: '{name}'. Expected one of {EXAMPLE_DATASET_NAMES}")

        return self.example_dataset[name]

The diagram below illustrates how the Finance Registry organizes these datasets for further processing in the Report Generation component.

Report Generation Component

The Report Generation Component processes categorized transaction datasets from the finance registry and generates summary statistics. It calculates key financial metrics such as maximum amount, mean amount, and total transaction count. It also provides functionality to display categorized transactions in a structured format within the shell.

• Input: Datasets of categorized transactions from the finance registry.

• Libraries used: Numpy for calculations, Tabulate for formatted shell output (if needed).

• Software design: Implements a class with methods to compute financial statistics and display transaction summaries per expense category.

• Component tests: Validate correct calculation of mean, max, and total transactions, and ensure accurate display of categorized datasets in the shell.

Here’s a function to compute transaction statistics, including mean, max, and count, from a dataset in the report generation component:

from Dataset import Dataset
import numpy as np

def calculateStats(dataset):
    """
    Computes statistical metrics for a given dataset.

    Parameters:
    dataset: The dataset containing transaction data.

    Updates:
    - dataset.mean: Mean transaction amount.
    - dataset.max: Maximum transaction amount.
    - dataset.count: Number of transactions.
    """

    # Return early if the dataset has no transactions
    if dataset.dataframe.empty:
        return

    # Extract transaction amounts as a list
    tx_amount_list = dataset.dataframe['Amount'].astype(float).round(2).tolist()

    # Adjust transaction amounts based on "Transaction Type"
    for i, tx_type in enumerate(dataset.dataframe['Transaction Type']):
        if tx_type == 'debit':
            tx_amount_list[i] *= -1  # Convert debit transactions to negative values

    # Compute statistical metrics
    dataset.mean = round(np.mean(tx_amount_list), 2)
    dataset.max = max(tx_amount_list)
    dataset.count = len(tx_amount_list)

This concludes the design section, where we explored key software design elements with a practical example. The next step, implementation, is beyond the scope of this article. But it's crucial to recognize that new challenges often emerge during development, requiring updates to requirements, architecture, and specifications.

The purpose of this article is not to provide a full implementation, but to teach you some basic software design principles through an example. The focus is on understanding how to structure software, define clear requirements, and create scalable architectures, all before writing code.

By following a structured design process, you can shift complex problem-solving from implementation to the architecture phase, where you can explore solutions more effectively using flowcharts, block diagrams, and documentation. This makes the development process more organized, efficient, and maintainable, a crucial skill for real-world software engineering.

If you're learning to code, remember that good design is just as important as writing code itself!

Conclusion: The Value of Thoughtful Software Design

With well-defined problem statements, scope, requirements, specifications, and design, even complex problems can be solved and maintained in a sustainable way.

The steps we went through in this article can help you break down any problem, regardless of its complexity, into smaller, actionable tasks that you and your team can efficiently tackle.

Without proper planning, projects are often plagued by scope creep, wasted time and resources, miscommunication between teams, overly complicated designs, technical debt, and frequent redesigns.
Good design is often simple design, but achieving simplicity is difficult without thorough planning.

Approaching each problem with the mindset of defining a Problem Statement, Scope, Use Cases, Requirements, Architecture, and Specifications helps cultivate a strong software design mindset. This mindset is crucial for developing software that is scalable, maintainable, and high quality.

TDD, or Test-Driven Development, is a software development approach where tests are written before the actual code is implemented.

It requires a clear understanding of "What" and "How" in the the requirements of the project/feature.

TDD helps to write less, but enough code. It helps prevent common software development mistakes, such as over-engineering, too much test coverage, missing main requirements, too large functions and classes, and too many complicated code statements.

Overall, it helps to have a concise, already unit-test covered, clean codebase. Over time, it also saves development and code maintenance costs.

In this article we will discuss TDD in action.

The context is an Android development environment, so we will use Kotlin and JUnit5 with a sample project to demonstrate the steps.

However, the instructions and techniques here can be practiced in other programming languages as well.

Prerequisites

• Basic knowledge of Kotlin
• Basic knowledge of writing Unit tests
• Knowledge of mocks and assertions

We will use Kotlin as the programming language and JUnit5 to write unit tests.

Mockito will be used to work with mocks and spys.

The target audience is any software developer from any platform seeking a new chapter in their career.

Even though the context is Android, the content does not talk about platform specific properties. Instead, we focus on techniques, notes and challenges when developing with TDD.

If above is OK with you, let's get started.

How Test Driven Development Works

TDD Cycle

The development process follows a cycle of:

1. Writing a failing test (pink square).
2. Implementing the code to make the test pass (green square)
3. Refactoring the code (blue square) as needed while ensuring that the tests continue to pass (pale green square).
4. Writing a new failing test (restart the flow again)

Writing a Failing Test (Pink Square)

In this step, you start by describing what you want your code to do.

Imagine you're giving your code a test to check if it behaves correctly. This test is like a question you ask your code, such as "Can you do this task?"

At first, your code doesn't know the answer, so you write a test that should fail because your code doesn't know how to do the task yet. This failing test is like a pink warning sign that tells you something isn't right.

Once you've finished this stage, JUnit5 will generate a comprehensive report from the tests you've crafted. These tests will stand as a tangible representation of your work.

Now, imagine that your project manager is reading these test cases to assess both their coverage and the accuracy of your grasp on the feature or product. Embracing this perspective offers a clearer understanding of the significance of this developmental phase.

Shift your focus from technical intricacies to the software's behavior itself.

Instead of getting caught up in the nitty-gritty technical aspects, direct your attention to how the software functions and interacts with users and other components.

This shift in perspective allows you to prioritise the software's intended actions and outcomes, leading to tests that accurately reflect its real-world behavior.

By concentrating on behavior rather than technical minutiae, you ensure that your tests align closely with the software's purpose and user expectations.

In some cases, You might end up with no more than a few test cases per component (which is the purpose: less work but targeted) and that's totally fine, as long as you cover all the behavioural requirements of the project.

Tips

• Be specific: Write clear and specific test cases that focus on one aspect of your code's behavior.
• Start simple: Begin with the simplest test case that covers the basic functionality you need.

@Test fun `a sum is calculated from two input numbers`() {}

• Use meaningful names: Name your tests descriptively so that anyone reading them knows what the test is checking.

@Test fun `Font Ratio is fetched from data source INITIALLY`() {}

Common mistakes to avoid

• Testing too much at once: Avoid testing multiple things in a single test. This can make it hard to identify what's failing.

// Don't do this
@Test fun `pixelSize fits the standart sizes while fontSize is bigger than minumum supported font size but matches the list of special levels of size`() {}

• Relying on implementation details: Don't write tests that are tightly coupled to the code's inner workings. Tests should focus on behavior, not implementation.

// Don't do this
@Test fun `pixelSize is Long and Non-Null and fits the standart sizes then calculated font size is non-null and of type Dimention`() {}

Implementing the Code to Pass the Test (Green Square)

Now that you have your test in place, it's time to teach your code how to do the task correctly.

You write the actual code that should make the test pass and your code answer the question correctly.

When your code passes the test, it's like a green light saying, "Yes, I can do the task now!".

This step is about making sure your code understands and can solve the problem you're asking it to.

Tips

• Write minimal code: Write the simplest code that makes the failing test pass. You can read more about how to avoid over-engineering here.

// Test Case 
@Test fun `Storage stores font ratio in key-value`() { 

    // Given
    val fontRatio = 2.0f
    val mockEditor = mockk<SharedPreferences.Editor>(relaxed = true)
    every { mockSharedPreference.edit() } returns mockEditor 
    every { mockEditor.putFloat(any(), any()) } returns mockEditor 
    every { mockEditor.apply() } just Runs 

    // When 
    storage.saveFontRatio(fontRatio) 

    // Then
    verify(exactly = 1) { 
        mockEditor.apply() 
    }
}


// Correct Implementation - Avoid extra implementation
class SharedPreferenceHelper( 
    private val sharedPreferences: SharedPreferences 
) { 
    fun saveFontRatio(fontRatio: Float) {
        sharedPreferences.edit().putFloat("font-ratio", fontRatio).apply() 
    } 
}


// Wrong Implementation 
class SharedPreferenceHelper(
    private val sharedPreferences: SharedPreferences
) { 
    fun saveFontRatio(fontRatio: Float) { 
    if (fontRatio <= 0.0f) 
    throw IllegalArgumentException("Font ratio must be greater than 0.0f") 

    storeValue(key = FONT_RATIO_KEY, value = fontRatio) 

} 

    private fun storeValue(key: String, value: Float){
        val editor = sharedPreferences.edit() editor.putFloat(key, value)
        editor.apply() 
    }

    fun getFontRatio(): Float { 
    return sharedPreferences.getFloat("font_ratio", 1.0f) } 
}

• Avoid duplication: Don't repeat code. If you find yourself writing similar logic in multiple places, consider refactoring. This primary code improvements can be done in this phase, but if the modification can have a side-effect then ignore it.

class ... {
    override fun getDefaultFontSize(): Float {
        val zoomRatio = DEFAULT_SSPEED * DEFAULT_FONT_RATIO / deviceDensity 
        val fontSize = zoomRatio * standardFontSize 
        return fontSize 
    }
    override fun getFontSizeBySSpeed(speed: Int): Float {
        val zoomRatio = speed * DEFAULT_FONT_RATIO / deviceDensity 
        val fontSize = zoomRatio * standardFontSize 
        return fontSize 
    }
}

class ... { 
    override fun getDefaultFontSize(): Float = calculate(DEFAULT_AGE)
    override fun getFontSizeByAge(age: Int): Float = calculate(age) 

    private fun calculate(age: Int): Float {
        val zoomRatio = age * DEFAULT_FONT_RATIO / deviceDensity 
        val fontSize = zoomRatio * standardFontSize 
        return fontSize 
    }
}

Common mistakes to avoid:

• Jumping Ahead: Don't write more code than necessary to pass the test. TDD is about incremental development. TDD encourages an incremental and step-by-step approach to development. When you jump ahead, you're essentially trying to solve problems that are not yet directly related to the current test you're working on. The primary goal is to focus on the immediate task at hand – passing the current test – without getting sidetracked by future functionalities.
• Ignoring Test Failures: If a test doesn't fail initially, you might be missing an important case. This might seem unlikely to happen at first sight, but after some development in your test components you'll start writing multiple tests for a single method to test different aspects of the logic. This is where you should not be happy if your unimplemented logic passes the test. In simple words, this is how you catch bugs in development phase. So, expect the failure when it should be.

Refactoring the Code (Blue Square) and Ensuring Test Success (Pale Green Square)

Once your code passes the test, it's time to clean things up.

You might see ways to make your code more organised, easier to understand, or even faster. Think of it as tidying up your room once you're done playing, making everything neat and organised after you've finished playing.You improve your code without changing what it does.

As you do this, you keep running all your tests to make sure they still pass. If a test fails during this step, it's like a pale green caution sign telling you that something you cleaned up might have accidentally broken the code.

You can treat this part as a separate code maintenance phase.

Assume that you are given the task to clean up an old code and make sure it follows team code quality guidelines as well as product requirements.

Throughout this process, the key is to maintain a careful balance – refining while ensuring your tests continue to succeed.

Here are some ideas and strategies for the refactoring phase:

• Code clarity: Simplify complex sections, replace unclear variable names, and enhance comments to make the code easier for others (and your future self) to understand.
• Modularity: Break down large functions into smaller, focused ones. This makes your code more modular and allows for easier maintenance and testing.
• Remove redundancy: Identify duplicated code and consolidate it into reusable functions or classes. This helps eliminate repetition and ensures consistency.
• Optimization: Identify areas where performance can be improved. However, only optimize if you have specific performance goals and evidence that the code is a bottleneck. Optimization here is to avoid resource drain and not to make the code performant.
• Consistent formatting: Maintain a consistent code style, adhering to the conventions of your team or project.
• Unused code: Remove any unused variables, functions, or imports that clutter the codebase.
• Test improvements: Unlike the usual perception regarding TDD, you can add tests whenever there is a need for it. Enhance the test suite by adding new test cases to cover scenarios that weren't previously addressed. This helps maintain comprehensive test coverage.
• Documentation: If your code's purpose isn't immediately clear from the code itself, consider adding or improving documentation to explain its intent and usage. Avoid making it a habit. This is meant to act as a complementary explanation for crucial cases to avoid confusion.

Note that TDD code should be self-expressing and independent of documentation.

Remember, while refactoring, it's crucial to keep running all your tests to ensure they continue to pass.

Tips

• Keep tests comprehensive: Make sure your tests cover various scenarios to catch unintended side effects during refactoring.
• Refactor gradually: Make small changes to your code and run tests frequently to catch any regressions early.

Common mistakes to avoid:

• Refactoring without tests: Refactoring without having tests in place can lead to unexpected behavior. If there is a chance to miss a part of the logic then consider writing tests for it.
• Large code change: Sometimes we end up changing more number of lines than what we developed to make the test pass. Always consider a separate refactoring phase over making too much changes in development phase as it's a safer & less costly option.

Writing a New Failing Test (Restarting the Flow)

Now, you think of the next thing you want your code to do.

You start by writing a new test that should fail because your code doesn't know how to do the new task yet. This is like giving your code a new challenge to solve.

Then, you repeat the whole cycle: make the test pass with code (green square), clean up if needed (blue square), and keep testing to make sure everything works (pale green square).

This way, you're always moving forward and building your code step by step.

Tips

• Incremental steps: Add new tests for new functionality in small increments to maintain a clear development path. Instead of attempting to implement a complex feature all at once, you break it down into smaller, manageable pieces and create tests for each of these pieces. This approach maintains a clear and steady development path, helping you to stay focused, reduce risks, and ensure that each addition to your software is thoroughly tested.
• Feedback loop: Use the feedback from writing failing tests to guide your implementation. Feedback loop highlights the iterative nature of TDD. As you craft new tests and observe them failing, you gain valuable insights that guide your implementation.

Here's how the feedback loop works:

• Expectation setting: When you write a new test, you define your expectations for how the code should behave. This clarifies what you're aiming to achieve with your new feature.
• Initial failure: The test fails at first because the corresponding code to fulfill its expectations is missing or incomplete. This initial failure is a natural part of the TDD process.
• Guides your implementation: The feedback from the test's failure points you in the direction of what code needs to be written or modified. It becomes a roadmap for your development, outlining what the new functionality should look like.
• Incremental Progress: As you implement the necessary code to make the test pass, you're incrementally building up the desired functionality. Each step is guided by the feedback provided by the failing test.
• Verification: Once your implementation is complete, you run the test again. If it passes, it verifies that your new code satisfies the expectations you initially set.

The feedback loop ensures that your development is tightly aligned with the intended goals of your software.

Common mistakes to avoid:

• Writing tests after implementation: Don't write tests after you've implemented the feature. TDD is about writing tests first. Even a tiny piece of logic added before the test code means there is a possible resource waste/bug in the code. The whole point is to not to add any logic unless there is a need for it from test suite.
• Skipping failing tests: Don't skip this step even if you think you know how to implement the feature.

Here is why you should not skip the failing tests step even when you're confident:

• Clarity of intent: Writing a failing test clarifies your intent for the feature. It forces you to consider the exact behavior and outcomes you're aiming for before diving into implementation.
• Verification of assumptions: Even if you think you understand the feature, creating a test ensures that your assumptions are valid. Your understanding might be correct, but the test validates it.
• Safety Net: By writing a failing test, you establish a safety net that prevents regressions in the future. It acts as a specification for the feature and helps catch unintended side effects.
• Incremental development: TDD encourages incremental development. Each new feature is built step by step, with a clear progression from failing test to working implementation. Skipping this step disrupts that progression.
• Documentation: The failing test documents the expected behavior of the feature. This documentation is valuable for you and your team, especially when revisiting the code in the future. Always remember that there are systems to generate reports by listing out all of your test code for product managers and QAs. Those reports expose the details you spotted in the product, So, try to convince them that you understood the point thoroughly.

How to Develop Using TDD

TDD emphasises the importance of writing automated tests to drive the design and development of software. This leads to code that is more reliable, maintainable, and easier to change over time.

But how can we put it into practice? By trying it out and getting used to it gradually.

Let's try TDD while developing a new feature to demonstrate how we can start using it in real world.

We will be implementing a font size auto setting feature.

We have a news app and a user can set auto-scroll-speed for news feed.

We want to implement a feature which adjusts the screen font size from the scroll speed set in the User Profile page.

If the user sets the scroll speed from 0 to 1, then the font size should increase by 1.3.

Any scroll speed increment over 1 will result in increase of the font size by 1.2.

This feature allows users to have a better experience while reading the news.

I've also shared the code we explore in this GitHub repository.

Feel free to clone and play with it.

Try to follow the steps as we progress in the development. This will help you grasp the techniques and the way of thinking in the context of TDD practically.

So, open Android Studio and create a new project.

Font Size Auto Setting Feature Data Flow Chart

DFD of a sample feature in an android app

Above is the flowchart of what the data flow should look like in the end.

Here's an outline of each engaging component:

The AutoScrollSettingsUseCase class will handle the logic for calculating and storing the FontRatio based on the selected Scroll Speed.

This use case will have a dependency on the UserRepository storing the FontRatio value.

In the UserRepository, there are methods to store and retrieve the FontRatio value using the Storage mechanism. Whenever a new FontRatio is sent to the storage, any observables will receive an emission with the latest value.

In the UserProfileViewModel, there is an instance of the AutoScrollSettingsUseCase that is being called whenever the user updates the Scroll Speed. This will trigger the recalculation of the FontRatio and its stored via the repository.

We will have the necessary UI components in the User Setting section to allow the user to input their desired scroll speed. This can be done using standard Android UI elements such as NumberPicker or custom UI components (We will not discuss these parts).

This is the breakdown for a simple feature and every time you go through it, it becomes more clear what are the steps and the final result. It's crucial to do it for your changes.‌ ‌

How to Write the Tests

The first step is to always create the test class itself. In this case, we will have at least the following test classes:

• UserRepositoryTest
• AutoScrollSettingTest
• UserSettingsViewModelTest

I prefer to start with the ViewModel part.

A ViewModel is an Android Architectural component which escapes lifecycle changes (such as foreground, background, focused). So, it's a fine place to store our states.

Let's create the test file inside the unitTest directory of the source code following the same package path as the real feature code.

TDD in practice is dissimilar to legacy work development.

With TDD we use an IDE to boost file and property(fields) creation process. But we create Test files manually! After a few tries, this aspect of IDE will become handy.

Create the code structure (packages) and then create your test class by right clicking on the package and selecting the Class type.

Choose a descriptive name for it (maybe you should follow a convention for it if you're not already).

For instance: xxx is tested for, where xxx is the name of the tested component.

Use IDE To Create Files

Now, let's create empty tests. Try to be as broad as possible.

According to the diagram, we will not have much logic for this feature.

There are two main strategies for writing unit test functions:

• AAA
• Given/When/Then

@Test fun `strategy A`(){ 
    // Arrange
    // Act 
    // Assert 
}

@Test fun `strategy B`(){ 
    // Given 
    // When 
    // Then 
}

Let's choose one and follow it for all your tests.

The concept is the same: cluster your test code to make is easy to read and maintain.

This is what I have for now:

class UserProfileViewModel is tested for` {
    // Unimplemented Class 
    val viewModel = UserProfileViewModel()

    @Test
    fun Font Ratio is fetched from data source`(){}

    @Test
    fun `Scroll Speed update is called so fontSize calculations are triggered`() {}

    @Test
    fun `Font Ratio is updated with new emissions from data source`() {}
}

Let's run the tests!

Failed Test Due To a Missing Test Target

It's failing. In fact, the build has failed- Not the test.

Congratulations! We just made it to the first step in TDD cycle:

First step in TDD cycle

Since the ViewModel does not exist yet, we have red colors.

Now, let's create an instance of the ViewModel,

So, we use an IDE to create a missing class or unimplemented code.

To make this dialog popup, I move the pointer to the unimplemented part and hit Option + Return (on macOS).

Then, follow the provided options:

TDD Action: Create Target Files through UnitTest file

Choose The Correct Destination For The New File

And now let's re-run the tests (last step):

Showing the test passing

Yes! It passed.

Note that these tests have an empty body and they test nothing! That's correct and alright.

We should even continue to create all the test classes (still with an empty test body) for every component in the DFD diagram - I shared these at the beginning of the article.

This further helps to have a more clear understanding of the feature before we implement it.

Eventually, we will have around 3-4 test classes containing general scenarios and Unit tests to cover.

It will look something like this:

Minimal Empty Test Cases

Let's implement one of them as an example.

But, before that, we are going to need to work with UI and Domain data models of this feature.

So, in order to be able to move the data around, let's create the data classes you need in advance.

Back to our ProfileViewModel test class, we have an empty unit test function. Let's implement that one.

Note that the key here is to read the test carefully and avoid extra implementation neither assertions.

Only the requirement is allowed to be implemented.

In this case, we need a stream of data which is connected to a previously created data source(UserRepository).

Don't forget: We need a Failing Test first.

Implement Inner Body

Notice the unimplemented parts inside the test function body (marked with red font).

Now, let's implement the code, then refactor it to make it just pass.

I'm using the MockK library for mocking classes and objects and Turbine to test Flow streams here.

If you are not familiar with them don't panic! Just check out their official webpage and try them out.

Let's create the dependency first and add it to the ViewModel using Named Arguments. Named Argument helps us when creating the parameter via IDE to introduce proper names through the test code.

Create Missing Parameter Using IDE Dialogs

Do the same for the FontRatio variable inside the Repository.

Eventually ,the final test code can be something like the code below:

class `UserProfileViewModel is tested for` {

    init {
        Dispatchers.setMain(Dispatchers.Unconfined)
    }

    val mockUserRepository = mockk<UserRepository>()

    @Test
    fun `Font Ratio is fetched from data source`() = runTest {
        // Given
        val expectedRatio = 2.0f
        every { mockUserRepository.fontRatio } returns flowOf(FontRatioUiModel(expectedRatio))
        val viewModel = UserProfileViewModel(userRepository = mockUserRepository)

        // When
        viewModel.fontRatio.test {
            val fromDataSource = expectItem()

            // Then
            assertEquals(/* expected = */ expectedRatio, /* actual = */ fromDataSource.fontRatio)
        }
    }
...
}

Note that we don't implement inner parts of the ViewModel or Repository here.

We just create the missing parts to remove error from the test body.

We will implement those details in a next iteration.

Run the test now.

Of course it will fail, because we did not implement FontRatio inside ProfileViewModel.

Now, refactor the ViewModel to make the test pass (minimal implementation).

In this case, just need to connect the state flow to the repository. We already added it as a dependency in the previous iteration.

Here is the final code:

class UserProfileViewModel(
    userRepository: UserRepository
) : ViewModel() {

    val fontRatio: StateFlow<FontRatioUiModel> = userRepository.fontRatio.stateIn(
        initialValue = FontRatioUiModel(DEFAULT_FONT_RATIO),
        scope = viewModelScope,
        started = SharingStarted.Lazily
    )

    companion object {
        private const val DEFAULT_FONT_RATIO = 1.0f
    }
}

Run the test again, And Boom! It passes!

Passing Test After Minimal Implementation Of Main Code

With this Unit test, we implemented a primary part of the UserProfileViewModel component. But only the necessary parts. Do the same for the rest of the test cases.

Do not treat these test cases like you do with normal Unit tests (which run and pass quickly).

Spend some time on it to understand the technical and product requirements first. Then, rollout the plan and start implementing. After a few tries, it'll be easier to think the TDD way.

Source Code

The source code and the repository for this project is available on my GitHub page.

Feel free to check it out and complete next steps. I've separated iterations in different branches so you can compare it with your own implementation.

Conclusion

So, after diving into Test-Driven Development (TDD) and exploring its ins and outs, I've got to say, it's a game-changer!

Let me break it down for you:

Key Points:

• TDD is all about writing tests before writing the actual code. It might sound a bit weird at first, but trust me, it works wonders.
• The TDD process follows a simple cycle: write failing tests, implement the code to make those tests pass, and then refactor as needed to keep everything running smoothly.
• By emphasising automated tests, TDD helps us design and develop software that's solid, maintainable, and adaptable over time.

We started by creating test classes and writing empty test functions but it's your task now to finish it (Or you can jump to the shared repo right away :) ).

It might seem a bit odd to have tests that don't do anything, but it's all part of the plan.

Next, we laid out a clear plan of what our feature should do, based on a data flow chart. This helped us understand the requirements before diving into the implementation.

With the plan in hand, we began implementing the necessary components (ViewModel in this case), making sure our tests failed first. That's right, failing tests are actually a good thing in TDD!

Gradually, we connected pieces together, like setting up the UserAutoScrollSettingsUseCase class to handle font size calculation based on the auto-scroll speed (Check project repo).

We also tackled UI components, allowing users to input their desired scroll speed, and making sure the font size was adjusted accordingly (Check project repo).

Throughout the process, we made sure to keep our code clean and simple, focusing on what was needed to make the tests pass. No unnecessary complexity here!

By the end, we had our "Font Size Auto Setting" feature up and running, with tests that passed with flying colours.

Remember, TDD isn't about rushing through tests or coding like crazy. It's about being deliberate and thoughtful in your development process, which pays off big time in the long run.

So, if you're looking to level up your software development game, give TDD a shot! It's a powerful approach that will make your code more solid, reduce bugs, and make you a better developer overall.

What I've shared is, how we work in my team and it's working for us, but it's not the perfect solution for every team/company. You need to find out whether it's yours or not. Let me know if you think I can improve this solution.

Happy coding! 🚀

Test Driven Development (TDD) is one of the best ways to make sure your code is high quality and works like it's supposed to work. It can also help you create reliable builds during continuous deployments.

In this post, we will learn how to create a Svelte application using TDD methods.

What We're Building

We are going to build a vertical tabs component where we can switch between three tabs. We are going to build this component by writing test cases first and developing the component functionality after that to make the tests more effective.

Final implementation

Prerequisite

I will explain all the steps needed to create an app and you can follow along with the code. It's great if you have basic programming knowledge and fundamental knowledge of HTML and CSS for this tutorial.

Also, you'll need to have Node.js installed. You can see how to do that here if you don't have it already.

What is Test-Driven Development?

The basic idea of test-driven development, or TDD, is to write the test before you implement the actual functionality. This helps you clearly figure out what you're developing and how it works.

You first watch the test fail, and then you write the code to make it pass. This ensures that there are no false positive tests in your code.

TDD is a methodology you can apply to any programming language. It is more prevalent when developing backend applications that contain business logic that you can easily test.

The good news is, you can apply similar techniques to test your front-end applications as well.

Three stages of TDD

The three stages of TDD are:

1. Red stage – Write the test and watch it fail
2. Green stage – Write the minimum code required to make the test pass
3. Refactor – Cleanup and refactor the code to make it more robust

Three stages of TDD

What is Vitest?

Vitest is an up-and-coming testing framework which has similar functionality to Jest.

Since we are using Vite as our build tool for Svelte in this tutorial, Vitest has very good integration with Vite and offers a similar testing environment without needing extra configuration.

How to Create a Svelte Application

We are going to create a Svelte application using Vite as the build tool. You can do that with this command:

npm create vite@latest

This will create a new project, and you can follow the steps below to create and setup the project:

1. Enter the name of the project. This will also create a new folder with the project name. In this example, I will add the project name as svelte-tdd-vitest.
2. You can select the framework in the next step. Let's choose svelte as the framework.
3. Then you can enter the variant of the framework. We can choose the TypeScript variant for this article. If you are not comfortable with TypeScript, you can also choose JavaScript in this option.

Initialise Svelte project with Vite

You can then follow the helpful steps provided in the terminal to install the dependencies and start the application. Run the following command:

cd svelte-tdd-vitest
npm install
npm run dev

npm install will install the dependencies of the project.

npm run dev will start the development server. You should see the app running in the port specified in the terminal.

Vite Server started using npm run dev

Congrats, you can now see the starter app running in your browser. You can open the project in your favourite Code Editor and start working.

How to Set Up Vitest

You can add Vitest to the project right now as a dev dependency. This means that Vitest will not be packaged into the production build of the application since you will be running the test in your local environment.

npm install -D vitest

Vitest can read the config of Vite inside the vite.config.js file and prepare the test environment similar to the build environment. This makes the test more reliable. So you can reuse the Vite config file and add more options for the configuration of Vitest.

You can also override the config for the Vitest by creating a new file called vitest.config.js in the project root. So now, create a new file called vitest.config.js:

import { defineConfig } from 'vitest/config'
import { svelte } from '@sveltejs/vite-plugin-svelte'

export default defineConfig({
  plugins: [
    svelte({ hot: !process.env.VITEST }),
  ],
  test: {
    environment: 'jsdom',
  }
})

There are a couple of configs we are adding to the file

1. We are disabling Svelte's hot module reload when tests are running.
2. We are defining the environment for running the test as jsdom. It helps in mocking the DOM API and running the tests in a reliable method.

In order to use the jsdom you need to add it as an Dev Dependency as well. So let's install that package using the terminal.

npm install -D jsdom

After installation, let's add a couple of scripts to the package.json file to start the Vitest test from the npm command line:

"scripts": {
    ...
    "test": "vitest",
        "coverage": "vitest run --coverage"
}

How to Create the First Test

You now have all the setup needed to write your first test. Create a new file called sample.spec.ts inside the lib directory.

import {describe, test, expect } from 'vitest';

describe("Example File", () => {
    test("Sample test", () => {
        expect(1 + 3).equal(4);
    });
});

Let's break down the different functions used to create this test file:

1. describe – you use this to group similar test together and benchmark tests when generating your reports. It takes a name and a function that contains the group of tests.
2. test – Represents a single test. It can contain multiple expectations within it. It is created by passing a name of the test and the function to run the test.
3. expect – Represents the expression which you're testing.

There are multiple different ways to write your test based on what you are testing. You can have a look at the complete API for Vitest in the official API Reference.

Let's run the test using the following npm command:

npm run test

Running the test

How to Add the Global Test Config

You are going to be using the describe, test, and expect functions a lot in the test files and it might be verbose to import them in all the test files. So Vitest has a nice config where you can set these global imports and so you don't have to add them to each file.

So let's update the vitest.config.js file with this configuration:

export default defineConfig({
  ...
  test: {
    ...
    globals: true
  }
})

After adding this globals equals true line in your config, you can now remove the imports in your spec file.

If you are using TypeScript, your TypeScript compiler will complain in your spec file. You can solve that by adding the following line to your tsconfig.json file:

{
  "extends": "@tsconfig/svelte/tsconfig.json",
  "compilerOptions": {
    ...
    "types": ["vitest/globals"]
  },
}

Now your test can look like this. This is not a huge upgrade for this small file, but when you have lots of spec files, this config change is useful.

describe("Example File", () => {
    it("Sample test", () => {
        expect(1 + 3).equal(4);
    });
});

How to Create a Svelte Component

We will create a new svelte component called VerticalTabs.svelte. The requirements are to create a vertical tab component that can contain a few items and for the user to be able to select a particular tab to view its content in the right side.

The component will be divided into two parts. The left side displays all the tabs. The right side displays the content based on the tab.

Let's create the basic HTML and CSS styles needed for the component. We will add the functionality to switch tabs after writing the tests.

<div class="vertical-tab-container">
    <ul class="vertical-tab">
        <li>First Tab</li>
        <li>Second Tab</li>
        <li>Third Tab</li>
    </ul>

    <div class="vertical-tab-content">
        <h2>First Tab Heading</h2>
        <p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Autem aut deserunt veniam tempora deleniti quos reprehenderit natus. Animi, obcaecati dolorum, culpa, maiores maxime ullam soluta unde rerum nihil temporibus quibusdam!</p>
    </div>
</div>

<style>
    .vertical-tab-container {
        display: flex;
        flex-direction: row;
        align-items: center;
        border: 1px solid gray;
        border-radius: 1rem;
    }

    .vertical-tab {
        margin: 0px;
        padding: 3rem;
        list-style: none;
        border-right: 1px solid gray
    }

    .vertical-tab li {
        margin: 2rem 0;
    }

    .vertical-tab-content {
        flex:1
    }
</style>

In this code, you are adding simple elements like an unordered list to display the list of tabs. You are styling it in the <style> tag which will be locally scoped CSS for this component.

Then, you are adding <h2> tag to display the tab heading and a paragraph tag <p> to show more dummy text for the tab. You're using flex to show the two items side by side and the property of flex: 1 on the content will make that container take all the remaining available space to expand.

The component should look like the below image:

Vertical Tab initial

How to Mount the Svelte Component in Test

Now you need to create the first test for the component by mounting the svelte component and then checking to see if you can find the "First Tab" text in the component.

So create a new spec file called VerticalTabs.spec.ts:

import VerticalTabs from "./VerticalTabs.svelte";

describe("VerticalTabs Component", () => {

    test("should render the component", () => {
        // Create a new container for the test
        const host = document.createElement('div');

        // Append the new container in the HTML body
        document.body.appendChild(host);

        // Create an instance of the vertical tab
        const instance = new VerticalTabs({ target: host });

        // Check if the instance has value
        expect(instance).toBeTruthy()

        // Test if we can find the "First Tab Heading"
        expect(host.innerHTML).toContain("First Tab Heading")

    });

})

In order to mount the Svelte component, you need to first create a div container and attach that div to the body of the HTML document. Then you need to attach your component to the div. You can then test the innerHTML of the main container to see if you have the required content.

Now this test should pass since you have the First Tab Heading content displayed in the component.

Going through this long process in all the steps might prove to be difficult. So let's add another package to make the job easier. The package is testing-library/svelte and it provides more features to make the assertions easy and less verbose.

How to Use the Svelte Testing Library

First, you'll need to install the library:

npm install -D @testing-library/svelte

Let's update the previous test to make it less verbose and let testing-library handle all the heavy lifting for us. You can use the render function to add the component to the testing page.

import VerticalTabs from "./VerticalTabs.svelte";
import { render, screen } from '@testing-library/svelte';

describe("VerticalTabs Component", () => {

    test("should render the component", () => {

        render(VerticalTabs);

        const firstTabNode = screen.getByText(/First Tab Heading/i)

        expect(firstTabNode).toBeTruthy()
    });

})

After the render function, add the component to the testing page. You can use the screen object imported from the library to query the nodes that are rendered.

There are multiple methods inside this object to make testing easy, and you will use one of the methods to get the text in the component.

getByText will return the instance of a given text. You are expecting the node to contain some value.

There are three main ways to retrieve the element in the testing library, and each serves a different purpose:

1. getByText – This will throw an error when the text is not found and the test will fail
2. queryByText – This will return null when the text is not found
3. findByText – This will also throw an error when the text is not found and you can use it when doing async tests where the element will take some time to appear/disappear

You can find a useful summary of these helper functions in the official docs page.

Summary screenshot from Official docs of testing library

You can find more details on this API in this official page.

How to Build the Tab Switching Feature

We will start adding the feature to switch tabs in the component and test the component by writing the test first.

Red stage

Let's write a test the switch to a different tab on click of the "Second Tab" list item.

Since we don't have this functionality implemented, we will fail this test first and that's okay. Once we fail the test, we should write the logic to make it pass in the next step.

So let's write a failing test:

test("should switch tabs", async () => {
        render(VerticalTabs);

        const secondTabElement = screen.getByText(/Second Tab/i);

        fireEvent.click(secondTabElement)

        await screen.findByText(/Second Tab Heading/i);
})

We are using the fireEvent from the testing library to simulate the click of the element. We can make the test async and await for the element since the text will change after the element is clicked.

You should have a failing test now:

Test failing unable to find the content

Green stage

Let's add the logic to change the tab in the Svelte component. We can do that easily by creating a selectedIndex variable and changing its value based on the selected tab.

<script lang="ts">
    let selectedIndex = 0;

    const changeSecondTab = () => {
        selectedIndex = 1;
    }
</script>

<div class="vertical-tab-container">
    <ul class="vertical-tab">
        <li>First Tab</li>
        <li on:click={() => changeSecondTab()}>Second Tab</li>
        <li>Third Tab</li>
    </ul>

    <div class="vertical-tab-content">
        {#if selectedIndex == 0}
            <h2>First Tab Heading</h2>
            <p>...</p>
        {:else if selectedIndex == 1}
            <h2>Second Tab Heading</h2>
            <p>...</p>
        {/if}
    </div>
</div>

Note: This is not the best implementation. It is only meant for showing that you can do minimal work to make the test pass. We will clean it up in the next stage

We have a method changeSecondTab that will change the selectedIndex value to 1 which will make the #if condition to change the tab. Even though it is not the best solution to handle all cases, we have a starting point.

Let's look at the test now. It should be working:

Refactor

Let's fix the implementation to make it more generic and have it work for all three tabs. We can also add an indicator to show which tab is currently selected.

<script lang="ts">
    let selectedIndex = 0;

    const changeTab = (index: number) => {
        selectedIndex = index;
    }
</script>

<div class="vertical-tab-container">
    <ul class="vertical-tab">
        <li class:selected={selectedIndex == 0} 
            on:click={() => changeTab(0)}>First Tab</li>

        <li class:selected={selectedIndex == 1} 
            on:click={() => changeTab(1)}>Second Tab</li>

        <li class:selected={selectedIndex == 2} 
            on:click={() => changeTab(2)}>Third Tab</li>
    </ul>

    <div class="vertical-tab-content">
        {#if selectedIndex == 0}
            <h2>First Tab Heading</h2>
            <p>...</p>
        {:else if selectedIndex == 1}
            <h2>Second Tab Heading</h2>
            <p>...</p>
        {:else}
            <h2>Third Tab Heading</h2>
            <p>...</p>
        {/if}
    </div>
</div>

<style>
    ...
    .selected {
        color: blue;
    }
</style>

We have created a method changeTab that will be called on the click of each element and then change the selectedIndex. This will cause the #if logic to change the tab based on its value.

We also have class:selected followed by an expression and when the expression becomes true, the selected class is added to the element. So we have added one more CSS class and we made the text colour blue to show the selected tab.

Finished vertical tabs component

Test after finishing refactor

We have now confirmed that the test is also passing after the refactor. You can continue this process to add more tests and features to your component.

How to Add Animation

Svelte makes it easy to add animation when content is changed. You can make use of the transition directive to add pre-built animation to your application.

So let's add a fly animation when the content changes. You can import the fly animation from svelte/transition and then add it to the element using transition:fly. This will add the default fly animation when the content flies out and new content flies in. Such a neat effect with just a single line of code!

import { fly } from 'svelte/transition';

<div class="vertical-tab-content" >
        {#if selectedIndex == 0}
            <div transition:fly>
                <h2>First Tab Heading</h2>
                <p>...</p>
            </div>
        {:else if selectedIndex == 1}
            <div transition:fly>
                <h2>Second Tab Heading</h2>
                <p>...</p>
            </div>
        {:else}
            <div transition:fly>
                <h2>Third Tab Heading</h2>
                <p>...</p>
            </div>
        {/if}
    </div>

Animation brings life to your application and helps it stand out. I am a big fan of the simple animation transition system in Svelte.

Conclusion

In this tutorial, you have learned how to create a new component using test-driven development methodology. Please share your feedback on this post and let me know your thoughts.

Thanks for reading! You can contact me on Twitter @sriram_thiagar. I regularly post articles on my blog eternaldev.com if you want to read more articles from me.

Hello everyone. I am Sriram, and I work as a Full Stack developer. I like to share my learning with others. I have been blogging for more than a year now on my website.

Test-driven development (TDD) is a process where you write tests before you write the associated code. You first write a test that describes an expected behavior, and you run it, ensuring it fails. Then, you write the dumbest, most straightforward code you can to make the test pass. Finally, you refactor the code to make it right. And you repeat all the steps for each test until you’re done.

This approach has many advantages. First, it forces you to think before you code. It’s commonplace to rush into writing code before establishing what it should do. This practice leads to wasting time and writing complicated code. With TDD, any new piece of code requires a test first, so you have no choice but take the time to define what this code should do before you write it.

Secondly, it ensures you write unit tests. Starting with the code often leads to writing incomplete tests, or even no tests at all. Such a practice usually happens as a result of not having precise and exhaustive specs, which leads to spending more time coding than you should. Writing tests becomes a costly effort, which is easy to undermine once the production code is ready.

Unit tests are critical to building robust code. Overlooking or rushing them increases chances of your code breaking in production at some point.

Why do TDD for components?

Testing a component can be counter-intuitive. As we saw in Unit Test Your First Vue.js Component, it requires a mental shift to wrap your head around testing components versus testing plain scripts, knowing what to test, and understanding the line between unit tests and end-to-end.

TDD makes all this easier. Instead of writing tests by examining all bits and pieces of a finished project and trying to guess what you should cover, you’re doing the opposite. You’re starting from actual specs, a list of things that the component should do, without caring about how it does it. This way, you’re ensuring that all you test is the public API, but you’re also guaranteeing you don’t forget anything.

In this tutorial, we’ll build a color picker. For every swatch, users can access the matching color code, either in hexadecimal, RGB, or HSL.

_Design inspired from [Chris Castillo](https://dribbble.com/shots/2908891-Custom-Color-Picker-Exploration" rel="noopener" target="_blank" title="">Custom Color Picker Exploration by <a href="https://dribbble.com/_ChrisCastillo" rel="noopener" target="blank" title=")

Despite its apparent simplicity, there are a bunch of small pieces of logic to test. They require some thinking before jumping into code.

In this article, we’ll deep dive into TDD. We’ll put some specs together before we write a single line of code. Then, we’ll test every public feature in a test-driven fashion. Finally, we’ll reflect on what we did and see what we can learn from it.

Before we start

This tutorial assumes you’ve already built something with Vue.js before, and written unit tests for it using Vue Test Utils and Jest (or a similar test runner). It won’t go deeper into the fundamentals, so make sure you get up to speed first. If you’re not there yet, I recommend you go over Build Your First Vue.js Component and Unit Test Your First Vue.js Component.

TL;DR: this post goes in-depth in the how and why. It’s designed to help you understand every decision behind testing a real-world Vue.js component with TDD and teach you how to make design decisions for your future projects. If you want to understand the whole thought process, read on. Otherwise, you can go directly to the afterthoughts at the end, or look at the final code on GitHub.

Write down your specs

Before you even write your first test, you should write down an overview of what the component should do. Having specs makes testing much more straightforward since you’re mostly rewriting each spec in the form of tests.

Let’s think about the different parts that compose our component, and what they should do.

First, we have a collection of color swatches. We want to be able to pass a list of custom colors and display as swatches in the component. The first one should be selected by default, and the end user can select a new one by clicking it.

Secondly, we have the color mode toggler. The end user should be able to switch between three modes: hexadecimal (default), RGB and HSL.

Finally, we have the color code output, where the end user can get the code for the currently selected color swatch. This code is a combination of the selected swatch and color mode. Thus, by default, it should display the first swatch as a hexadecimal value. When changing any of these, the code should update accordingly.

As you can see, we don’t go too deep into details; we don’t specify what the color mode labels should be, or what the active state looks like for the color swatches. We can make most of the small decisions on the fly, even when doing TDD. Yet, we’ve come from a simple definition of what the component should be, to a comprehensive set of specs to start from.

Write test-driven code

First, you need to create a new Vue project with Vue CLI. You can check Build Your First Vue.js Component if you need a step by step guide.

During the scaffolding process, manually select features and make sure you check Unit testing. Pick Jest as your testing solution, and proceed until the project is created, dependencies are installed, and you’re ready to go.

We’ll need to use SVG files as components, so you also need to install the right loader for them. Install vue-svg-loader as a dev dependency, and add a rule for it in your vue.config.js file.

// vue.config.js

module.exports = {
  chainWebpack: config => {
    const svgRule = config.module.rule('svg')
    svgRule.uses.clear()
    svgRule.use('vue-svg-loader').loader('vue-svg-loader')
  }
}

This loader doesn’t play well with Jest by default, which causes tests to throw. To fix it, create a svgTransform.js file as documented on the website, and edit your jest.config.js as follows:

// svgTransform.js

const vueJest = require('vue-jest/lib/template-compiler')

module.exports = {
  process(content) {
    const { render } = vueJest({
      content,
      attrs: {
        functional: false
      }
    })

    return `module.exports = { render: ${render} }`
  }
}

// jest.config.js

module.exports = {
  // ...
  transform: {
    // ...
    '.+\\.(css|styl|less|sass|scss|png|jpg|ttf|woff|woff2)$': 'jest-transform-stub',
    '^.+\\.svg$': '<rootDir>/svgTransform.js'
  },
  // ...
}

Note that we’ve removed “svg” from the first regular expression (the one that gets transformed with jest-transform-stub). This way, we ensure SVGs get picked up by svgTransform.js.

Additionally, you need to install color-convert as a dependency. We’ll need it both in our code and in our tests later on.

Don’t serve the project yet. We’re going to write tests and rely on them passing or not to move on. We don’t want to control whether what we build works by testing it visually in the browser, nor being distracted by how it looks.

Instead, open your project and create a new ColorPicker.vue single-file component in the src/components/ directory. In tests/unit/, create its associated spec file.

<!-- ColorPicker.vue -->

<template>
  <div></div>
</template>

<script>
export default {}
</script>

<style>
</style>

// ColorPicker.spec.js

import { shallowMount } from '@vue/test-utils'
import ColorPicker from '@/components/ColorPicker'

describe('ColorPicker', () => {
  // let's do this!
})

In your terminal, execute the following command to run tests:

npm run test:unit --watchAll

For now, you should get an error because you don’t yet have tests. Don’t worry though; we’ll fix this shortly ? Note the usage of the --watchAll flag in the command: Jest is now watching your files. This way, you won’t have to re-run test by hand.

TDD goes in 3 stages:

1. Red: you write a test that describes an expected behavior, then you run it, ensuring it fails.
2. Green: you write the dumbest, most straightforward code you can to make the test pass.
3. Refactor: you refactor the code to make it right.

Step 1: Red

Time to write our first test! We’ll start with the color swatches. For clarity, we’ll wrap all tests for each distinct element in their own suite, using a describe block.

First, we want to make sure that the component displays each color that we provide as an individual swatch. We would pass those as props, in the form of an array of hexadecimal strings. In the component, we would display the list as an unordered list, and assign the background color via a style attribute.

import { shallowMount } from '@vue/test-utils'
import ColorPicker from '@/components/ColorPicker'
import convert from 'color-convert'

let wrapper = null

const propsData = {
  swatches: ['e3342f', '3490dc', 'f6993f', '38c172', 'fff']
}

beforeEach(() => (wrapper = shallowMount(ColorPicker, { propsData })))
afterEach(() => wrapper.destroy())

describe('ColorPicker', () => {
  describe('Swatches', () => {
    test('displays each color as an individual swatch', () => {
      const swatches = wrapper.findAll('.swatch')
      propsData.swatches.forEach((swatch, index) => {
        expect(swatches.at(index).attributes().style).toBe(
          `background: rgb(${convert.hex.rgb(swatch).join(', ')})`
        )
      })
    })
  })
})

We mounted our ColorPicker component and wrote a test that expects to find items with a background color matching the colors passed as props. This test is bound to fail: we currently have nothing in ColorPicker.vue. If you look at your terminal, you should have an error saying that no item exists at 0. This is great! We just passed the first step of TDD with flying colors.

Step 2: Green

Our test is failing; we’re on the right track. Now, time to make it pass. We’re not much interested in writing working or smart code at this point, all we want is to make Jest happy. Right now, Vue Test Utils complains about the fact that we don’t event have no item at index 0.

[vue-test-utils]: no item exists at 0

The simplest thing we can do to make that error go away is to add an unordered list with a swatch class on the list item.

<template>
  <div class="color-picker">
    <ul class="swatches">
      <li class="swatch"></li>
    </ul>
  </div>
</template>

Jest still complains but the error has changed:

Expected value to equal:
  "background: rgb(227, 52, 47);"
Received:
  undefined

This makes sense; the list item doesn’t have a style attribute. The simplest thing we can do about it is to hardcode the style attribute. This isn’t what we want in the end, but, we aren’t concerned about it yet. What we want is for our test to go green.

We can therefore hardcode five list items with the expected style attributes:

<ul class="swatches">
  <li class="swatch" style="background: rgb(227, 52, 47);"></li>
  <li class="swatch" style="background: rgb(52, 144, 220);"></li>
  <li class="swatch" style="background: rgb(246, 153, 63);"></li>
  <li class="swatch" style="background: rgb(56, 193, 114);"></li>
  <li class="swatch" style="background: rgb(255, 255, 255);"></li>
</ul>

The test should now pass.

Step 3: Refactor

At this stage, we want to rearrange our code to make it right, without breaking tests. In our case, we don’t want to keep the list items and their style attributes hardcoded. Instead, it would be better to receive swatches as a prop, iterate over them to generate the list items, and assign the colors as their background.

<template>
  <div class="color-picker">
    <ul class="swatches">
      <li
        :key="index"
        v-for="(swatch, index) in swatches"
        :style="{ background: `#${swatch}` }"
        class="swatch"
      ></li>
    </ul>
  </div>
</template>

<script>
export default {
  props: {
    swatches: {
      type: Array,
      default() {
        return []
      }
    }
  }
}
</script>

When tests re-run, they should still pass ? This means we’ve successfully refactored the code without affecting the output. Congratulations, you’ve just completed your first TDD cycle!

Now, before we go to the next test, let’s reflect a bit. You may be wondering:

“Isn’t this a bit dumb? I knew the test would fail. Am I not wasting time by running it anyway, then hardcoding the right value, see the test pass, then make the code right? Can’t I go to the refactor step directly?”

It’s understandable that you’re feeling confused by the process. Yet, try to look at things from a different angle: the point here isn’t to prove that the test doesn’t pass. We know it won’t. What we want to look at is what our test expects, make them happy in the simplest possible way, and finally write smarter code without breaking anything.

That’s the whole idea of test-driven development: we don’t write code to make things work, we write code to make tests pass. By reversing the relationship, we’re ensuring robust tests with a focus on the outcome.

What are we testing?

Another question that may come to mind is how we’re deciding what to test. In Unit Test Your First Vue.js Component, we saw that we should only be testing the public API of our component, not the internal implementation. Strictly speaking, this means we should cover user interactions and props changes.

But is that all? For example, is it okay for the output HTML to break? Or for CSS class names to change? Are we sure nobody is relying on them? That you aren’t yourself?

Tests should give you confidence that you aren’t shipping broken software. What people can do with your program shouldn’t stop working the way they expect it to work. It can mean different things depending on the project and use case.

For example, if you’re building this color panel as an open source component, your users are other developers who use it in their own projects. They’re likely relying on the class names you provide to style the component to their liking. The class names become a part of your public API because your users rely on them.

In our case, we may not necessarily be making an open source component, but we have view logic that depends on specific class names. For instance, it’s important for active swatches to have an active class name, because we’ll rely on it to display a checkmark, in CSS. If someone changes this by accident, we want to know about it.

Testing scenarios for UI components highly depend on the use case and expectations. Whichever the case, what you need to ask yourself is do I care about this if it changes?

Next tests

Testing the swatches

Let’s move on to the next test. We expect the first swatch of the list to be the one that’s selected by default. From the outside, this is something that we want to ensure keeps on working the same way. Users could, for instance, rely on the active class name to style the component.

test('sets the first swatch as the selected one by default', () => {
  const firstSwatch = wrapper.find('.swatch')
  expect(firstSwatch.classes()).toContain('active')
})

This test, too, should fail, as list items currently don’t have any classes. We can easily make this pass by adding the class on the first list item.

<li
  :key="index"
  v-for="(swatch, index) in swatches"
  :style="{ background: `#${swatch}` }"
  class="swatch"
  :class="{ 'active': index === 0 }"
></li>

The test now passes; however, we’ve hardcoded the logic into the template. We can refactor that by externalizing the index onto which the class applies. This way, we can change it later.

<template>
  <!-- ... -->
  <li
    :key="index"
    v-for="(swatch, index) in swatches"
    :style="{ background: `#${swatch}` }"
    class="swatch"
    :class="{ active: index === activeSwatch }"
  ></li>
  <!-- ... -->
</template>

export default {
  // ...
  data() {
    return {
      activeSwatch: 0
    }
  }
}

This naturally leads us to our third test. We want to change the active swatch whenever the end user clicks it.

test('makes the swatch active when clicked', () => {
  const targetSwatch = wrapper.findAll('.swatch').at(2)
  targetSwatch.trigger('click')
  expect(targetSwatch.classes()).toContain('active')
})

For now, nothing happens when we click a swatch. However, thanks to our previous refactor, we can make this test go green and even skip the refactor step.

<li
  :key="index"
  v-for="(swatch, index) in swatches"
  :style="{ background: `#${swatch}` }"
  class="swatch"
  :class="{ active: index === activeSwatch }"
  @click="activeSwatch = index"
></li>

This code makes the test pass and doesn’t even need a refactor. This is a fortunate side-effect of doing TDD: sometimes, the process leads to either writing new tests that either don’t need refactors, or even that pass right away.

Active swatches should show a checkmark. We’ll add it now without writing a test: instead, we’ll control their visibility via CSS later. This is alright since we’ve already tested how the active class applies.

First, create a checkmark.svg file in src/assets/.

<svg viewBox="0 0 448.8 448.8">
  <polygon points="142.8 323.9 35.7 216.8 0 252.5 142.8 395.3 448.8 89.3 413.1 53.6"/>
</svg>

Then, import it in the component.

import CheckIcon from '@/assets/check.svg'

export default {
  // ...
  components: { CheckIcon }
}

Finally, add it inside the list items.

<li ... >
  <check-icon />
</li>

Good! We can now move on to the next element of our component: the color mode.

Testing the color mode

Let’s now implement the color mode toggler. The end user should be able to switch between hexadecimal, RGB and HSL. We’re defining these modes internally, but we want to ensure they render correctly.

Instead of testing button labels, we’ll rely on class names. It makes our test more robust, as we can easily define a class name as part of our component’s contract. However, button labels should be able to change.

Now you may be tempted to check for these three specific modes, but that would make the test brittle. What if we change them? What if we add one, or remove one? That would still be the same logic, yet the test would fail, forcing us to go and edit it.

One solution could be to access the component’s data to iterate on the modes dynamically. Vue Test Utils lets us do that through the vm property, but again, this tightly couples our test with the internal implementation of the modes. If tomorrow, we decided to change the way we define modes, the test would break.

Another solution is to keep going with black box testing and only expect the class name to match a given pattern. We don’t care that it’s color-mode-hex, color-mode-hsl or color-mode-xyz, as long as it looks like what we expect from the outside. Jest lets us do that with regular expression matchers.

// ...
describe('Color model', () => {
  test('displays each mode as an individual button', () => {
    const buttons = wrapper.findAll('.color-mode')
    buttons.wrappers.forEach(button => {
      expect(button.classes()).toEqual(
        expect.arrayContaining([expect.stringMatching(/color-mode-\w{1,}/)])
      )
    })
  })
})

Here, we’re expecting elements with a class that follows the pattern “color-mode-“ + any word character (in ECMAScript, any character within [a-zA-Z_0-9]). We could add or remove any mode we want, and the test would still be valid.

Naturally, right now, the test should fail, as there are no buttons with class color-mode yet. We can make it pass by hardcoding them in the component.

<div class="color-modes">
  <button class="color-mode color-mode-hex"></button>
  <button class="color-mode color-mode-rgb"></button>
  <button class="color-mode color-mode-hsl"></button>
</div>

We can now refactor this code by adding the modes as private data in our component and iterate over them.

<template>
  <!-- ... -->
  <div class="color-modes">
    <button
      :key="index"
      v-for="(mode, index) in colorModes"
      class="color-mode"
      :class="`color-mode-${mode}`"
    >{{ mode }}</button>
  </div>
  <!-- ... -->
</template>

export default {
  // ...
  data() {
    return {
      activeSwatch: 0,
      colorModes: ['hex', 'rgb', 'hsl']
    }
  }
}

Good! Let’s move on.

As with the swatches, we want the first mode to be set as active. We can copy the test we wrote and adapt it to this new use case.

test('sets the first mode as the selected one by default', () => {
  const firstButton = wrapper.find('.color-mode')
  expect(firstButton.classes()).toContain('active')
})

We can make this test pass by manually adding the class on the first list item.

<button
  :key="index"
  v-for="(mode, index) in colorModes"
  class="color-mode"
  :class="[{ active: index === 0 }, `color-mode-${mode}`]"
>{{ mode }}</button>

Finally, we can refactor by externalizing the index onto which the class applies.

<template>
  <!-- ... -->
  <button
    :key="index"
    v-for="(mode, index) in colorModes"
    class="color-mode"
    :class="[{ active: index === activeMode }, `color-mode-${mode}`]"
  >{{ mode }}</button>
  <!-- ... -->
</template>

export default {
  // ...
  data() {
    return {
      activeSwatch: 0,
      activeMode: 0,
      colorModes: ['hex', 'rgb', 'hsl']
    }
  }
}

We need to change the active mode whenever the end user clicks the associated button, as with the swatches.

test('sets the color mode button as active when clicked', () => {
  const targetButton = wrapper.findAll('.color-mode').at(2)
  targetButton.trigger('click')
  expect(targetButton.classes()).toContain('active')
})

We can now add a @click directive as we did with the swatches, and make the test go green without having to refactor.

<button
  :key="index"
  v-for="(mode, index) in colorModes"
  class="color-mode"
  :class="[{ active: index === activeMode }, `color-mode-${mode}`]"
  @click="activeMode = index"
>{{ mode }}</button>

Testing the color code

Now that we’re done testing the swatches and color code, we can move on to the third and final element of our color picker: the color code. What we display in there is a combination of the other two: the selected swatch defines the color we should display, and the selected mode determines how to display it.

First, we want to make sure we initially display the default swatch in the default mode. We have the information to build this since we’ve implemented the swatches and the color mode.

Let’s start with a (failing) test.

describe('Color code', () => {
  test('displays the default swatch in the default mode', () => {
    expect(wrapper.find('.color-code').text()).toEqual('#e3342f')
  })
})

Now, let’s make this pass by hardcoding the expected result in the component.

<div class="color-code">#e3342f</div>

Good! Time to refactor. We have a raw color in hexadecimal mode, and we’re willing to output it in hexadecimal format. The only difference between our input and output values is that we want to prepend the latter with a hash character. The easiest way of doing so with Vue is via a computed property.

<template>
  <!-- ... -->
  <div class="color-code">{{ activeCode }}</div>
  <!-- ... -->
</template>

export default {
  // ...
  computed: {
    activeCode() {
      return `#${this.swatches[this.activeSwatch]}`
    }
  }
}

This should keep the test green. However, there’s an issue with this computed property: it only works for hexadecimal values. It should keep on working when we change the color, but not when we change the mode. We can verify this with another test.

test('displays the code in the right mode when changing mode', () => {
  wrapper.find('.color-mode-hsl').trigger('click')
  expect(wrapper.find('.color-code').text()).toEqual('2°, 76%, 54%')
})

Here, we’ve changed to HSL mode, but we’re still getting the hexadecimal output. We need to refactor our code so that our activeCode computed property is not only aware of the current color, but also the current color mode. One way we can achieve this is to create computed properties for each mode and proxy them through activeCode based on the selected mode.

First, we should simplify access to the current color and mode. Right now, we need to do an array lookup, which is repetitive and makes the code hard to read. We can use computed properties to wrap that logic.

export default {
  // ...
  computed: {
    // ...
    activeColorValue() {
      return this.swatches[this.activeSwatch]
    },
    activeModeValue() {
      return this.colorModes[this.activeMode]
    }
  }
}

As you can see, we’re not writing tests for these computed properties, as they aren’t part of our public API. We’ll use them later in our dedicated color mode computed properties, which themselves will be proxied in activeCode, which we’re testing in our “Color code” suite. All we care about is that the color code renders as expected so that the user can rely on them. How we get there are implementation details that we need to be able to change if need be.

We can now write our dedicated computed properties for each mode. We’ll map their name onto the ones in colorModes, so we can do an array lookup later in activeCode to return the right one.

For the hexadecimal output, we can externalize what we currently have in activeCode and refactor it using activeColorValue.

export default {
  // ...
  computed: {
    // ...
    hex() {
      return `#${this.activeColorValue}`
    }
  }
}

Now, let’s modify activeCode so it proxies the right computed property depending on the active mode.

export default {
  // ...
  computed: {
    // ...
    activeCode() {
      return this[this.activeModeValue]
    }
  }
}

This still shouldn’t make our latest test pass, since we haven’t written a computed property for it. However, our test that checks if the default mode renders correctly is still passing, which is a good sign we’re on the right track.

We now want to write a computed property that returns the color output in HSL mode. For this, we’ll use color-convert, an npm package that lets us convert colors in many different modes. We’ve already been using it in our tests, so we don’t have to reinstall it.

import convert from 'color-convert'

export default {
  // ...
  computed: {
    // ...
    hsl() {
      const hslColor = convert.hex.hsl(this.activeColorValue)
      return `${hslColor[0]}°, ${hslColor[1]}%, ${hslColor[2]}%`
    }
  }
}

Great, our test passes! We can now finish this up adding the missing RGB mode.

Yet, as you can see, we’re currently not testing the output of our color computed properties in isolation, but through other tests. To make things cleaner, we could decouple that logic from the component, import it as a dependency, and test it separately. This has several benefits:

• it keeps the component from growing every time we want to add a color mode,
• it keeps domains separated: the component focuses on its own view logic, and the color modes utility takes care of testing each mode exhaustively.

First, create a new color.js file in the src/utils/ directory, and a matching spec file in tests/unit/.

// color.spec.js

import { rgb, hex, hsl } from '@/utils/color'

// color.js

import convert from 'color-convert'

export const rgb = () => {}

export const hex = () => {}

export const hsl = () => {}

We can use TDD to test those three functions and make sure they always return the expected value. We can extract the logic we had in our Vue component for the last two, and write the RGB function from scratch.

For the sake of brevity, we’ll cover all three tests at once, but the process remains the same.

import { rgb, hex, hsl } from '@/utils/color'

const color = 'e3342f'

describe('color', () => {
  test('returns the color into RGB notation', () => {
    expect(rgb(color)).toBe('227, 52, 47')
  })
  test('returns the color into hexadecimal notation', () => {
    expect(hex(color)).toBe('#e3342f')
  })
  test('returns the color into HSL notation', () => {
    expect(hsl(color)).toBe('2°, 76%, 54%')
  })
})

We now have three failing tests. The first thing we can do is to return hardcoded values to go green.

export const rgb = () => '227, 52, 47'

export const hex = () => '#e3342f'

export const hsl = () => '2°, 76%, 54%'

Now, we can start refactoring by migrating the code from our Vue component.

export const hex = () => `#${color}`

export const hsl = color => {
  const hslColor = convert.hex.hsl(color)
  return `${hslColor[0]}°, ${hslColor[1]}%, ${hslColor[2]}%`
}

Finally, we can implement our rgb function.

export const rgb = color => convert.hex.rgb(color).join(', ')

All tests should stay green!

We can now use the color utilities in our Vue component and refactor it a bit. We no longer need to import color-convert in the component, nor do we need dedicated computed properties for each mode, or even for getting the active color and mode values. All we need to keep is activeCode, where we can store all the necessary logic.

This is a good example where doing black box testing helps us: we’ve been focusing on testing the public API; thus we can refactor the internals of our component without breaking the tests. Removing properties like activeColorValue or hex doesn’t matter, because we were never testing them directly.

// ...
import { rgb, hex, hsl } from '@/utils/color'

const modes = { rgb, hex, hsl }

export default {
  // ...
  computed: {
    activeCode() {
      const activeColor = this.swatches[this.activeSwatch]
      const activeMode = this.colorModes[this.activeMode]
      return modes[activeMode](activeColor)
    }
  }
}

We now have much terser code in our component, and better domain separation, while still respecting the component’s contract.

Finally, we can implement a missing test: the one that ensures the color code changes whenever we click a new swatch. This should already go green, but it’s still essential for us to write it, so we can know about it if it breaks.

test('displays the code in the right color when changing color', () => {
  wrapper
    .findAll('.swatch')
    .at(2)
    .trigger('click')
  expect(wrapper.find('.color-code').text()).toEqual('#f6993f')
})

And we’re done! We just built a fully functional Vue component using TDD, without relying on browser output, and our tests are ready.

Visual control

Now that our component is ready, we can see how it looks and play with it in the browser. This allows us to add the CSS and ensure we didn’t miss out on anything.

First, mount the component into the main App.vue file.

<!-- App.vue -->

<template>
  <div id="app">
    <color-picker :swatches="['e3342f', '3490dc', 'f6993f', '38c172', 'fff']"/>
  </div>
</template>

<script>
import ColorPicker from '@/components/ColorPicker'

export default {
  name: 'app',
  components: {
    ColorPicker
  }
}
</script>

Then, run the app by executing the following script, and open it in your browser at [http://localhost:8080/](http://localhost:8080/).

npm run serve

You should see your color picker! It doesn’t look like much for now, but it works. Try clicking colors and change the color mode; you should see the color code change.

To see the component with proper styling, add the following CSS between the style tags:

.color-picker {
  background-color: #fff;
  border: 1px solid #dae4e9;
  border-radius: 0.125rem;
  box-shadow: 0 2px 4px 0 rgba(0, 0, 0, 0.1);
  color: #596a73;
  font-family: BlinkMacSystemFont, Helvetica Neue, sans-serif;
  padding: 1rem;
}

.swatches {
  color: #fff;
  display: flex;
  flex-wrap: wrap;
  list-style: none;
  margin: -0.25rem -0.25rem 0.75rem;
  padding: 0;
}

.swatch {
  border-radius: 0.125rem;
  cursor: pointer;
  height: 2rem;
  margin: 0.25rem;
  position: relative;
  width: 2rem;
}

.swatch::after {
  border-radius: 0.125rem;
  bottom: 0;
  box-shadow: inset 0 0 0 1px #dae4e9;
  content: '';
  display: block;
  left: 0;
  mix-blend-mode: multiply;
  position: absolute;
  right: 0;
  top: 0;
}

.swatch svg {
  display: none;
  color: #fff;
  fill: currentColor;
  margin: 0.5rem;
}

.swatch.active svg {
  display: block;
}

.color-modes {
  display: flex;
  font-size: 1rem;
  letter-spacing: 0.05rem;
  margin: 0 -0.25rem 0.75rem;
}

.color-mode {
  background: none;
  border: none;
  color: #9babb4;
  cursor: pointer;
  display: block;
  font-weight: 700;
  margin: 0 0.25rem;
  padding: 0;
  text-transform: uppercase;
}

.color-mode.active {
  color: #364349;
}

.color-code {
  border: 1px solid #dae4e9;
  border-radius: 0.125rem;
  color: #364349;
  text-transform: uppercase;
  padding: 0.75rem;
}

You should see something like this:

And we’re done!

Afterthoughts

How can we improve this?

For now, we have a robust test suite. Even though we don’t have 100% coverage, we can feel confident with our component going out in the wild, and evolving over time. There are still a couple of things we could improve though, depending on the use case.

First, you may notice that when clicking the white swatch, the checkmark doesn’t show up. That’s not a bug, rather a visual issue: the checkmark is there, but we can’t see it because it’s white on white. You could add a bit of logic to fix this: when a color is lighter than a certain threshold (let’s say 90%), you could add a light class on the swatch. This would then let you apply some specific CSS and make the checkmark dark.

Fortunately, you already have all you need: the color-converter package can help you determine whether a color is light (with the HSL utilities), and you already have a color utility module to store that logic and test it in isolation. To see what the finished code could look like, check out the project’s repository on GitHub.

We could also reinforce the suite by adding a few tests to make sure some expected classes are there. This doesn’t test actual logic, but would still be particularly useful if someone was relying on those class names to style the component from the outside. Again, everything depends on your use case: test what shouldn’t change without you knowing, don’t only add tests for the sake of it.

What did we learn?

There are several lessons to learn from this TDD experiment. It brings a lot to the table but also highlights a few challenges that we should be aware of.

First, TDD is a fantastic way to write robust tests, not too many and not too few. Have you ever finished a component, moved on to tests and thought “where do I even start?”? Looking at finished code and figuring out what to test is hard. It’s tempting to get it done quickly, overlook some critical parts and end up with an incomplete test suite. Or you can adopt a defensive approach and test everything, risking to focus on implementation details and writing brittle tests.

Adopting TDD for developing UI components helps us focus on exactly what to test by defining, before writing any line of code, if this is part of the contract or not.

Secondly, TDD encourages refactors, leading to better software design. When you’re writing tests after coding, you’re usually no longer in a refactoring dynamic. You can fix your code if you find issues while testing, but at this stage, you’re most likely done with the implementation. This separation between writing code and writing test is where lies the issue.

With TDD, you’re creating a deeper connection between code and tests, with a strong focus on making the public API reliable. Implementation comes right after you’ve guaranteed the outcome. This is why the green step is critical: you first need your test to pass, then ensure it never breaks. Instead of implementing your way to a working solution, you’re reversing the relationship, focusing on the contract first, and allowing the implementation to remain disposable. Because refactoring comes last, and you’ve established the contract, you now have mental space to make things right, clean some code, adopt a better design, or focus on performance.

It’s worth noting that TDD is much easier to follow with specs. When you already have a clear overview of everything the component should do, you can translate those specifications into tests. Some teams use frameworks like ATDD (acceptance test–driven development), where the involved parties develop specifications from a business perspective. The final specs, or acceptance tests, are a perfect base to write tests following TDD.

On the other hand, going with TDD to test UI components can be difficult at first, and require some prior knowledge before diving into it. For starters, you need to have good knowledge of your testing libraries so that you can write reliable assertions. Look at the test we wrote with a regular expression: the syntax is not the most straightforward. If you don’t know the library well, it’s easy to write a test that fails for the wrong reasons, which would end up hindering the whole TDD process.

Similarly, you need to be aware of some details regarding the values you expect; otherwise, you could end up battling with your tests and doing some annoying back-and-forths. On that matter, UI components are more challenging than renderless libraries, because of the various ways the DOM specifications can be implemented.

Take the first test of our suite for example: we’re testing background colors. However, even though we’re passing hexadecimal colors, we’re expecting RGB return values. That’s because Jest uses jsdom, a Node.js implementation of the DOM and HTML standards. If we were running our tests in a specific browser, we might have a different return value. This can be tricky when you’re testing different engines. You may have to seek some more advanced conversion utilities or use environment variables to handle the various implementations.

Is it worth it?

If you made it this far, you’ve probably realized that TDD demands time. This article itself is over 6,000 words! This can be a bit scary if you’re used to faster development cycles, and probably looks impossible if you’re often working under pressure. However, it’s important to bust the myth that TDD would somehow double development time for little return on investment, because this is entirely false.

TDD requires some practice, and you’ll get faster over time. What feels clumsy today can become a second nature tomorrow, if you do it regularly. I encourage you not to discard something because it’s new and feels awkward: give it some time to assess it fairly, then take a decision.

Secondly, time spent on writing test-driven code is time you won’t spend fixing bugs.

Fixing bugs is far more costly than preventing them. If you’ve ever had to fix critical production bugs, you know this feels close to holding an open wound on a surgical patient with one hand, while trying to operate with the other one. In the desert. At night. With a Swiss Army knife. It’s messy, stressful, suboptimal, and bears high chances of screwing up something else in the process. If you want to preserve your sanity and the trust your end users have in your software, you want to avoid those situations at all costs.

Tests help you catch bugs before they make it to production, and TDD helps you write better tests. If you think you should test your software, then you should care about making these tests useful in the first place. Otherwise, the whole thing is only a waste of time.

As with anything, I encourage you to try TDD before discarding the idea. If you’re consistently encountering production issues, or you think you could improve your development process, then it’s worth giving it a shot. Try it for a limited amount of time, measure the impact, and compare the results. You may discover a method that helps you ship better software, and feel more confident about hitting the “Deploy” button.

What is Testing?

Testing is the process of ensuring a program receives the correct input and generates the correct output and intended side-effects. We define these correct inputs, outputs, and side-effects with specifications. You may have seen testing files with the naming convention filename.spec.js. The spec stands for specification. It is the file where we specify or assert what our code should do and then test it to verify it does it.

You have two choices when it comes to testing: manual testing and automated testing.

Manual Testing

Manual testing is the process of checking your application or code from the user’s perspective. Opening up the browser or program and navigating around in an attempt to test functionality and find bugs.

Automated Testing

Automated testing, on the other hand, is writing code that checks to see if other code works. Contrary to manual testing, the specifications remain constant from test to test. The biggest advantage is being able to test many things much faster.

It’s the combination of these two testing techniques that will flush out as many bugs and unintended side-effects as possible, and ensure your program does what you say it will. The focus of this article is on automated testing, and in particular, unit testing.

There are two main types of automated tests: Unit and End-to-End (E2E). E2E tests test an application as a whole. Unit tests test the smallest pieces of code, or units. What is a unit? Well, we define what a unit is, but in general, it’s a relatively small piece of application functionality.

Recap:

1. Testing is verifying our application does what it should.

2. There are two types of tests: manual and automated

3. Tests assert that your program will behave a certain way. Then the test itself proves or disproves that assertion.

Test-Driven Development

Test-driven development is the act of first deciding what you want your program to do (the specifications), formulating a failing test, then writing the code to make that test pass. It is most often associated with automated testing. Although you could apply the principals to manual testing as well.

Let’s look at a simple example: Building a wooden table. Traditionally, we would make a table, then once the table is made, test it to make sure it does, well, what a table should do. TDD, on the other hand, would have us first define what the table should do. Then when it isn’t doing those things, add the minimum amount of “table” to make each unit work.

Here an example of TDD for building a wooden table:

I expect the table to be four feet in diameter.

The test fails because I have no table.

I cut a circular piece of wood four feet in diameter.

The test passes.

__________

I expect the table to be three feet high.

The test fails because it is sitting on the ground.

I add one leg in the middle of the table.

The test passes.

__________

I expect the table to hold a 20-pound object.

The test fails because when I place the object on the edge, it makes the table fall over since there is only one leg in the middle.

I move the one leg to the outer edge of the table and add two more legs to create a tripod structure.

The test passes.

This would continue on and on until the table is complete.

Recap

1. With TDD, test logic precedes application logic.

A Practical Example

Imagine we have a program that manages users and their blog posts. We need a way to keep track of the posts a user writes in our database with more precision. Right now, the user is an object with a name and email property:

user = { 
   name: 'John Smith', 
   email: 'js@somePretendEmail.com' 
}

We will track the posts a user creates in the same user object.

user = { 
   name: 'John Smith', 
   email: 'js@someFakeEmailServer.com'
   posts: [Array Of Posts] // <-----
}

Each post has a title and content. Instead of storing the entire post with each user, we’d like to store something unique that could be used to reference the post. We first thought we would store the title. But, if the user ever changes the title, or if–although somewhat unlikely–two titles are exactly the same, we’d have some issues referencing that blog post. Instead, we will create a unique ID for each blog post that we will store in the userObject.

user = { 
   name: 'John Smith', 
   email: 'js@someFakeEmailServer.com'
   posts: [Array Of Post IDs]
}

Set up our testing environment

For this example, we will be using Jest. Jest is a testing suite. Often, you’ll need a testing library and a separate assertion library, but Jest is an all-in-one solution.

An assertion library allows us to make assertions about our code. So in our wooden table example, our assertion is: “I expect the table to hold a 20-pound object.” In other words, I am asserting something about what the table should do.

Project setup

1. Create an NPM project: npm init.

2. Create id.js and add it to the project’s root.

3. Install Jest: npm install jest --D

4. Update the package.json test script

// package.json

{
   ...other package.json stuff
   "scripts": {   
     "test": "jest" // this will run jest with "npm run test"
   }
}

That’s it for the project setup! We aren’t going to have any HTML or any styling. We are approaching this purely from a unit-testing standpoint. And, believe it or not, we have enough to run Jest right now.

In the command line, run our test script: npm run test.

You should have received an error:

No tests found
In /****/
  3 files checked.
  testMatch: **/__tests__/**/*.js?(x),**/?(*.)+(spec|test).js?(x) - 0 matches
  testPathIgnorePatterns: /node_modules/ - 3 matches

Jest is looking for a file name with some specific characteristics such as a .spec or .test contained within the file name.

Let’s update id.js to be id.spec.js.

Run the test again

You should receive another error:

FAIL  ./id.spec.js
  ● Test suite failed to run
  
Your test suite must contain at least one test.

A little bit better, it found the file, but not a test. That makes sense; it’s an empty file.

How Do We Write a Test?

Tests are just functions that receive a couple of arguments. We can call our test with either it() or test().

it()is an alias of test().

Let’s write a very basic test just to make sure Jest is working.

// id.spec.js

test('Jest is working', () => {
   expect(1).toBe(1);
});

Run the test again.

PASS  ./id.spec.js
  ✓ Jest is working (3ms)
  
Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        1.254s
Ran all test suites.

We passed our first test! Let’s analyze the test and results output.

We pass a title or description as the first argument.

test('Jest is Working')

The second argument we pass is a function where we actually assert something about our code. Although, in this case, we aren’t asserting something about our code, but rather something truthy in general that will pass, a sort of sanity check.

...() => { expect(1).toBe(1) });

This assertion is mathematically true, so it’s a simple test to ensure we’ve wired up Jest correctly.

The results tell us whether the test passes or fails. It also tells us the number of tests and test suites.

A side note about organizing our tests

There is another way we could organize our code. We could wrap each test in a describe function.

describe('First group of tests', () => {
   test('Jest is working', () => {
      expect(1).toBe(1);
   });
});

describe('Another group of tests', () => {
   // ...more tests here
});

describe() allows us to divide up our tests into sections:

PASS  ./id.spec.js
  First group of tests
    ✓ Jest is working(4ms)
    ✓ Some other test (1ms)
  Another group of tests
    ✓ And another test
    ✓ One more test (12ms)
    ✓ And yes, one more test

We won’t use describe, but it is more common than not to see a describe function that wraps tests. Or even a couple of describes–maybe one for each file we are testing. For our purposes, we will just focus on test and keep the files fairly simple.

Testing Based on Specifications

As tempting as it is to just sit down and start typing application logic, a well-formulated plan will make development easier. We need to define what our program will do. We define these goals with specifications.

Our high-level specification for this project is to create a unique ID, although we should break that down into smaller units that we will test. For our small project we will use the following specifications:

1. Create a random number

2. The number is an integer.

3. The number created is within a specified range.

4. The number is unique.

Recap

1. Jest is a testing suite and has a built-in assertion library.

2. A test is just a function whose arguments define the test.

3. Specifications define what our code should do and are ultimately what we test.

Specification 1: Create a Random Number

JavaScript has a built-in function to create random numbers–Math.random(). Our first unit test will look to see that a random number was created and returned. What we want to do is use math.random() to create a number and then ensure that is the number that gets returned.

So you might think we would do something like the following:

expect(our-functions-output).toBe(some-expected-value). The problem with our return value being random, is we have no way to know what to expect. We need to re-assign the Math.random() function to some constant value. This way, when our function runs, Jest replaces Math.random()with something constant. This process is called mocking. So, what we are really testing for is that Math.random()gets called and returns some expected value that we can plan for.

Now, Jest also provides a way to prove a function is called. However, in our example, that assertion alone only assures us Math.random()was called somewhere in our code. It won’t tell us that the result of Math.random()was also the return value.

Why would you want to mock a function? Isn’t the point to test the real code? Yes and no. Many functions contain things we cannot control, for example an HTTP request. We aren’t trying to test this code. We assume those dependencies will do what they are supposed or make pretend functions that simulate their behavior. And, in the event those are dependencies we’ve written, we will likely write separate tests for them.

Add the following test to id.spec.js

test('returns a random number', () => {
   const mockMath = Object.create(global.Math);
   mockMath.random = jest.fn(() => 0.75);
   global.Math = mockMath;
   const id = getNewId();
   expect(id).toBe(0.75);
});

Breaking the above test down

First, we copy the global Math object. Then we change the random method to return a constant value, something we can expect. Finally, we replace the global Math object with our mocked Math object.

We should get an ID back from a function (that we haven't created yet–remember this TDD). Then, we expect that ID to equal 0.75–our mocked return value.

Notice I’ve chosen to use a built-in method that Jest provides for mocking functions: jest.fn(). We could have also passed in a anonymous function instead. However, I wanted to show you this method, since there will be times that a Jest-mocked function will be required for other functionality in our tests to work .

Run the test: npm run test

FAIL  ./id.spec.js
✕ returns a random number (4ms)
● returns a random number
   ReferenceError: getNewId is not defined

Notice we get a reference error just like we should. Our test can’t find our getNewId().

Add the following code above the test.

function getNewId() {
   Math.random()
}

I am keeping the code and testing in the same file for simplicity. Normally, the test would be written in a separate file, with any dependencies imported as they are needed.

FAIL  ./id.spec.js
   ✕ returns a random number (4ms)
   ● returns a random number
   
   expect(received).toBe(expected) // Object.is equality
   Expected: 0.75
   Received: undefined

We failed again with what is called an assertion error. Our first error was a reference error. This second error tells us it received undefined. But we called Math.random()so what happened? Remember, functions that don’t explicitly return something will implicitly return undefined. This error is a good hint that something wasn’t defined such as a variable, or, like in our case, our function isn’t returning anything.

Update the code to the following:

function getNewId() {
   return Math.random()
}

Run the test

PASS  ./id.spec.js
✓ returns a random number (1ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total

Congratulations! We passed our first test.

Ideally, we want to get to our assertion errors as quickly as possible. Assertion errors–specifically value assertion errors like this one, although we will touch on boolean assertions errors in a bit–give us hints to what is wrong.

Specification 2: The number we return is an integer.

Math.random() generates a number between 0 and 1 (not inclusive). The code we have will never generate such an integer. That’s ok though, this is TDD. We will check for an integer and then write the logic to transform our number to an integer.

So, how do we check if a number is an integer? We have a few options. Recall, we mocked Math.random() above, and we are returning a constant value. In fact, we are creating a real value as well since we are returning a number between 0 and 1 (not inclusive). If we were returning a string, for example, we couldn’t get this test to pass. Or if on the other hand, we were returning an integer for our mocked value, the test would always (falsely) pass.

So a key takeaway is if you going to use mocked return values, they should be realistic so our tests return meaningful information with those values.

Another option would be to use the Number.isInteger(), passing our ID as the argument and seeing if that returns true.

Finally, without using the mocked values, we could compare the ID we get back with its integer version.

Let’s look at option 2 and 3.

Option 2: Using Number.isInteger()

test('returns an integer', () => {
   const id = getRandomId();
   expect(Number.isInteger(id)).toBe(true);
});

The test fails as it should.

FAIL  ./id.spec.js
✓ returns a random number (1ms)
✕ returns an integer (3ms)

● returns an integer
expect(received).toBe(expected) // Object.is equality

Expected: true
Received: false

The test fails with a boolean assertion error. Recall, there are multiple ways a test might fail. We want them to fail with assertion errors. In other words, our assertion isn’t what we say it is. But even more so, we want our test to fail with value assertion errors.

Boolean assertion errors (true/false errors) don’t give us very much information, but a value assertion error does.

Let’s return to our wooden table example. Now bear with me, the following two statements might seem awkward and difficult to read, but they’re here to highlight a point:

First, you might assert that the table is blue [to be] true. In another assertion, you might assert the table color [to be] blue. I know, these are awkward to say and might even look like identical assertions but they're not. Take a look at this:

expect(table.isBlue).toBe(true)

vs

expect(table.color).toBe(blue)

Assuming the table isn’t blue, the first examples error will tell us it expected true but received false. You have no idea what color the table is. We very well may have forgotten to paint it altogether. The second examples error, however, might tell us it expected blue but received red. The second example is much more informative. It points to the root of the problem much quicker.

Let’s rewrite the test, using option 2, to receive a value assertion error instead.

test('returns an integer', () => {
   const id = getRandomId();
   expect(id).toBe(Math.floor(id));
});

We are saying we expect the ID we get from our function to be equal to the floor of that ID. In other words, if we are getting an integer back, then the floor of that integer is equal to the integer itself.

FAIL  ./id.spec.js
✓ returns a random number (1ms)
✕ returns an integer (4ms)
● returns an integer
expect(received).toBe(expected) // Object.is equality

Expected: 0
Received: 0.75

Wow, what are the chances this function just happened to return the mocked value! Well, they are 100% actually. Even though our mocked value seems to be scoped to only the first test, we are actually reassigning the global value. So no matter how nested that re-assignment takes place, we are changing the global Math object.

If we want to change something before each test, there is a better place to put it. Jest offers us a beforeEach() method. We pass in a function that runs any code we want to run before each of our tests. For example:

beforeEach(() => {
   someVariable = someNewValue;
});

test(...)

For our purposes, we won’t use this. But let's change our code a bit so that we reset the global Math object back to the default. Go back into the first test and update the code as follows:

test('returns a random number', () => {
   const originalMath = Object.create(global.Math);
   const mockMath = Object.create(global.Math);
   mockMath.random = () => 0.75;
   global.Math = mockMath;
   const id = getNewId();
   expect(id).toBe(0.75);
   global.Math = originalMath;
});

What we do here is save the default Math object before we overwrite any of it, then reassign it after our test is complete.

Let’s run our tests again, specifically focusing back on our second test.

✓ returns a random number (1ms)
✕ returns an integer (3ms)
● returns an integer
expect(received).toBe(expected) // Object.is equality

Expected: 0
Received: 0.9080890805713182

Since we’ve updated our first test to go back to the default Math object, we are truly getting a random number now. And just like the test before, we are expecting to receive an integer, or in other words, the floor of the number generated.

Update our application logic.

function getRandomId() {
   return Math.floor(Math.random()); // convert to integer
}

FAIL  ./id.spec.js
✕ returns a random number (5ms)
✓ returns an integer
● returns a random number
expect(received).toBe(expected) // Object.is equality
Expected: 0.75
Received: 0

Uh oh, our first test failed. So what happened?

Well, because we are mocking our return value. Our first test returns 0.75, no matter what. We expect, however, to get 0 (the floor of 0.75). Maybe it would be better to check if Math.random() gets called. Although, that is somewhat meaningless, because we could call Math.random()anywhere in our code, never use it, and the test still passes. Maybe, we should test whether our function returns a number. After all, our ID must be a number. Yet again, we are already testing if we are receiving an integer. And all integers are numbers; that test would be redundant. But there is one more test we could try.

When it is all said and done, we expect to get an integer back. We know we will use Math.floor() to do so. So maybe we can check if Math.floor() gets called with Math.random() as an argument.

test('returns a random number', () => {
   jest.spyOn(Math, 'floor'); // <--------------------changed
   const mockMath = Object.create(global.Math); 
   const globalMath = Object.create(global.Math);
   mockMath.random = () => 0.75;
   global.Math = mockMath;
   const id = getNewId();
   getNewId(); //<------------------------------------changed
   expect(Math.floor).toHaveBeenCalledWith(0.75); //<-changed
   global.Math = globalMath;
});

I’ve commented the lines we changed. First, move your attention towards the end of the snippet. We are asserting that a function was called. Now, go back to the first change: jest.spyOn(). In order to watch if a function has been called, jest requires us to either mock that function, or spy on it. We’ve already seen how to mock a function, so here we spy on Math.floor(). Finally, the other change we’ve made was to simply call getNewId() without assigning its return value to a variable. We are not using the ID, we are simply asserting it calls some function with some argument.

Run our tests

PASS  ./id.spec.js
✓ returns a random number (1ms)
✓ returns an integer

Test Suites: 1 passed, 1 total
Tests:       2 passed, 2 total

Congratulations on a second successful test.

Specification 3: The number is within a specified range.

We know Math.random() returns a random number between 0 and 1 (not inclusive). If the developer wants to return a number between 3 and 10, what could she do?

Here is the answer:

Math.floor(Math.random() * (max — min + 1))) + min;

The above code will produce a random number in a range. Let’s look at two examples to show how it works. I’ll simulate two random numbers being created and then apply the remainder of the formula.

Example: A number between 3 and 10. Our random numbers will be .001 and .999. I’ve chosen the extreme values as the random numbers so you could see the final result stays within the range.

0.001 * (10-3+1) + 3 = 3.008 the floor of that is 3

0.999 * (10-3+1) + 3 = 10.992 the floor of that is 10

Let’s write a test

test('generates a number within a specified range', () => {
   const id = getRandomId(10, 100);
   expect(id).toBeLessThanOrEqual(100);
   expect(id).toBeGreaterThanOrEqual(10);
});

FAIL  ./id.spec.js
✓ returns a random number (1ms)
✓ returns an integer (1ms)
✕ generates a number within a specified range (19ms)

● generates a number within a specified range
expect(received).toBeGreaterThanOrEqual(expected)

Expected: 10
Received: 0

The floor of Math.random() will always be 0 until we update our code. Update the code.

function getRandomId(min, max) {
   return Math.floor(Math.random() * (max - min + 1) + min);
}

FAIL  ./id.spec.js
✕ returns a random number (5ms)
✓ returns an integer (1ms)
✓ generates a number within a specified range (1ms)

● returns a random number

expect(jest.fn()).toHaveBeenCalledWith(expected)

Expected mock function to have been called with:

0.75 as argument 1, but it was called with NaN.

Oh no, our first test failed again! What happened?

Simple, our test is asserting that we are calling Math.floor() with 0.75. However, we actually call it with 0.75 plus and minus a max and min value that isn’t yet defined. Here we will re-write the first test to include some of our new knowledge.

test('returns a random number', () => {
   jest.spyOn(Math, 'floor');
   const mockMath = Object.create(global.Math);
   const originalMath = Object.create(global.Math);
   mockMath.random = () => 0.75;
   global.Math = mockMath;
   const id = getNewId(10, 100);
   expect(id).toBe(78);
   global.Math = originalMath;
});

PASS  ./id.spec.js
✓ returns a random number (1ms)
✓ returns an integer
✓ generates a number within a specified range (1ms)

Test Suites: 1 passed, 1 total
Tests:       3 passed, 3 total

We’ve made some pretty big changes. We’ve passed some sample numbers into our function (10, and 100 as minimum and maximum values), and we’ve changed our assertion once again to check for a certain return value. We can do this because we know if Math.random() gets called, the value is set to 0.75. And, when we apply our min and max calculations to 0.75 we will get the same number each time, which in our case is 78.

Now we have to start wondering if this is even a good test. We’ve had to go back in and mold our test to fit our code. That goes against the spirit of TDD a bit. TDD says to change your code to make the test pass, not to change the test to make the test pass. If you find yourself trying to fix tests so they pass, that may be a sign of a bad test. Yet, I’d like to leave the test in here, as there are a couple of good concepts. However, I urge you to consider the efficacy of a test such as this, as well as a better way to write it, or if it’s even critical to include at all.

Let’s return to our third test which was generating a number within a range.

We see it has passed, but we have a problem. Can you think of it?

The question I am wondering is whether we just get lucky? We only generated a single random number. What are the chances that number just happened to be in the range and pass the test?

Fortunately here, we can mathematically prove our code works. However, for fun (if you can call it fun), we will wrap our code in a for loop that runs 100 times.

test('generates a number within a defined range', () => {
   for (let i = 0; i < 100; i ++) {
      const id = getRandomId(10, 100);    
   
      expect(id).toBeLessThanOrEqual(100);
      expect(id).toBeGreaterThanOrEqual(10);
      expect(id).not.toBeLessThan(10);
      expect(id).not.toBeGreaterThan(100);
   }
});

I added a few new assertions. I use the .not only to demonstrate other Jest API’s available.

PASS  ./id.spec.js
  ✓ is working (2ms)
  ✓ Math.random() is called within the function (3ms)
  ✓ receives an integer from our function (1ms)
  ✓ generates a number within a defined range (24ms)
  
Test Suites: 1 passed, 1 total
Tests:       4 passed, 4 total
Snapshots:   0 total
Time:        1.806s

With 100 iterations, we can feel fairly confident our code keeps our ID within the specified range. You could also purposely try to fail the test for added confirmation. For example, you could change one of the assertions to not expect a value greater than 50 but still pass in 100 as the maximum argument.

Is it ok to use multiple assertions in one test?

Yes. That isn’t to say you shouldn’t attempt to reduce those multiple assertions to a single assertion that is more robust. For example, we could rewrite our test to be more robust and reduce our assertions to just one.

test('generates a number within a defined range', () => {
   const min = 10;
   const max = 100;
   const range = [];
   for (let i = min; i < max+1; i ++) {
     range.push(i);
   }
   for (let i = 0; i < 100; i ++) {
      const id = getRandomId(min, max);
      expect(range).toContain(id);
   }
});

Here, we created an array that contains all the numbers in our range. We then check to see if the ID is in the array.

Specification 4: The number is unique

How can we check if a number is unique? First, we need to define what unique to us means. Most likely, somewhere in our application, we would have access to all ID’s being used already. Our test should assert that the number that is generated is not in the list of current IDs. There are a few different ways to solve this. We could use the .not.toContain() we saw earlier, or we could use something with index.

indexOf()

test('generates a unique number', () => {
   const id = getRandomId();
   const index = currentIds.indexOf(id);
   expect(index).toBe(-1);
});

array.indexOf() returns the position in the array of the element you pass in. It returns -1 if the array doesn’t contain the element.

FAIL  ./id.spec.js
✓ returns a random number (1ms)
✓ returns an integer
✓ generates a number within a defined range (25ms)
✕ generates a unique number (10ms)

● generates a unique number

ReferenceError: currentIds is not defined

The test fails with a reference error. currentIds is not defined. Let's add an array to simulate some ID’s that might already exist.

const currentIds = [1, 3, 2, 4];

Re-run the test.

PASS  ./id.spec.js
✓ returns a random number (1ms)
✓ returns an integer
✓ generates a number within a defined range (27ms)
✓ generates a unique number

Test Suites: 1 passed, 1 total

Tests:       4 passed, 4 total

While the test passes, this should once again raise a red flag. We have absolutely nothing that ensures the number is unique. So, what happened?

Again, we are getting lucky. In fact, your test may have failed. Although if you ran it over and over, you’d likely get a mix of both with far more passes than failures due to the size of currentIds.

One thing we could try is to wrap this in a for loop. A large enough for loop would likely cause us to fail, although it would be possible they all pass. What we could do is check to see that our getNewId() function could somehow be self-aware when a number is or is not unique.

For example. we could set currentIds = [1, 2, 3, 4, 5]. Then call getRandomId(1, 5) . Our function should realize there is no value it can generate due to the constraints and pass back some sort of error message. We could test for that error message.

test('generates a unique number', () => {
   mockIds = [1, 2, 3, 4, 5];
   let id = getRandomId(1, 5, mockIds);
   expect(id).toBe('failed');
    
   id = getRandomId(1, 6, mockIds);
   expect(id).toBe(6);
});

There are a few things to notice. There are two assertions. In the first assertion, we expect our function to fail since we constrain it in a way that it shouldn’t return any number. In the second example, we constrain it in a way where it should only be able to return 6.

FAIL  ./id.spec.js
✓ returns a random number (1ms)
✓ returns an integer (1ms)
✓ generates a number within a defined range (24ms)
✕ generates a unique number (6ms)

● generates a unique number

expect(received).toBe(expected) // Object.is equality

Expected: "failed"
Received: 1

Our test fails. Since our code isn’t checking for anything or returning failed, this is expected. Although, it is possible your code received a 2 through 6.

How can we check if our function can’t find a unique number?

First, we need to do some sort of loop that will continue creating numbers until it finds one that’s valid. At some point though, if there are no valid numbers, we need to exit the loop so we avoid an infinite loop situation.

What we will do is keep track of each number we’ve created, and when we’ve created every number we can, and none of those numbers pass our unique check, we will break out of the loop and provide some feedback.

function getNewId(min = 0, max = 100, ids =[]) {
   let id;
   do {
      id = Math.floor(Math.random() * (max - min + 1)) + min;
   } while (ids.indexOf(id) > -1);
   return id;
}

First, we refactored getNewId() to include a parameter that is a list of current ID’s. In addition, we updated our parameters to provide default values in the event they aren’t specified.

Second, we use a do-while loop since we don’t know how many times it will take to create a random number that is unique. For example, we could specify a number from 1 to 1000 with the only number unavailable being 7. In other words, our current ID’s only has a single 7 in it. Although our function has 999 other numbers to choose from, it could theoretically produce the number 7 over and over again. While this is very unlikely, we use a do-while loop since we are not sure how many times it will run.

Additionally, notice we break out of the loop when our ID is unique. We determine this with indexOf().

We still have a problem, with the code currently how it is, if there are no numbers available, the loop will continue to run and we will be in an infinite loop. We need to keep track of all the numbers we create, so we know when we’ve run out of numbers.

function getRandomId(min = 0, max = 0, ids =[]) {
   let id;
   let a = [];
   do {
      id = Math.floor(Math.random() * (max - min + 1)) + min;
      if (a.indexOf(id) === -1) {
         a.push(id);
      }
      if (a.length === max - min + 1) {
         if (ids.indexOf(id) > -1) {
            return 'failed';
         }
      }
   } while (ids.indexOf(id) > -1);
   return id;
}

Here is what we did. We solve this problem by creating an array. And every time we create a number, add it to the array (unless it already in there). We know we’ve tried every number at least once when the length of that array is equal to the range we’ve chosen plus one. If we get to that point, we’ve created the last number. However, we still want to make sure the last number we created doesn’t pass the unique test. Because if it does, although we want the loop to be over, we still want to return that number. If not, we return “failed”.

PASS  ./id.spec.js
✓ returns a random number (1ms)
✓ returns an integer (1ms)
✓ generates a number within a defined range (24ms)
✓ generates a unique number (1ms)

Test Suites: 1 passed, 1 total

Tests:       4 passed, 4 total

Congratulations, we can ship our ID generator and make our millions!

Conclusion

Some of what we did was for demonstration purposes. Testing whether our number was within a specified range is fun, but that formula can be mathematically proven. So a better test might be to make sure the formula is called.

Also, you could get more creative with the random ID generator. For example, if it can’t find a unique number, the function could automatically increase the range by one.

One other thing we saw was how our tests and even specifications might crystalize a bit as we test and refactor. In other words, it would be silly to think nothing will change throughout the process.

Ultimately, test-driven development provides us with a framework to think about our code at a more granular level. It is up to you, the developer, to determine how granular you should define your tests and assertions. Keep in mind, the more tests you have, and the more narrowly focused your tests are, the more tightly coupled they become with your code. This might cause a reluctance to refactor because now you must also update your tests. There is certainly a balance in the number and granularity of your tests. The balance is up to you, the developer, to figure out.

Thanks for reading!

Found this helpful? I write about practical automation, productivity systems, and building smarter workflows — without the jargon. Visit me at brandonwoz.com.

I first read about test driven development (TDD) in some technical reviews blog, but I barely read it (or thought about it). Why would people write tests first when they already knew the logic?

So what was this all about? Writing tests first, incrementally building the logic, and doing it in iterations. The funny thing is, when you give two programmers five minutes to code a simple fibonacci sequence and ask one to do TDD, by the end of the 5 minutes, the programmer doing TDD may say “I have test for it!” But they won’t have finished the code. On the other hand, the other one will have finished the entire fibonacci sequence and will have optimized it.

Why use TDD? Aren’t unit tests good enough?

At the end of last year, I finally met TDD face to face. In a three-month bootcamp session, we were forced to always do things with TDD. I was already struggling enough, and so my brain always rebelled when it came time to write the tests.

Why should we write tests first when I can directly code the logic, my brain asked? Can’t we just write them later? After all functionality is finished?

How it looks when our TDD mentor convince us

Let me give you a quick overview of TDD in a nutshell.

Let’s say I’m creating a fibonacci function. I might ask, what is the simplest assertion on a fibonacci?
=> Returns 1 if input is 1.

Writing test first, no logic coded!

What is the simplest solution for that assertion? The simplest solution, I mean it.

Now, next move. What is next simplest assertion for fibonacci?
=> Returns 2 for inputs = 3

Again, let’s fix this very quickly. Just return it and add some branching.

Move to another expectation. Aim for a bigger number. Do it iteratively, incrementally.

On and on it goes, until you get the nice solution for your fibonacci function. If you want to practice more, try adding memoization during the process (and don’t forget—with TDD).

Did you notice what we did there? The baby steps, your assertion, and how we define the solution? Your thought process got separated into these five critical points:

Simple & Incremental Design — You have to think about what is the simplest thing a particular function could do, and what’s coming next. The fibonacci example describes this point perfectly.

Assertion — What is your expectation of that function? And how do you describe that expectation? Will other people understand it quickly?
Some test libraries provide you with a test description feature. That string is the only verbose thing that explains what your code is doing.

Make sure it’s a good explanation, or you’ll get a call on your holiday because your unreadable test case is failing, and no one knows why.

Your assertion and how you state it matters.

Testable Design — How should you design it so it can be testable? Take a look at these two snippets below.

The first one:

Look how messy it is if your code is not testable.

By doing TDD, since you write the test first, you have to make sure that your code is testable. You can see from the example that you don’t even test your fibonacci function. Instead, you test the side-effect of that fibonacci logic in your code, which invokes the console.log function.

The other thing is, you never know which one is failing, the console.log() or your fibonacci block when you refactor it. In this way, TDD leads us to increase modularity in our code.

Now, let’s look at second snippet.

In the second example, we can see that we test the particular fibonacci function, not the other function that spikes on it. We are confident that the function works perfectly under the conditions that we state. We are sure that if the other function invokes our fibonacci and fails, it is not from our code.

Negatives and Corner Cases — what do you expect when something’s not right: is it invoked with null? Does it throw an exception? How should it be handled? What could possibly happen in the code? What could be the strangest and weirdest thing that could happen in this loop? What test can catch that?

How many possibilities are there?

Boundaries — Should you expect that from your function? Are you sure it’s not another class’s responsibility?

My issues with TDD

Yes, it is slow indeed. Sometimes, your time is doubled since you’re writing both tests and logic at the same time. This makes how you use your keyboard important (typing speed, better shortcut usage, and so on).

And even worse —when the requirements change—you have to refactor or delete and rewrite test code you worked hard on. Which means that tests code is code you write that is more likely to be deleted in the future. And you are doing it, iteratively. DELETES. CODES. REWRITES. AGAIN. IN A LOOP!

Think about it. Why would you write code that is more likely to be deleted?

“Nope, that’s enough of this TDD thing. I’ll do it when I find a strong reason why I should spend time writing code I’m likely to delete”, I said to myself.

And that was right before I unconsciously started digging my own grave.

Why I changed my mind

The enlightenment came about two months later, when I was assigned to a group that did not implement TDD well at all.

I mean, they implemented TDD, but they left the tests broken. They didn’t bother to fix those failing test cases (which often broke because the requirements had changed). And this happened because of the most cliche reason in the world: they didn’t have time. They had to make deadlines.

After looking at the situation, I mumbled “Look, see! This TDD doesn’t work in the production world!” It made me question many things: is this TDD worth fighting for? Is TDD worth the time? Does it even deliver any business value?

After a while, I realized that the problems were growing exponentially, tasks were getting delayed, chaos was reigning, and the developer experience was getting really bad — all because they implemented TDD poorly and halfheartedly. It was even worse than not writing tests at all.

Here are some of the issues it caused:

• When I added a new feature or refactored things, I didn’t know whether that code was failing or not because the test was already failing.

We do not know which tests do I fails on, because almost all of it already failing before! --_

• We were forced to have high threshold on code coverage. And make no mistake, programmers are smart and sneaky. They write tests with no expectations, like smoke tests. And that was the only test they had on that particular logic. It was like, we only knew it was failing after everything was on fire. How dangerous.

Always passing, anyway! All hail code coverage!

• We used CI/CD for deployment. And we always deployed even though it was failing, which was scary: You never knew whether your production itself was failing, or if it was because you didn’t fix the tests.

Test is failing, deploy anyway!

• After production, we ended up fixing strange and completely out-of-mind bugs. We had never even thought of those strange conditions before. (Ever find a situation when something in a try-catch block is failing but not throwing an exception?)

Oh, the horror!

After analyzing the situation, doing it in iterations, and reflecting on it, I realized that TDD is actually a golden nugget. If done right, it can make us better developers.

Why I now love TDD

With TDD, you have fewer bugs

You’ll hardly miss things that you can catch with your tests.

When you get a requirement, you write a test for it first. Then you run the test, and see if it fails first. When you add the logic, you see if it passes.

Seeing it fail is important, because you know what broke your code. In the long run, this practice ensures that all lines in your code are well-tested.

TDD saves you lot of time (in the future)

CI/CD relies heavily on tests. If you write the wrong tests (or too few tests) you already wasted five hours to find what errors it couldn’t catch. If you write good tests, and spend just five more minutes writing deeper and more complete conditions of your code, you’ll save time debugging it in the future.

TDD deals with the human aspects of coding

The main ones being negligence and forgetfulness. If you write all the logic directly, by the end of, say, line 190, you may forget why you multiplied a variable by 100 at line 19.

But, by doing it incrementally and stating the assertion of our code, we gradually build our understanding. This makes us understand the code and its behaviors better.

As a bonus, we have sort of living and functional documentation of our code. You can see which test is failing if you delete the previous line, and you instantly know why.

TDD helps you focus

Programmers tend to write too much code, or write code that does too much. Or they try to plan for conditions that never exist. Often, when my team practiced pair pairing, I discovered that TDD allowed us to write less code compared to other teams that didn’t do TDD. While coding, we were focused on getting the test case passed — nothing less, nothing more.

TDD also benefits your brain

You have proof of your code’s readiness for production, even before deploying it. You don’t have to worry about things you already tested for before. You don’t have to brag to your project manager about how project is going, because you can show them that the tests are passing!

However, TDD is not always your silver bullet. It takes time. You have to set up the project — such as the environment, mocks, and stubs — even before you start doing anything.

But remember, time spent on writing tests is not wasted time. It’s the time you invest now to save your time later. It’s the investment you make on the system you build, as you build code on top of more code. And you want to make its foundation as solid as possible. TDD gives you that.

In the end, it could cost you a fortune if you don’t do TDD. It may take time, but it is good for you and your team in the long run.

This is not a primer on Test Driven Development. It contains my personal observations of re-starting the discipline and the problem of unit testing craft.

Kent Beck, a software engineering leader, is also the modern day re-inventor of test driven development (TDD). Kent also cowrote JUnit, a widely used testing framework, with Erich Gamma.

In his book, XP Explained (second edition), Kent describes that at the intersection of values and practices form principles. When we iterate from the concept and plug in what we believe as a formula, we achieve a transformation.

[KISS, Quality, YAGNI, ...] + [Testing, Specs, ...] == [TDD, ...]

I have a profound respect for Kent’s life work not only because of his brilliant software creations but also his continued exploration of trust, courage, feedback, simplicity and vulnerability. All attributes are paramount to the invention of Extreme Programming (XP).

TDD is a principle and a discipline that is followed by the XP community. The discipline has been present for nineteen years.

In this post, I will describe my opinion of where TDD stands in its adoption. Following this, we will explore intriguing personal observations as we perform TDD. Finally, we will conclude by postulating why TDD hasn’t taken off as it should. Let’s begin.

TDD, Studies, And Professionalism

Nineteen years in, TDD is still debated as a discipline in the development community.

The first question an analytical person would ask, is “How many or what percentage of software professionals use TDD today?” If you asked a friend of Robert Martin (Uncle Bob), a friend of Kent Beck, the answer would be one hundred percent. This is because Uncle Bob believes that it is infeasible to consider being a professional if test driven development is not practiced. [1]

Uncle Bob has been the focus of the discipline for some years now and it is natural to discuss him as a part of this write up. Uncle Bob has defended TDD and has pushed the discipline’s boundaries significantly. It should go without question that I too respect Uncle Bob and his pragmatic dogmatism.

However, no one asks the follow up question “the definition of practice is the deliberate use of — but it does not specify amount or percentage of, right?” My subjective estimation is that a majority have not practiced TDD even in some small timeframe.

The reality of the situation is that we actually do not know, since the practice percentage has not been studied widely. The only concrete measurement we have is a small collection of companies being gathered at WeDoTDD. Here, there is tracking of such companies. Interviews are conducted with those who practice 100% of the time, but that list is small. It is also incomplete since simple searching reveals other larger shops practicing — but perhaps not at full capacity.

If we don’t know how many are practicing, the next question is “how effective is TDD based on measured benefits?”

You would be pleased to know that there have been studies conducted over the years that have proven TDD’s effectiveness. This includes the well recognized reports from Microsoft, IBM, North Carolina University, and the University of Helsinki.

An impactful visual taken from the Helsinki report.

These reports prove to a degree that defect density is reduced by 40% to 60% in exchange for increased effort and execution time by 15% to 35%. These numbers have also begun to echo through books and new industry processes such as the DevOps community.

With these questions half answered, the final question is “what should I expect as I start to perform TDD?” You are in luck, because I have formulated my own observations of TDD. Let’s review them next.

1. TDD Commands Verbalizing An Approach

As we practice TDD, we begin to experience a phenomena of “calling the shot”. In simple terms, the short acts of creating failing and passing tests will intellectually challenge the developer. They will say aloud “I think this will pass” and “I do not think this will pass” or “I’m not sure, let me think after I try this approach.”

The developer’s IDE has become a rubber duck begging for an intense conversation. At a minimum, TDD shops should be humming with this type of conversion.

Think, then speak up about your immediate next move(s).

This type of reinforcement is key to communication, not only to predict your next action, but also to reinforce the concepts of writing the simplest code to make a unit test pass. Of course, if the developer becomes silent, they are almost certainly wandering off the loop and must come back on the path.

2. TDD Commands Muscle Memory

As a developer moves forward with the first cycles of TDD, they will experience heavy fatigue by battling through high friction and awkward flow. This is true for any initiated but unlearned human activity. The developer will attempt to find shortcuts to improve the cycle, because the goal is to reduce that awkwardness and to improve muscle memory.

Muscle memory is a key to feeling the good vibes and becoming fluid. TDD demands it because of execution repetition.

Print out a shortcut cheat sheet. Learn only as many shortcuts in your IDE as you need to make your cycles efficient. Then, keep searching for more.

The developer will become an expert of select shortcuts only in a matter of a few sittings, including building and running the test rig. With more practice, creating new artifacts, highlighting text, and navigating the IDE will become natural. Finally we graduate to unlock all of the refactor shortcuts such as extraction, renaming, generation, pulling up, reformatting, and pushing down code.

3. TDD Commands Thinking At Least Slightly Forward

Each time a developer sits to start TDD, they must have a concrete short mental map on what is to be solved. In a traditional coding approach, this is not always true, as the mental map of the solve could be macro and exploratory. The developer does not know how to solve the problem, but may know of a fuzzy goal. To get to that goal, unit tests are neglected in the process.

The start and end of the sitting should also be ritualized. First, think and list. Play with it. List more. Then start, do, and then think. Check off. Repeat some times. Finally think and stop.

Maintain your test list like a hawk. Check off items as you go. Never drive without one. Think!

The list may take some time to formulate and is not a part of the cycle. However it should be prepared right before the cycles start. If you don’t have one, you may not know where you are going. Always have a map.

// A Test List// "" -> does not validate// "a" -> does not validate// "aa" -> validates// "racecar" -> validates// "Racecar" -> validates// print the validation// have a blueberry ale

The developer must command a test list, as described by Kent Beck. The test list allows direction of solving in the next immediate cycles. That test list should always be labored upon and updated moments before the cycles begin. Once the test list is solved minus the last step, the cycle stops on red with a failing test.

4. TDD Demands Communication With Others

As the above test list is filled out, certain steps may become blocked because the commitment of work was not clear. The developer cannot figure out the test list. Or the reverse. Generating a presumptive test list that has too many guesses about the missing requirement(s). The suggestion is to stop right there.

Driving without TDD will cause implementations of unneeded complexity to occur. Driving with TDD in listless mindlessness is just as dangerous.

Speak up loudly if the test list has gaps.

In TDD, the developer must understand what to build based on the owner’s picture of the requirement(s) and no more. If the requirement is unclear in context, the test list will start to break down. That break down will require a conversation. Candid conversions can quickly turn into trust and respect. The short feedback loops are now established.

5. TDD Demands Iterative Architecture

Initially proposed in the first edition of the XP book, Kent proposed that tests should drive architecture. However, over the course of a few years there have been stories about how sprint teams crash into walls about a few sprints in.

Of course, having tests drive all of the architecture is unwise. Uncle Bob had agreed with other experts that architecture driven by tests is “horse sh*t.” [1] Some larger map is required, but not too far above the distributed test lists that are being worked on in the field.

Kent also called this out many years ago in the TDD By Example book. Concurrency and security are the two major areas where TDD cannot drive and the developer must be concerned separately. Loosely translated, concurrency via system design is on a different level and must be labored over iteratively and in concert with TDD. This is very true today, as some architectures are driving toward reactive and reactive extensions, the zenith of concurrency construction.

Create a larger map of organization. A vision that goes just a little bit ahead. Make sure you are steering with the team in the same way.

However, the most important idea is the organization of the system which TDD cannot effectively handle alone. This is because unit tests test at a lower level. Iterative architecture and TDD orchestration is hard in practice and demands trust among all team members, pair programming, and solid code review. There is no clear way to do this, but it will become apparent that short iterative design sessions are needed in unison with the test lists in the field.

6: TDD Reveals Unit Test Frailty And Degenerative Implementation

Unit tests have a funny property about them and TDD exposes that property. They cannot prove correctness. E.W. Dijkstra had labored over this and discussed the possibility of mathematical proofs in our profession to resolve the gap.

For example, the below solves all tests around a hypothetical imperfect palindrome that business required. It was developed with TDD.

// Not an imperfect palindrome.

@Testfun `Given "", then it does not validate`() {    "".validate().shouldBeFalse()}@Testfun `Given "a", then it does not validate`() {    "a".validate().shouldBeFalse()}@Testfun `Given "aa", then it validates`() {    "aa".validate().shouldBeTrue()}@Testfun `Given "abba", then it validates`() {    "abba".validate().shouldBeTrue()}@Testfun `Given "racecar", then it validates`() {    "racecar".validate().shouldBeTrue()}@Testfun `Given "Racecar", then it validates`() {    "Racecar".validate().shouldBeTrue()}

Indeed, these tests have holes. Unit tests are frail even for the most trivial asks. We can never prove correctness because if we had to, it would require an extreme mental labor and the required inputs would be unimaginable.

// Too generic of a solve based on tests provided

fun String.validate() = if (isEmpty() || length == 1) false else toLowerCase() == toLowerCase().reversed()

// Is the best implementation and solves all tests

fun String.validate() = length > 1

length >; 1 could be called degenerative implementation. It is just enough implementation to solve the problem at hand, but on its own tells us nothing about the problem we are trying to solve.

The question is, when does an developer stop writing the tests? The answer seems to be simple. When the business is satisfied, not when the code author is. This may hurt our construction passion and we are embarrassed by the simplicity. These feelings are balanced by the good feelings of clean code and the ability to refactor with confidence later. Things simply feel tidy and clean.

Be aware that the unit tests are fallible but are necessary. Understand their strength and weakness. Mutation testing may help tie up this gap.

TDD has gains, but it can take away building the sand castles we do not need. It is constraint but it allows us to go faster, further and with safety. Perhaps this is what Uncle Bob really meant about being a professional.

But! No matter how frail unit tests may seem, they are a core necessity. They are required to allow fear to turn into courage. Tests allow those to mercifully refactor the code and even better, it is a guide, a documentation, for any other developer to immediately jump in and being to add value to a project that is well supported by unit testing.

7: TDD Reveals Assertion Completion Feedback Loop

Take a step back further. For the next two phenomena, we will visit strange re-occurrences. For the first occurrence, let’s take a quick look at FizzBuzz. Here is our test list.

// Print numbers 9 to 15. [OK]// For numbers divisible by 3, print Fizz instead of the number.// ...

We are a few steps in. We now have a failing test.

@Testfun `Given numbers, replace those divisible by 3 with "Fizz"`() {    val machine = FizzBuzz()    assertEquals(machine.print(), "?")}class FizzBuzz {    fun print(): String {        var output = ""        for (i in 9..15) {            output += if (i % 3 == 0) {                "Fizz "            } else "${i} "        }        return output.trim()    }}

Expected <Fizz 10 11 Fizz 13 14 Fizz>, actual <?>.

Naturally, if we duplicate the expected assertion data to assertEquals, it achieves the result and the test passes.

As we keep querying the test rig during implementation steps, failing unit tests set around data may correctly answer their own assertions. Perhaps we can call this voodoo testing.

Sometimes failing tests will scream a correct result that is required to make the test pass. I do not know what to call these events… perhaps voodoo testing. Your milage may vary based on your laziness and test etiquette, but I have seen this happen numerous times when working to have implementation achieve canned and expected data sets.

8: TDD Reveals The Transformation Priority Premise

In TDD, one can become trapped. There are situations where the developer can be entangled by the transformations they apply to achieve implementation. At some point, the testing code becomes a bottle neck to move forward. An impasse forms. The developer has to back out, and disarm by removing a portion of tests to get out of the hole. The developer becomes exposed.

Uncle Bob likely has experienced these impasses in his career, and then he probably realized that the act of making a test pass must require a preferred order so that the risk of a impasse is reduced. At the same time, he also would’ve realized a premise. As the tests get more specific, the code gets more generic.

The order of the transformations. One should always prefer the simplest (top of the list).

This is called the Transformation Priority Premise. There seems to be an order of refactor risk one can chose to achieve by passing a test. The top transformation chosen (the simplest) is usually the best option and will incur the least risk to create a situation of an impasse.

TPP or perhaps Uncle Bob’s Test Calculus is one of the most intriguing, technical, and exciting observations to date. Use it as a guide to keep the code as simple as possible.

Print out the TPP list and place it at your desk. Refer to it as you drive to avoid impasses. Embrace an order of simplicity.

This completes all initial observations. But before we conclude, I’d like to get back to my original unanswered question “How many or what percentage of software professionals use TDD today?” My answer stands at “I think the group is small”. I’d like to explore this guess below with reasons why.

Has TDD Taken Off?

Unfortunately it hasn’t. The percentage is subjectively low and the search for data continues. Taking from my experiencing in hiring, leading teams, and being an empathic developer myself, let me rely my observations.

Reason 1: No Exposure To Real Testing Culture

My educated guess is that a majority of software developers have not had the experience of learning and working through a testing culture.

The definition of a testing culture is a place where developers are deliberately practicing and improving by testing. They are continuously mentoring those who are not skilled in the area. Each pairing and in every pull request is a feedback loop on building individuals to become great at testing. There is also major support and backing all the way up the engineering chain. All managers understand and believe in testing. When deadlines and times get tough, the test discipline is not dropped — it is maintained.

Those that have gone through a testing culture, like myself, are lucky to have those observations. We can apply the experience to future projects.

Reason 2: Unclear Educational Resources

Some have attempted to write books on the subject such as xUnit Patterns and Effective Unit Testing. However, there seems to be no place that clearly defines what and why to test. Most resources out there do not clearly describe the craft of assertion and verification.

Open source projects are also hit or miss with good unit tests. In these unfamiliar projects, the very first thing I do is look for tests. My disappointment is almost certain. I can also remember the very few instances of excitement when tests are present but also… readable.

Reason 3: No Focus In Universities

My observation of candidates over the years fresh out of university reveals a well-known assumption: little to no discipline in testing rigor. Every developer I know has learned testing afterward, some on their own but most going through a previous testing culture experience.

Reason 4: A Career Of High Test Passion Required

It also takes passion to be interested in testing and to understand the details and benefits over a large time period. You have to be hungry and obsess on clean code and doing the craft better.

Most just want to get things working, achieving only half of what Kent Beck said “First make it work, then make it right.” I empathize that to get things working is a tough battle in itself.

Testing is just as hard to do well, so let’s conclude on that thought.

Conclusion

Kent’s proposal in XP included a simple formulation of instinct, thought, and experience. These three levels are stepping stones to execution quality measured by a threshold. This is a great model to explain a problem with TDD.

The threshold for clean test execution is high, in that it eclipses a generous baseline of experience. The majority will never become above water and those that do are lucky — have experience from the elusive testing culture.

From XP Explained. Originally about design quality, imagine a higher threshold line.

Software is tough enough to build and organize, but testing takes it to a whole new level of enlightenment.

Early on, I had an instinct that testing is important, but my test culture experience came later. It took years of thought in my career, but without that experience of test culture, I would have not emerged above that threshold.

I believe that many developers also have this thought but cannot see the true benefit of test culture due to lack of specific experience.

TDD discipline has struggled to take off due in part to high learning curve of testing. Even armed with veteran testing knowledge and experience, TDD requires a headspace that is unique and challenging. However, all should try it.

Amplify this. TDD demands all that thought and experience and more. It is not easy and is a skill. I think it is because it commands the developers throughput to the maximum, continuously and relentlessly. We are all vulnerable in the process, and few developers like being in this position.

@Testfun `Given software, when we build, then we expect tests`() {    build(software) shoudHave tests}

However, TDD is an intriguing discipline and is a tool to lean on. Its phenomena should be studied in detail. If anything else, the discipline makes for better developers as the practice contains benefits which can strengthen the individual and collective group.

Inspiration for this post was due in part by Danny Preussler. As I re-explore the discipline, he has started running comprehensive Android TDD workshops. Check out his recent deck here.

[1] Jim Coplien and Bob Martin Debate TDD

“Give me six hours to chop down a tree and I will spend the first four sharpening the axe.” — Abraham Lincoln

When I refactored a project a few weeks ago, I spent most of my time writing specs. After writing several similar test cases for some APIs, I started to wonder whether I might be able to get rid of a lot of this duplication.

So I threw myself into reading up on the best practices for DRYing up tests (Don’t Repeat Yourself). And that’s how I came to know of shared examples and shared contexts.

In my case, I ended up using shared examples. And here’s what I’ve learned so far from applying these.

When you have multiple specs that describe similar behavior, it might be better to extract redundant examples into shared examples and use them in multiple specs.

Suppose you have two models User and Post, and a user can have many posts. Users should be able to view list of users and posts. Creating an index action in the users and posts controllers will serve this purpose.

First, write specs for your index action for the users controller. It will have the responsibility of fetching users and rendering them with proper layout. Then write enough code to make tests pass.

# users_controller_spec.rbdescribe "GET #index" do  before do     5.times do      FactoryGirl.create(:user)     end    get :index  end  it {  expect(subject).to respond_with(:ok) }  it {  expect(subject).to render_template(:index) }  it {  expect(assigns(:users)).to match(User.all) }end

# users_controller.rbclass UsersController < ApplicationController  ....  def index    @users = User.all  end  ....end

Typically, the index action of any controller fetches and aggregates data from few resources as required. It also adds pagination, searching, sorting, filtering and scoping.

Finally, all these data are presented to views via HTML, JSON, or XML using APIs. To simplify my example, the index actions of controllers will just fetch data, then show them via views.

The same goes for the index action in the posts controller:

describe "GET #index" do   before do     5.times do      FactoryGirl.create(:post)    end    get :index  end  it {  expect(subject).to respond_with(:ok) }  it {  expect(subject).to render_template(:index) }  it {  expect(assigns(:posts)).to match(Post.all) }end

# posts_controller.rbclass PostsController < ApplicationController  ....  def index    @posts = Post.all  end  ....end

RSpec tests written for both users and posts controller are very similar. In both controllers we have:

• The response code — should be ‘OK’
• Both index action should render proper partial or view — in our case index
• The data we want to render, such as posts or users

Let’s DRY the specs for our index action by using shared examples.

Where to put your shared examples

I like to place shared examples inside the _specs/support/sharedexamples directory so that all shared example-related files are loaded automatically.

You can read about other commonly used conventions for locating your shared examples here: shared examples documentation

How to define a shared example

Your index action should respond with 200 success code (OK) and render your index template.

RSpec.shared_examples "index examples" do   it { expect(subject).to respond_with(:ok) }  it { expect(subject).to render_template(:index) }end

Apart from your it blocks — and before and after your hooks — you can add let blocks, context, and describe blocks, which can also be defined inside shared examples.

I personally prefer to keep shared examples simple and concise, and don’t add contexts and let blocks. The shared examples block also accepts parameters, which I’ll cover below.

How to use shared examples

Adding include_examples "index examples" to your users and posts controller specs includes “index examples” to your tests.

# users_controller_spec.rbdescribe "GET #index" do  before do     5.times do      FactoryGirl.create(:user)     end    get :index  end  include_examples "index examples"  it {  expect(assigns(:users)).to match(User.all) }end

# similarly, in posts_controller_spec.rbdescribe "GET #index" do  before do     5.times do      FactoryGirl.create(:post)     end    get :index  end  include_examples "index examples"  it {  expect(assigns(:posts)).to match(Post.all) }end

You can also use it_behaves_like or it_should_behaves_like instead of include_examples in this case. it_behaves_like and it_should_behaves_like are actually aliases, and work in same manner, so they can be used interchangeably. But include_examples and it_behaves_like are different.

As stated in the official documentation:

• include_examples — includes examples in the current context
• it_behaves_like and it_should_behave_like include the examples in a nested context

Why does this distinction matter?

RSpec’s documentation gives a proper answer:

When you include parameterized examples in the current context multiple times, you may override previous method definitions and last declaration wins.

So when you face situation where parameterized examples contain methods that conflict with other methods in same context, you can replace include_examples with it_behaves_like method. This will create a nested context and avoid this kind of situations.

Check out the following line in your users controller specs, and posts controller specs:

it { expect(assigns(:users)).to match(User.all) }it { expect(assigns(:posts)).to match(Post.all) }

Now your controller specs can be re-factored further by passing parameters to shared example as below:

# specs/support/shared_examples/index_examples.rb

# here assigned_resource and resource class are parameters passed to index examples block RSpec.shared_examples "index examples" do |assigned_resource, resource_class|   it { expect(subject).to respond_with(:ok) }  it { expect(subject).to render_template(:index) }  it {  expect(assigns(assigned_resource)).to match(resource_class.all)   }end

Now, make following changes to your users and posts controller specs:

# users_controller_spec.rbdescribe "GET #index" do  before do     ...  end  include_examples "index examples", :users, User.allend

# posts_controller_spec.rbdescribe "GET #index" do  before do     ...  end  include_examples "index examples", :posts, Post.allend

Now controller specs look clean, less redundant and more importantly, DRY. Furthermore, these index examples can serve as basic structures for designing the index action of other controllers.

Conclusion

By moving common examples into a separate file, you can eliminate duplication and improve the consistency of your controller actions throughout your application. This is very useful in case of designing APIs, as you can use the existing structure of RSpec tests to design tests and create APIs that adhere to your common response structure.

Mostly, when I work with APIs, I use shared examples to provide me with a common structure to design similar APIs.

Feel free to share how you DRY up your specs by using shared examples.

Tips on how to apply TDD more efficiently, and why it's a valuable technique

There's a common pattern we follow when we start a project using TDD. We describe the specifications of what we expect the system to do in the form of a special test. This "special test" can be an end-to-end with the front-end or an integration test that executes an HTTP request to test the back-end.

It's the first test we write. We do it before a single line of code is written. That special test will serve as a guideline to make sure we don't break anything that prevents the regular flow from working. If we don't do that and rely solely on unit tests, there's a chance that, eventually, we will have all tests passing but the server will not be starting or the user won’t be able to do anything on the screen.

When starting a project using TDD, there's a common pattern to create a special test to make sure we don’t break anything that prevents the regular flow from working.

After we make that special test pass with a naive implementation (or we can keep it failing if we are using ATDD to drive the application internals), we start building the units of the system using a similar pattern on a micro level, never breaking any test we created earlier. We describe each unit of the system through a failing test and make it pass with a naive implementation first. Then, we identify smells and refactor it if necessary so that we can keep the cycle going over and over again.

That’s called the Red/Green/Refactor cycle of TDD.

This cycle will drive us to build all the pieces of our application with enough confidence that it will be robust and maintainable. It will also expose problems early if we were to get stuck due to the wrong assumption of how the API is supposed to behave.

There's one important thing we should be careful about: we should avoid refactoring code or adding a new test while another test is failing. If we do that, there's a high chance we will get stuck because of the unnecessary cognitive load of worrying about another rule we have already covered. To prevent that, we need to fix the failing test before starting anything else.

In TDD, we should avoid refactoring code or adding a new test while another test is failing.

There are circumstances where one would prefer writing tests after writing the code. However, there are some negative effects that come with that approach:

• We can miss important functionality because it’s harder to know if the coverage matches our expectation.
• It can create false positives because we won’t see a failing test first.
• It can make us over-engineer the architecture because we won’t have any guidelines to force us to write the minimum amount of code that fits in our most basic requirements.
• It's harder to validate if the message for the failing test is clear and pointing to the cause of that failure or not.

One thing to keep in mind is that TDD can be posed as a discipline, but there's no way to create a discipline for writing tests after the production code.

There are cases when there's no value in applying TDD or automated testing at all. It's when we're testing some IO layers, support functions for the tests, or things built using a declarative language like HTML or CSS (we can test the visual in CSS, but not the CSS code). However, testing is a fundamental part of the process that ensures a complex piece of functionality satisfies a set of expectations. That alone allows us to be confident enough that each part of the system works as expected.

There are cases when there's no value in applying TDD or automated testing at all, like when testing IO layers, support functions for the tests, or code written with a declarative language.

There's a concept called The Transformation Priority Premise. The TL;DR is that there are some transformations we can apply when making the code more generic in the "green" phase of the TDD cycle.

"Refactor" is when we change the structure of the code without changing its behavior. The Transformations are not called "refactoring" because they change the structure and the behavior of the code to make it more generic.

An example of using the Transformation Priority is when we make a test that forces us from returning a single constant to returning an argument that will contain more than one value. In this case, it's the constant->scalar priority transformation.

So what are these transformations? Perhaps we can make a list of them:

* ({}–>nil) no code at all -> code that employs nil

* (nil->constant)

* (constant->constant+) a simple constant to a more complex constant

* (constant->scalar) replacing a constant with a variable or an argument

* (statement->statements) adding more unconditional statements.

* (unconditional->if) splitting the execution path

* (scalar->array)

* (array->container)

* (statement->recursion)

* (if->while)

* (expression->function) replacing an expression with a function or algorithm

* (variable->assignment) replacing the value of a variable.

There are likely others.

— Excerpt from The Transformation Priority Premise article

In TDD, The Transformation Priority Premise can give us a guideline for the "green" phase.

Writing correct software is hard. TDD is a common pattern where we use the tests to help driving the implementation of our system while retaining a huge percentage of test coverage. However, it's not a Silver Bullet.

If we are using TDD, we should avoid refactoring the code when the tests are failing. To make it pass in the "green" phase, we use the Transformation Priority Premise to guide us in the most naive implementation approach we can take before refactoring.

In comparison with other ways of writing tests, TDD can take more time in the beginning. However, as with every new skill, with enough practice we will reach a plateau, and the time it takes to apply TDD will be no different than the time it would take to write tests in a traditional way.

The difference now is that your software will be less likely to behave in a way you didn't expect.

And for all practical means, that's no different than 100% test coverage.

Thanks for reading. If you have some feedback, reach out to me on Twitter, Facebook or Github.