How to Write Unit Tests: A Problem-Solving Approach

Unit testing is a core software development practice that gives testers and developers the visibility they need to ensure individual code components like methods, functions, or classes work as expected. By isolating and testing these small units, teams can catch issues earlier in the development cycle and make debugging more straightforward. 

It also helps both developers and testers better understand the codebase, enabling quicker changes to problematic areas and reducing the chance of bugs slipping into later stages of testing. Whether you’re working with TDD, BDD, or another development approach, this guide will walk you through practical techniques and best practices for writing and running unit tests effectively.

How to write unit tests

Unit tests should be precise, dependable, and follow established best practices. In practical terms, this means organizing related test cases clearly, naming them consistently, and using meaningful assertions to validate expected behavior.

1. Identify the unit’s purpose

Before you write a unit test, take a step back and ask: What is this unit supposed to do? Having a clear understanding of its intended purpose will guide the rest of your test design process.

Here are some key steps to help you identify the unit’s purpose:

• Requirement analysis: Review relevant specifications and requirements related to the unit. This helps ground your test in business or technical expectations.
• Code study: Read through the code to understand its logic, dependencies, inputs, and outputs. This step helps you uncover any potential edge cases or areas of complexity.
• Identifying test scenarios: Determine all the possible situations the unit might encounter, including error conditions and boundary cases. It’s a good idea to involve the QA team at this stage—they can help evaluate risks, spot edge cases, and suggest scenarios based on both functional requirements and real-world user behavior.

2. Select a unit test support framework

Choose a unit testing framework that integrates smoothly with your programming language and aligns with your testing goals. The right framework will make it easier to handle tasks like test discovery, setup, and teardown, and assertion management—helping you write maintainable, scalable tests.

Here are some widely used frameworks to consider, depending on your language and use case:

• JUnit (Java) – Ideal for test-driven development (TDD); simple, fast, and widely adopted.
• TestNG (Java) – Offers more advanced capabilities than JUnit, such as parallel test execution and data-driven testing.
• Pytest (Python) – A versatile framework for writing everything from simple unit tests to complex test suites, with minimal boilerplate.
• Robot Framework (Python-based) – Especially useful for acceptance testing and acceptance test-driven development (ATDD).
• Jest (JavaScript) – Optimized for JavaScript projects, particularly React applications.
• Mocha (JavaScript) – A flexible test framework often paired with Chai for powerful assertion support.
• ChaiJS and Jasmine (JavaScript) – Good choices for behavior-driven development (BDD) testing styles.
• Puppeteer (Node.js) – Designed for browser-based testing, particularly in headless Chrome environments.
• RSpec (Ruby) – A popular BDD-style framework for testing in Ruby applications.
• NUnit (.NET) – A mature and widely used testing framework for C# and the .NET ecosystem, part of the xUnit family.

3. Prepare the environment

Once you’ve selected your unit testing framework, the next step is to prepare the environment in which your tests will run. This involves more than just installing dependencies—it’s about creating a stable, consistent, and isolated setup that allows your tests to execute reliably across different machines and environments.

Here are some key steps to consider when setting up your test environment:

• Install and configure dependencies: Include all necessary libraries, plug-ins, and external services your application depends on.
• Set up environment variables: Define any environment-specific variables needed for the application to function as expected.
• Use mocks or stubs: Replace external dependencies—such as APIs, databases, or third-party services—with controlled mock objects to keep tests focused and isolated.
• Ensure repeatability: Avoid test flakiness by eliminating dependencies on system state or external conditions. Tests should run consistently regardless of where or how they’re executed.
• Structure tests clearly: Follow the Arrange, Act, Assert (AAA) pattern to make each test easy to read and reason about:
  • Arrange – Set up everything the test needs (e.g., mock data, configurations, or dependencies).
  • Act – Execute the specific function or unit being tested.
  • Assert – Verify that the output or behavior matches the expected result.

4. Write the test case

Start with a narrow focus: each unit test should validate a single behavior or outcome. Unit test functions should be concise, readable, and test only a small piece of logic at a time. This approach improves clarity and makes your tests easier to maintain over time.

To reduce redundancy in your test setup, look for patterns in repeated code. If you find yourself writing the same initialization or configuration steps across multiple tests, consider extracting those steps into helper methods or reusable setup functions. This approach—often referred to as composition—helps eliminate duplication and keeps your tests clean, consistent, and easier to update as your code evolves.

5. Execute the test

Once you’ve written your unit test cases, the next step is to run them and verify that the code behaves as expected under various conditions. Use your chosen testing framework to execute the tests and analyze the results. Check which tests pass or fail, and investigate any inconsistencies or unexpected behaviors to catch issues early in the development cycle.

If your team uses behavior-driven development (BDD), this is also a good time to involve non-technical stakeholders such as business analysts or product owners in the testing process. BDD promotes shared understanding by describing system behavior in clear, structured, and human-readable language.

One common way to express BDD-style tests is through the  Given-When-Then (GWT) format:

• Given – Sets up the initial conditions for the test (e.g., initializing objects or defining input values).
• When – Describes the action that triggers the behavior (e.g., calling a method or performing an operation).
• Then – Defines the expected outcome or result.

Using this format can help ensure that test cases are clear, consistent, and aligned with business requirements, especially in teams that prioritize collaboration between technical and non-technical roles

6. Analyze the results

After executing your unit tests, take time to review the results and identify any issues or unexpected behaviors in the code. When problems surface, it’s not just about fixing them—it’s equally important to document and report them. Doing so allows your team to track patterns, gather metrics, and improve the overall testing process over time.

One of the most effective ways to determine whether a unit test fulfills its purpose is through the use of assertions. Assertions check whether actual outcomes match expected results and can range from simple validations like comparing strings or numbers to more complex checks involving multiple components or conditions.

If you’re using a tool like the TRCLI (TestRail Command Line Interface), you can capture assertions as individual test cases. Uploading these results to your TestRail instance makes it easy to manage and trace unit test outcomes within your broader QA workflow, enabling better visibility and tracking across teams.

Addressing complex scenarios

Writing effective unit tests goes beyond checking basic functionality. To truly validate a system’s reliability, you also need to address more complex scenarios, such as testing edge cases, mocking dependencies, and handling asynchronous operations.

Testing edge cases

Edge cases refer to rare or unexpected input scenarios that can cause a program to behave in unintended ways. While they’re often overlooked during basic testing, edge case tests are essential for verifying how robust and resilient your code really is.

Here are some strategies for designing effective edge case unit tests:

• Use boundary values: Test inputs at the extreme ends of acceptable ranges (e.g., the minimum and maximum allowed values).
• Test empty, null, or unexpected types: Validate how the unit handles inputs like empty strings, null, or data types that don’t conform to expectations.
• Input oversized values: Try extremely long strings or inputs with special characters to assess how the code manages overflow or formatting.
• Enter out-of-range dates: Use values like years before 1901 or after 2038 to reveal date-related overflow issues.
• Try potentially malicious input: Inject JavaScript or JSON into fields expecting plain text to confirm proper sanitization and error handling.

Example edge case:

• Scenario: A user enters “01/01/3000” into a date field.
• Expected result: The system either handles the input gracefully or throws a controlled validation error without crashing or producing unpredictable results.

When designing edge case tests, put yourself in the user’s shoes. Consider what could go wrong, what might be entered accidentally or intentionally, and how the system should respond. Proactively testing these edge cases helps prevent issues from slipping through to later testing phases or, worse, into production.

Mocking dependencies

Mocking helps isolate the code under test by replacing real dependencies like APIs, databases, or external services with controlled, simulated versions. This allows you to focus solely on the behavior of the unit being tested without interference from outside systems.

For example:

• Mocks simulate the behavior of real objects by returning predefined responses and allowing you to verify interactions (e.g., checking if a function was called).
• Stubs provide hardcoded outputs for specific inputs but don’t track interactions—they simply support the test with consistent data.

By using mocks and stubs, you can make your tests deterministic, meaning they behave the same way every time. Mocked dependencies are also useful for simulating failures, such as timeouts, server errors, or invalid responses, so you can confirm that your code handles those conditions correctly.

Handling asynchronous code

Testing asynchronous code is crucial when your application includes operations that don’t execute immediately, like background tasks, database queries, or API calls. These operations often run on different threads or as non-blocking functions, making it more challenging to predict their behavior without a thoughtful test design.

To test async code effectively:

• Use your testing framework’s built-in async support (e.g., async/await patterns or done() callbacks).
• Mock time delays, responses, or asynchronous side effects to simulate real-world behavior.
• Ensure tests wait for the correct condition or response rather than relying on arbitrary timeouts.

Testing for concurrency issues early on, especially when unit tests pass for individual functions,, helps ensure the system behaves correctly under real-world timing and load conditions.

Measuring test quality

Measuring test quality is key to validating the robustness, reliability, and correctness of your code during unit testing. It also helps surface flaky tests, speeds up debugging, and improves the long-term maintainability of your test suite.

Tracking coverage

Code coverage metrics help QA and development teams understand how thoroughly their tests exercise the application code. The following types of coverage offer different insights into test completeness:

• Line coverage – Measures the percentage of lines of code executed during testing. Helps identify which lines are tested and which are not.
• Branch coverage – Measures how many decision branches (like if/else conditions) have been executed under varying inputs.
• Statement coverage – Tracks the percentage of individual statements in the code that were executed.
• Function coverage – Indicates how many functions or methods have been invoked by tests at least once.
• Module/class coverage – Shows which modules or classes were executed during testing, offering a broader view of test reach.
• Path coverage – Measures how many unique execution paths through the code have been tested, ensuring different flows and logic combinations are exercised.

Each metric offers a different perspective on what parts of your codebase are being tested, and which parts might need more attention. Combining multiple metrics can give you a well-rounded view of test coverage and guide improvements to your test suite.

Preventing test fragility

Preventing test fragility is all about writing unit tests that are resilient, independent, and easy to maintain over time. Fragile tests often break due to minor code changes, even when the actual functionality remains correct, which can reduce trust in your test suite and slow down development.

Here are some best practices to help you write more stable tests:

• Use a single strong assertion per test: This makes it easier to identify the root cause of a failure and reduces noise in test reports.
• Keep tests independent: Each test should run in isolation and not depend on the setup or outcome of another test.
• Test behavior, not implementation details: Focus on what the code should do rather than how it does it. This gives developers more freedom to refactor internal logic without constantly updating tests.
• Avoid overly specific exception checks: Relying on exact exception types can make tests brittle.

Example: Instead of asserting that a method throws IllegalArgumentException, consider asserting that an exception is thrown and that the message or error context matches the expected behavior. This way, the test won’t break if the implementation changes to use a different, but equally valid, exception like ValidationException.

By following these practices, your unit tests will be more robust, more adaptable, less prone to breaking when internal implementations shift, and easier to maintain over time.

Unit testing in CI/CD pipelines

Unit testing plays a critical role as the first line of defense in the CI/CD pipeline. It helps catch defects early, before code progresses to more advanced stages like integration, system, or acceptance testing. While unit-tested code is not deployed directly to production, running these tests continuously in CI/CD environments allows developers to spot and fix issues before they impact the broader delivery process.

Modern CI/CD tools support parallel test execution, allowing multiple unit tests to run simultaneously across environments or containers. This dramatically reduces test time and provides faster feedback during development cycles.

Incorporating unit tests into automated pipelines also ensures consistency and repeatability. Tests execute the same way across environments, which minimizes human error and increases confidence in build quality. When combined with tools for code coverage, static analysis, and test result reporting, unit testing becomes a crucial component of a comprehensive strategy to detect regressions early and maintain high software quality throughout the development lifecycle.

Why unit tests often miss the mark

Unit tests are essential for maintaining code quality, but only if they’re written thoughtfully. Poorly designed tests can create a false sense of security and significantly reduce the overall effectiveness of your testing efforts.

Here are some common pitfalls that cause unit tests to fall short:

• False positives and false negatives: A false positive occurs when a test passes even though a bug is present. A false negative, on the other hand, means the test fails due to an unrelated or unexpected issue. Both increase debugging time and erode trust in the test suite.
• Superficial or redundant coverage: High test coverage doesn’t always mean meaningful coverage. If tests only confirm that functions were executed but don’t verify outcomes or behaviors, they offer little practical value.
• Over-reliance on internal implementation: Tightly coupling tests to the internal structure of the code makes them fragile. Even minor refactors can cause tests to break, despite the functionality still being correct.
• Lack of real-world scenarios: Testing only for basic functionality can leave your code vulnerable to unexpected inputs or edge cases. Without realistic scenarios, important issues might go undetected until later stages—or even in production.

Avoiding these mistakes helps ensure that your unit tests provide accurate feedback, improve reliability, and contribute real value to your overall quality strategy.

Unit test writing best practices

If your goal is to create unit tests that are meaningful, maintainable, and reliable, following a few proven best practices can make a big difference. Well-structured tests improve coverage, simplify debugging, reduce false positives and negatives, and enhance the effectiveness and scalability of your testing in CI/CD pipelines.

Here are four core best practices to keep in mind:

1. Focus on small, isolated units of code

Each unit test should target a single method or function, and it should be isolated from other parts of the system. Avoid combining multiple interactions or components in the same test.

Why it matters:

Isolated tests improve reliability, reduce dependencies, and make it easier to trace the source of failures.

How to do it:

Keep the logic in each test simple and focused. Use mocks or stubs to simulate external dependencies so the test only verifies the behavior of the unit itself, not the components around it.

2. Prioritize readability and maintainability

Write tests that are easy to read, understand, and update. Use clear, descriptive naming conventions and add comments where necessary, especially when the test logic involves edge cases or complex behavior. This makes tests more accessible, even to non-technical collaborators like product owners or business analysts.

Why it matters:

When test logic becomes too complex or unclear, it slows down debugging and collaboration. Readable tests save time and make it easier for anyone reviewing or updating them to understand their intent.

How to do it:

Be consistent with naming conventions. A helpful pattern is:

FunctionName_StateUnderTest_ExpectedBehavior

Example: CalculateTax_NegativeIncome_ThrowsException

This approach communicates exactly what’s being tested and under what conditions, making your test suite easier to navigate and maintain over time.

3. Test For Behavior, Not Implementation

Unit tests should focus on verifying a function’s observable behavior and outputs, rather than its internal logic or how it’s implemented. This approach helps ensure that your tests stay stable even when the underlying code structure changes.

Why it matters:

When you test for behavior instead of implementation, your tests become less brittle and easier to maintain. Developers have more flexibility to refactor code without needing to constantly rewrite test logic.

Involving the QA team early in the unit testing process can also improve test quality. While QA engineers typically don’t refactor code, they can contribute during code review sessions, clarify test intent, and highlight edge cases or real-world usage scenarios that may not be obvious to developers.

How to do it:

Avoid writing tests that rely on internal steps or intermediate states. Instead, validate the input-output relationship: Given specific inputs, does the function return the expected result?

This behavior-first approach aligns well with behavior-driven development (BDD) principles and keeps test logic focused on what matters to users and stakeholders.

4. Write Tests That Fail for The Right Reasons

A passing test doesn’t always mean your code is correct, especially if the test isn’t validating the right behavior. Well-written unit tests should only fail when there’s a genuine issue with the specific functionality being tested. If a test fails for unrelated reasons or if a faulty test still passes, it can lead to confusion and false confidence in your code.

Why it matters:

Precise, intentional test failures make debugging faster and more effective. They help confirm that your tests are meaningful and reduce the risk of false positives.

How to do it:

Focus each test case on a single, specific behavior. Use clear and consistent assertions with informative error messages so failures are easy to trace. This ensures your tests provide reliable, actionable feedback when something breaks.

Writing better unit tests with TestRail

Developers play a key role in driving software quality by writing meaningful unit tests. It starts with identifying the purpose of each unit, choosing the right testing framework, and writing focused, maintainable test cases. But managing and tracking those tests effectively is just as important—and that’s where a test management solution like TestRail adds value.

TestRail provides features like intuitive test case organization, flexible test plans, and fast test execution tracking. It integrates with your toolchain, including:

• Issue trackers like Azure DevOps and JIRA
• CI/CD tools like GitLab CI, GitHub Actions, and Jenkins
• Test automation frameworks like Cypress, Playwright, and Selenium

For unit testing specifically, the TestRail Command Line Interface (TRCLI) enables teams to automate the upload of test results directly into TestRail. This makes it easy to:

• Track unit test results in real time
• Consolidate testing insights across the pipeline
• Link unit tests to larger test plans and requirements for full traceability

TestRail helps organizations improve visibility, enhance collaboration, and deliver higher-quality software with confidence. Ready to take your unit testing to the next level? Start your free 30-day trial today!