JUnit assertLinesMatch Method

The assertLinesMatch method in JUnit is used to assert that two lists or streams of strings are equal. JUnit provides several overloaded versions of this method to handle different scenarios and to provide custom messages for test failures. This guide covers the basics of using the assertLinesMatch method, including its syntax and examples of its different overloads.

Table of Contents

1. Introduction
2. assertLinesMatch Method Syntax
3. Examples
   • Basic Usage
   • Using a Custom Message
   • Using a Message Supplier
4. Real-World Use Case
5. Conclusion

Introduction

The assertLinesMatch method in JUnit is an assertion method used to verify that two lists or streams of strings match. This method is particularly useful for comparing multi-line strings or files line by line. If the lists or streams do not match, the assertion fails, and the test is marked as failed.

assertLinesMatch Method Syntax

Here is the basic syntax of the assertLinesMatch method with its different overloads:

For Lists

// Asserts that the supplied lists of strings match
static void assertLinesMatch(List<String> expectedLines, List<String> actualLines);

// Asserts that the supplied lists of strings match with a custom message
static void assertLinesMatch(List<String> expectedLines, List<String> actualLines, String message);

// Asserts that the supplied lists of strings match with a custom message supplier
static void assertLinesMatch(List<String> expectedLines, List<String> actualLines, Supplier<String> messageSupplier);

For Streams

// Asserts that the supplied streams of strings match
static void assertLinesMatch(Stream<String> expectedLines, Stream<String> actualLines);

// Asserts that the supplied streams of strings match with a custom message
static void assertLinesMatch(Stream<String> expectedLines, Stream<String> actualLines, String message);

// Asserts that the supplied streams of strings match with a custom message supplier
static void assertLinesMatch(Stream<String> expectedLines, Stream<String> actualLines, Supplier<String> messageSupplier);

Parameters:

• expectedLines: The expected list or stream of strings.
• actualLines: The actual list or stream of strings produced by the code.
• message: Optional. A custom message to display if the assertion fails.
• messageSupplier: Optional. A supplier that provides a custom message to display if the assertion fails.

Returns:

• Nothing. The method throws an assertion error if the lists or streams do not match.

Examples

Basic Usage

Compare two lists of strings to ensure they match.

Example

import static org.junit.jupiter.api.Assertions.assertLinesMatch;
import org.junit.jupiter.api.Test;
import java.util.List;
import java.util.Arrays;

public class LinesMatchTest {
    @Test
    void testLinesMatch() {
        List<String> expectedLines = Arrays.asList("Line 1", "Line 2", "Line 3");
        List<String> actualLines = Arrays.asList("Line 1", "Line 2", "Line 3");
        assertLinesMatch(expectedLines, actualLines);
    }
}

Using a Custom Message

Include a custom message to display if the assertion fails.

Example

import static org.junit.jupiter.api.Assertions.assertLinesMatch;
import org.junit.jupiter.api.Test;
import java.util.List;
import java.util.Arrays;

public class CustomMessageTest {
    @Test
    void testLinesMatchWithMessage() {
        List<String> expectedLines = Arrays.asList("Line 1", "Line 2", "Line 3");
        List<String> actualLines = Arrays.asList("Line 1", "Line 2", "Line 4");
        assertLinesMatch(expectedLines, actualLines, "The lines should match");
    }
}

Using a Message Supplier

Use a message supplier to lazily generate a custom message if the assertion fails.

Example

import static org.junit.jupiter.api.Assertions.assertLinesMatch;
import org.junit.jupiter.api.Test;
import java.util.List;
import java.util.Arrays;
import java.util.function.Supplier;

public class MessageSupplierTest {
    @Test
    void testLinesMatchWithMessageSupplier() {
        List<String> expectedLines = Arrays.asList("Line 1", "Line 2", "Line 3");
        List<String> actualLines = Arrays.asList("Line 1", "Line 2", "Line 4");
        Supplier<String> messageSupplier = () -> "The lines should match";
        assertLinesMatch(expectedLines, actualLines, messageSupplier);
    }
}

Using Streams

Compare two streams of strings to ensure they match.

Example

import static org.junit.jupiter.api.Assertions.assertLinesMatch;
import org.junit.jupiter.api.Test;
import java.util.stream.Stream;

public class StreamLinesMatchTest {
    @Test
    void testStreamLinesMatch() {
        Stream<String> expectedLines = Stream.of("Line 1", "Line 2", "Line 3");
        Stream<String> actualLines = Stream.of("Line 1", "Line 2", "Line 3");
        assertLinesMatch(expectedLines, actualLines);
    }
}

Real-World Use Case

Testing a FileService Class

A common use case for assertLinesMatch is testing methods that return or process multi-line strings in a FileService class. For example, verifying that the method correctly reads or writes the contents of a file.

Class Under Test – FileService

import java.util.List;
import java.util.Arrays;
import java.util.stream.Collectors;
import java.util.stream.Stream;

public class FileService {
    public List<String> readFile() {
        return Arrays.asList("Line 1", "Line 2", "Line 3");
    }
    
    public Stream<String> readFileAsStream() {
        return Stream.of("Line 1", "Line 2", "Line 3");
    }
}

Test Class – FileServiceTest

import static org.junit.jupiter.api.Assertions.assertLinesMatch;
import org.junit.jupiter.api.Test;
import java.util.stream.Collectors;
import java.util.stream.Stream;

public class FileServiceTest {
    private final FileService fileService = new FileService();

    @Test
    void testReadFile() {
        List<String> expectedLines = Arrays.asList("Line 1", "Line 2", "Line 3");
        List<String> actualLines = fileService.readFile();
        assertLinesMatch(expectedLines, actualLines, "The file contents should match the expected lines");
    }

    @Test
    void testReadFileAsStream() {
        Stream<String> expectedLines = Stream.of("Line 1", "Line 2", "Line 3");
        Stream<String> actualLines = fileService.readFileAsStream();
        assertLinesMatch(expectedLines, actualLines, "The file contents should match the expected lines");
    }
}

In this example, the FileServiceTest class tests the readFile and readFileAsStream methods of the FileService class using assertLinesMatch. It includes tests to ensure that the methods return the correct lines from the file.

Conclusion

The assertLinesMatch method in JUnit is used for verifying that two lists or streams of strings match in your tests. By using assertLinesMatch and its various overloads, you can compare multi-line strings or files line by line and provide custom messages for test failures. Understanding and using the assertLinesMatch method effectively is crucial for developing robust and maintainable Java applications.