Serdar Kuzucu

Drawing an Arrow with Pillow

Sun, 20 Jul 2025 12:00:00 +0000

While writing my previous blog post, I created the visuals I needed using the Pillow library inside a Jupyter notebook. The hardest part was drawing an arrow between two points with a fixed thickness, different colors for its fill and outline, and a triangle tip whose size I could control. Because of that, I wanted to share the math behind this in a separate post, along with the Python code.

First, let’s write a function that calculates the math behind this arrow independently from the Pillow library. As shown in the image below, the arrow we’ll draw consists of 7 points. In most drawing libraries, a polygon is simply defined by a list of points in the right order. Each point is represented by an (x, y) coordinate pair. So, in the end, our function should return 7 such points, each containing two numbers: x and y.

In the image above, I marked these points with red circles and numbered them. The numbers follow the order in which the points will appear in the polygon list, to avoid any confusion.

You’ve probably noticed that the polygon is made up of a rectangle and a triangle. Not every arrow has to be like this, but to keep things simple, we’ll stick to this structure for now. Later, we can extend the function to support different inner angles if needed.

Let’s define our function with the following signature:

def calculate_arrow_polygon(
    x1: float,
    y1: float,
    x2: float,
    y2: float,
    arrowhead_height: int,
    tail_thickness: int,
) -> tuple[tuple[float, float], ...]:
    """
    Calculates the 7-point polygon representing an arrow with a rectangular tail
    and equilateral triangle head.

    Args:
        x1: Tail center x-coordinate.
        y1: Tail center y-coordinate.
        x2: Arrow tip x-coordinate.
        y2: Arrow tip y-coordinate.
        arrowhead_height: Height of the equilateral triangle arrowhead.
        tail_thickness: Width of the rectangular tail.

    Returns:
        A tuple of 7 (x, y) points forming the arrow polygon.
    """

Points 1, 2, 3, and 7 in the image belong to the rectangle. Points 4, 5, and 6 belong to the triangle.

The x1, y1 parameters given to the function by the user will correspond to the center point of the tail end of the arrow i.e., the midpoint between points 1 and 2. Therefore, we can calculate points 1 and 2 using a bit of trigonometry, centered around the point (x1, y1).

The (x2, y2) point directly corresponds to point 5 in the image, which is the tip of the arrow.

Let’s begin the calculations. To do that, we first need to understand what a unit vector is and why it’s essential in our case.

Unit Vector

A unit vector is a vector with a length (or magnitude) of exactly 1. It represents only a direction, without any scaling. In our scenario, we use a unit vector to describe the direction from the tail of the arrow (centered at point (x1, y1)) toward the arrowhead (point (x2, y2)). By converting this direction into a unit vector, we ensure that any further operations like scaling or rotation are based solely on direction and not on distance.

We also calculate a perpendicular unit vector; a unit vector that is rotated 90 degrees from the original direction vector. This perpendicular vector is essential because we use it to shift points left and right from the center line of the arrow to define the rectangle’s width (i.e., to find points 1, 2, 3, and 7). Without the perpendicular direction, we wouldn’t be able to define the sides of the arrow shaft.

In summary:

The unit vector gives us the direction along the arrow.
The perpendicular unit vector gives us the direction across the arrow (left/right). Both are crucial to accurately position the corners of the rectangle and the triangle using trigonometric offsets.

Here is the Python code to compute both the unit vector (direction of the arrow) and the perpendicular unit vector (used to offset left/right), with explanations in the comments:

import math

def unit_vector(x1: float, y1: float, x2: float, y2: float) -> tuple[float, float]:
    """Compute the unit vector from point (x1, y1) to point (x2, y2).

    Args:
        x1 (float): X-coordinate of the starting point.
        y1 (float): Y-coordinate of the starting point.
        x2 (float): X-coordinate of the ending point.
        y2 (float): Y-coordinate of the ending point.

    Returns:
        tuple[float, float]: Unit vector (ux, uy) in the direction from (x1, y1) to (x2, y2).
    """
    # Step 1: Compute the direction vector from tail (x1, y1) to tip (x2, y2)
    dx = x2 - x1
    dy = y2 - y1

    # Step 2: Compute the length (magnitude) of this vector
    length = math.hypot(dx, dy)  # Equivalent to sqrt(dx**2 + dy**2)

    # Step 3: Normalize the direction vector to get the unit vector
    ux = dx / length
    uy = dy / length

    # Step 4: Return the unit vector as a tuple
    return ux, uy

def perpendicular_vector(ux: float, uy: float) -> tuple[float, float]:
    """Compute the vector perpendicular to a given unit vector, rotated 90 degrees counterclockwise.

    Args:
        ux (float): X-component of the unit vector.
        uy (float): Y-component of the unit vector.

    Returns:
        tuple[float, float]: Perpendicular unit vector (-uy, ux).
    """

    # Rotating the direction vector 90 degrees counterclockwise:
    # (ux, uy) --> (-uy, ux)
    return -uy, ux

From Vectors to Arrow Geometry

Now that we have both the direction unit vector (which we’ll call ux, uy) and the perpendicular unit vector (px, py), we can begin to calculate the seven points that form our arrow. Every point will be derived by starting from a center position (like the midpoint of the tail or the base of the arrowhead), and then moving either along the arrow direction (using ux, uy) or across the arrow (using px, py).

Let’s break it down:

The tail rectangle has two long sides. We find these by shifting the tail midpoint (x1, y1) left and right using the perpendicular vector (px, py) scaled by half the tail thickness.
The base of the arrowhead is placed arrowhead_height units behind the arrow tip, by moving backwards along (ux, uy).
The triangle head is an equilateral triangle, so we can compute its width based on its height using the formula for an equilateral triangle: half_base = height / sqrt(3)
The triangle base corners (points 4 and 6) are computed by shifting left and right from the arrowhead base center using px, py.

By combining these geometric translations, we can locate all seven points of the arrow.

Final Code

Now that we’ve explored the vector math, understood how to shift points along and across the arrow, and seen how to compute the tail and arrowhead dimensions, it’s time to assemble everything into two functions.

import math
from PIL import Image, ImageDraw


def calculate_arrow_polygon(
    x1: float,
    y1: float,
    x2: float,
    y2: float,
    arrowhead_height: int,
    tail_thickness: int,
) -> tuple[tuple[int, int], ...]:
    """
    Calculates the 7-point polygon representing an arrow with a rectangular tail
    and equilateral triangle head.

    Args:
        x1: Tail center x-coordinate.
        y1: Tail center y-coordinate.
        x2: Arrow tip x-coordinate.
        y2: Arrow tip y-coordinate.
        arrowhead_height: Height of the equilateral triangle arrowhead.
        tail_thickness: Width of the rectangular tail.

    Returns:
        A tuple of 7 (x, y) points forming the arrow polygon.
    """
    # Step 1: Get unit direction vector and perpendicular vector
    ux, uy = unit_vector(x1, y1, x2, y2)
    px, py = perpendicular_vector(ux, uy)

    # Step 2: Base of the triangle is arrowhead_height units back from tip
    # This is also the middle point of rectangle's side touching the triangle
    base_cx = x2 - arrowhead_height * ux
    base_cy = y2 - arrowhead_height * uy

    # Step 3: Calculate Triangle base width
    # h = √3/2 * a --> a = 2*h/√3 --> a/2 = h/√3
    tri_base_half_width = arrowhead_height / math.sqrt(3)

    # Step 4: Tail rectangle corners: points 1 and 2
    tail_half = tail_thickness / 2
    p1 = (x1 + px * tail_half, y1 + py * tail_half)
    p2 = (x1 - px * tail_half, y1 - py * tail_half)

    # Step 5: Tail rectangle corners: points 3 and 7
    # We calculate them from the middle point between those two points that is also
    # the mid-point of the triangle's base.
    p3 = (base_cx - px * tail_half, base_cy - py * tail_half)
    p7 = (base_cx + px * tail_half, base_cy + py * tail_half)

    # Step 6: Triangle base points
    p4 = (base_cx - px * tri_base_half_width, base_cy - py * tri_base_half_width)
    p6 = (base_cx + px * tri_base_half_width, base_cy + py * tri_base_half_width)

    # Point 5 is just the user input
    p5 = (x2, y2)

    # Step 7: Convert points from float to int and return the polygon
    return tuple(map(
        lambda p: (int(round(p[0])), int(round(p[1]))),
        [p1, p2, p3, p4, p5, p6, p7],
    ))


def draw_arrow(
    canvas: Image.Image,
    x1: int, 
    y1: int, 
    x2: int, 
    y2: int, 
    outline_thickness: int = 3, 
    arrowhead_height: int = 10, 
    tail_thickness: int = 8,
    outline_color: tuple[int, int, int] = (0, 0, 0),
    fill_color: tuple[int, int, int] = (255, 255, 255),
) -> None:
    """
    Draws a filled, outlined arrow from (x1, y1) to (x2, y2) on the given image.

    Args:
        canvas: The target PIL image to draw on.
        x1, y1: Tail center coordinates.
        x2, y2: Arrow tip coordinates.
        outline_thickness: Outline width in pixels.
        arrowhead_height: Height of the equilateral triangle head.
        tail_thickness: Width of the tail rectangle.
        outline_color: RGB color of the outline.
        fill_color: RGB color of the inside fill.
    """
    polygon = calculate_arrow_polygon(x1, y1, x2, y2, arrowhead_height, tail_thickness)
    draw = ImageDraw.Draw(canvas)
    draw.polygon(polygon, fill=fill_color, outline=outline_color, width=outline_thickness)

Here is a quick and dirty code showing how we can test the above functions in a jupyter notebook using matplotlib:

from PIL import Image, ImageDraw
import matplotlib.pyplot as plt


# Create a blank white image
width, height = 300, 300
img = Image.new("RGB", (width, height), (255, 255, 255))

# Example arrow parameters
x1, y1 = 250, 190   # Tail center
x2, y2 = 50, 150  # Arrow tip
arrowhead_height = 100
tail_thickness = 30
outline_thickness = 6
outline_color = (0, 0, 0)
fill_color = (100, 200, 255)

# Draw the arrow
draw_arrow(
    canvas=img,
    x1=x1, y1=y1, x2=x2, y2=y2,
    outline_thickness=outline_thickness,
    arrowhead_height=arrowhead_height,
    tail_thickness=tail_thickness,
    outline_color=outline_color,
    fill_color=fill_color,
)

# Display using matplotlib inline
plt.figure(figsize=(5, 5))
plt.imshow(img)
plt.axis('off')
plt.title("Test Arrow")
plt.show()

Closing Words

I’ll admit, this isn’t exactly groundbreaking stuff. But for some reason, not sharing it was bothering me enough to keep me up at night. I went down quite the rabbit hole trying to get a clean arrow shape using vector math and ChatGPT. After spending that much time, it felt like a waste not to write it up and share it.

If you’ve made it all the way here, thanks for reading. Hope it was at least a little useful or at the very least, entertaining. Take care and see you in the next weirdly specific problem.

Implementing the Simulation with Pygame

Sun, 23 Mar 2025 00:09:00 +0000

Welcome to the 4th post in the “Simulating Shortest Path in a Binary Matrix using Pygame” series! So far, we’ve explored the problem, implemented BFS, and designed a multi-stage simulation. Now, it’s time to bring it all to life! In this post, we’ll dive into the Pygame implementation and create an interactive visualization of the algorithm. You’ll see walls, paths, and visited nodes animate on screen, watch BFS explore the grid step by step, and even handle success or failure scenarios. Whether you’re here for the algorithms, the visuals, or just the fun of coding, this post will turn our simulation into a reality. Let’s get started!

Let’s Code It!

Sections below will show the classes and functions, but skip imports. I will post the complete code to GitHub and share links to the actual code under each section.

`sprites.py`

The sprites.py file defines various Pygame sprite classes and helper functions for rendering different elements in the simulation. Let’s go one by one.

Helper Functions:

def create_wall(cell_size: int = CELL_SIZE, padding: int = 2) -> pygame.Surface:
    """Creates a surface representing a wall cell.

    Args:
        cell_size (int): The size of the cell in pixels.
        padding (int): The padding inside the cell to adjust the wall appearance.

    Returns:
        pygame.Surface: A surface with a dark red rectangle representing a wall.
    """
    # Create a transparent surface of the given cell size
    surface = pygame.Surface((cell_size, cell_size), pygame.SRCALPHA).convert_alpha()
    
    # Draw a dark red rectangle with padding to make the wall visually distinct
    pygame.draw.rect(
        surface,
        DARK_RED,  # Fill color
        (
            padding,  # X position of the rectangle within the `surface`
            padding,  # Y position of the rectangle within the `surface`
            cell_size - 2 * padding,  # Width of the rectangle
            cell_size - 2 * padding,  # Height of the rectangle
        ),
    )
    return surface


def create_circle(
    fill_color: tuple[int, int, int],
    border_color: tuple[int, int, int] = BLACK,
    cell_size: int = CELL_SIZE,
    padding: int = 1,
    border_width: int = 1,
) -> None:
    """Creates a circular surface with a border.

    Args:
        fill_color (tuple[int, int, int]): RGB color of the inner circle.
        border_color (tuple[int, int, int]): RGB color of the outer border.
        cell_size (int): The size of the cell in pixels.
        padding (int): Space between the circle and the edge of the surface.
        border_width (int): Thickness of the border.

    Returns:
        pygame.Surface: A surface containing a circle with the given properties.
    """
    # Create a transparent surface of the given cell size
    surface = pygame.Surface((cell_size, cell_size), pygame.SRCALPHA).convert_alpha()
    
    # Calculate center coordinates
    center_x = cell_size // 2
    center_y = cell_size // 2
    
    # Calculate the outer and inner radii
    outer_radius = cell_size // 2 - 2 * padding
    inner_radius = outer_radius - 2 * border_width
    
    # Draw the outer circle (border)
    pygame.draw.circle(surface, border_color, (center_x, center_y), outer_radius)
    
    # Draw the inner circle (fill)
    pygame.draw.circle(surface, fill_color, (center_x, center_y), inner_radius)
    return surface


@cache
def get_cell_surfaces() -> dict[CellType, pygame.Surface]:
    """Pre-renders and caches surfaces for different cell types.

    Returns:
        dict[CellType, pygame.Surface]: A dictionary mapping cell types to 
        their corresponding pre-rendered surfaces.
    """
    surfaces = {
        "wall": create_wall(),  # Surface for wall cells
        "unvisited": create_circle(GRAY),  # Surface for unvisited cells
        "visited": create_circle(BLUE),  # Surface for visited cells
        "final_path": create_circle(GREEN),  # Surface for the shortest path
    }
    return surfaces

CellSprite represents a single cell in the grid-based simulation, extending pygame.sprite.Sprite to integrate with Pygame’s rendering and update system. Each cell has an (x, y) position in the grid and a cell_type that determines its appearance, such as “wall,” “visited,” or “final_path.” The class preloads surfaces for different cell types using get_cell_surfaces() to optimize rendering. It also includes a method, update_type(), which allows the cell’s appearance to be updated dynamically based on state changes during the simulation. By managing its own graphical representation and position, CellSprite enables efficient visual updates in the Pygame environment.

class CellSprite(pygame.sprite.Sprite):
    """Represents a grid cell in the simulation as a Pygame sprite.

    Attributes:
        x (int): The x-coordinate of the cell in the grid.
        y (int): The y-coordinate of the cell in the grid.
        cell_type (CellType): The type of the cell (e.g., wall, visited, etc.).
        image (pygame.Surface): The visual representation of the cell.
        rect (pygame.Rect): The rectangle defining the cell's position.
    """

    def __init__(
        self,
        x: int,
        y: int,
        cell_type: CellType,
    ):
        """Initializes a CellSprite with position and type.

        Args:
            x (int): The x-coordinate of the cell in the grid.
            y (int): The y-coordinate of the cell in the grid.
            cell_type (CellType): The type of the cell (determines appearance).
        """
        super().__init__()
        self.x = x
        self.y = y
        self.cell_type = cell_type
        self.image = get_cell_surfaces()[self.cell_type]  # Assign the corresponding surface
        self.rect = self.image.get_rect(topleft=(x * CELL_SIZE, y * CELL_SIZE))  # Position in grid

    def update_type(self, cell_type: CellType):
        """Updates the cell's type and refreshes its appearance.

        Args:
            cell_type (CellType): The new type of the cell.
        """
        self.cell_type = cell_type
        self.image = get_cell_surfaces()[self.cell_type]  # Update surface based on new type

The LineSprite class represents a visual line connecting two points on a grid, typically used for illustrating paths or connections between cells. It inherits from pygame.sprite.Sprite, allowing it to be part of Pygame’s sprite system. The sprite is initialized with two grid coordinates, a customizable line width, and a color. The line is drawn on a surface, with its dimensions calculated based on the distance between the two points. Special handling is applied to diagonal lines, increasing their width for better visibility. The sprite’s rect is adjusted to position the line properly within the grid, ensuring it aligns with the grid’s structure.

class LineSprite(pygame.sprite.Sprite):
    """Represents a line connecting two points in the grid.

    This sprite is used to visually represent paths or connections between cells
    in the grid-based simulation. It supports drawing both straight and diagonal
    lines with configurable width and color.

    Attributes:
        image (pygame.Surface): The surface containing the drawn line.
        rect (pygame.Rect): The rectangular area occupied by the line.
    """

    def __init__(
        self,
        from_point: tuple[int, int],
        to_point: tuple[int, int],
        line_width: int = THIN_LINE_WIDTH,
        color: tuple[int, int, int] = RED,
    ):
        """Initializes a LineSprite connecting two grid points.

        Args:
            from_point (tuple[int, int]): The starting point (grid coordinates).
            to_point (tuple[int, int]): The ending point (grid coordinates).
            line_width (int, optional): The width of the line. Defaults to THIN_LINE_WIDTH.
            color (tuple[int, int, int], optional): The color of the line. Defaults to RED.
        """
        super().__init__()

        # Convert grid coordinates to pixel coordinates.
        x1, y1, x2, y2 = (p * CELL_SIZE for p in (*from_point, *to_point))
        
        # Calculate the required surface dimensions to fit the line.
        width, height = abs(x1 - x2) + CELL_SIZE, abs(y1 - y2) + CELL_SIZE

        # Create a transparent surface to draw the line on.
        self.image = pygame.Surface((width, height), pygame.SRCALPHA).convert_alpha()
        self.rect = self.image.get_rect(topleft=(min(x1, x2), min(y1, y2)))

        # Adjust line width for diagonal lines to make them more visible.
        if x1 != x2 and y1 != y2:
            line_width = int(line_width * 1.5)

        # Center the line within the grid cell.
        shift_by_x = CELL_SIZE // 2 - self.rect.left
        shift_by_y = CELL_SIZE // 2 - self.rect.top

        # Draw the line from the starting point to the ending point.
        pygame.draw.line(
            self.image,
            color,
            (x1 + shift_by_x, y1 + shift_by_y),
            (x2 + shift_by_x, y2 + shift_by_y),
            line_width,
        )

The TextSprite class is a simple way to display text in a game. The class renders a given text string in a specified font size and color. It creates a surface and pre-renders the text during initialization. This makes it efficient to repeatedly redraw at each frame.

class TextSprite(pygame.sprite.Sprite):
    """
    A sprite class for rendering and displaying text in a Pygame game.

    This class is used to create a text element that can be added to the 
    Pygame sprite system for rendering.

    Attributes:
        image (pygame.Surface): The surface containing the rendered text.
        rect (pygame.Rect): The rectangle that defines the boundaries of the text.
    """

    def __init__(self, text: str, font_size: int, color: tuple[int, int, int]):
        """
        Initialize the TextSprite object.

        Args:
            text (str): The text string to display in the sprite.
            font_size (int): The font size for rendering the text.
            color (tuple[int, int, int]): The color of the text in RGB format.
        """
        super().__init__()

        # Create a font object with the specified font size.
        font = pygame.font.Font(None, font_size)

        # Render the text with the specified color and store it in the 'image' attribute.
        self.image = font.render(text, True, color)

        # Get the rectangle for the rendered text to define its position and size.
        self.rect = self.image.get_rect()

The OverlaySprite class is used to create semi-transparent overlays on the game screen. It allows setting a custom width, height, color, and transparency level (alpha). The overlay is drawn as a surface with the given dimensions and then filled with the specified color and transparency. This class is useful for adding visual effects or background elements without obscuring the content behind it.

class OverlaySprite(pygame.sprite.Sprite):
    """
    A sprite that creates a semi-transparent overlay for the game screen.
    
    This class creates an overlay that can be used for effects such as modal dialogs,
    backgrounds for text, or to create visual focus. The overlay is customizable in terms of size, 
    color, and transparency (alpha value).

    Attributes:
        image (pygame.Surface): The surface representing the overlay sprite.
        rect (pygame.Rect): The rectangle used for positioning the overlay sprite.
    """
    
    def __init__(self, width: int, height: int, color=(128, 128, 128), alpha=200):
        """
        Initialize the OverlaySprite with the given width, height, color, and alpha.
        
        Args:
            width (int): The width of the overlay.
            height (int): The height of the overlay.
            color (tuple[int, int, int]): The RGB color of the overlay (default is gray).
            alpha (int): The transparency of the overlay (default is 200).
        """
        super().__init__()

        # Create a new surface with the given width and height and transparent background
        self.image = pygame.Surface((width, height), pygame.SRCALPHA)
        
        # Fill the surface with the specified color and alpha (transparency)
        self.image.fill((*color, alpha))
        
        # Set the rect attribute for positioning the sprite
        self.rect = self.image.get_rect()

`game.py`

The game.py file is responsible for managing the core structure and flow of the game. It defines the main game loop, handles user input through event handling, updates the game state, and renders the game scene to the screen. This file also handles transitions between different game states (e.g., welcome screen, gameplay, game over), ensuring smooth navigation and gameplay experience. Essentially, it serves as the backbone of the game’s execution, coordinating all aspects of the game’s lifecycle.

class Game:
    def __init__(self):
        # Currently active state
        self.state = None
        
        # Next state to activate at the end of the game loop iteration
        self.next_state = None
        
        # Is the game running?
        self.running = False
        
        # Game's main screen; main surface to draw our game into
        self.screen = None

    def run(self):
        # Before doing anything else with pygame, it must be initialized
        pygame.init()
        
        # Define the screen and its size
        self.screen = pygame.display.set_mode(SCREEN_SIZE)
        
        # This sets the text on the title bar of the window
        pygame.display.set_caption("Shortest Path in Binary Matrix")
        
        # Update the contents of the entire display
        pygame.display.flip()

        # Clock will help us keep track of time and handle frame rate
        clock = pygame.time.Clock()
        
        # Set running to True to go into the infinite gaming loop until running is False
        self.running = True
        
        # Initialise the InitState: entrance scene for the game
        from leetcode.bfs_shortest_path.states import InitState
        self.state = InitState(self)

        # Start the gaming loop; run the code until running=False
        while self.running:
            # We do two things here: first, ask clock to update and regulate the frame rate,
            # then we calculate the deltaTime (elapsed time) in seconds.
            #
            # clock.tick(FPS) ensures that the game runs at the specified FPS (frames per second),
            # by limiting the number of frames that can be drawn within a given time.
            #
            # The resulting delta_time is the time in seconds between the current frame and the previous frame.
            # This value can be used for frame rate-independent movement or other time-dependent operations.
            # Dividing by 1000 converts the result from milliseconds to seconds, 
            # which is a standard unit of time for physics simulations.
            #
            # The value of delta_time can be used for smooth animations, physics calculations, or any other task
            # that requires time-based adjustments that are not dependent on the actual frame rate.
            delta_time = clock.tick(FPS) / 1000  # deltaTime in seconds
            print("FPS: ", clock.get_fps(), "Delta time: ", delta_time)

            # Game loops typically have 3 main actions: handling events, updating game state, and rendering.
            # Handle input events (e.g., keyboard, mouse) and game logic changes.
            self.handle_events()
            
            # Update the current game state based on the elapsed time (delta_time),
            # ensuring frame rate independence for physics, movements, or logic.
            self.state.update(delta_time)
            
            # Render the updated state to the screen (draw the updated visuals or objects).
            self.state.render()

            # Flip the display buffers to update the screen with the new frame.
            # This is typically used in double-buffered rendering to prevent flickering.
            pygame.display.flip()

            # Check if there is a state change request pending.
            if self.next_state is not None:
                # Transition to the new state by updating the current state.
                self.state = self.next_state
                
                # Reset the next_state to None, clearing the transition request.
                self.next_state = None

        # Quit the game, terminates the window. We need to call this when the game loop ends.
        # Otherwise, the window stays open.
        pygame.quit()

    def handle_events(self):
        # Initialize an empty list to store the events to be processed.
        events = []
        
        # Loop through all events in the event queue.
        for event in pygame.event.get():
            # If the event is a quit event (e.g., closing the window).
            if event.type == pygame.QUIT:
                # Set the running flag to False to stop the game loop.
                self.running = False
                # Exit the method immediately to stop handling further events.
                return
            else:
                # Add all other events to the events list for further processing.
                events.append(event)
        
        # Pass the collected events to the current game state's handle_events method for processing.
        self.state.handle_events(events)


if __name__ == "__main__":
    # Create an instance of the Game class, initializing the game object.
    game = Game()
    
    # Call the run method to start the game loop and begin game execution.
    game.run()

`states.py`

GameState is an abstract base class (ABC) that defines the structure for different game states in the simulation. It provides three methods — handle_events, update, and render — which are meant to be overridden by subclasses. These methods define how the state handles user input, updates game logic, and renders visuals. By using this base class, the game can manage different states (e.g., initialization, simulation, completion) in a structured and consistent way.

class GameState(ABC):
    """
    Abstract base class representing the general state of the game.

    This class defines the essential methods that each game state must implement:
    - handle_events: Handles any input events (like keyboard or mouse actions).
    - update: Updates the state of the game, usually for animation or logic progression.
    - render: Renders the current state of the game on the screen.

    Inherits from ABC (Abstract Base Class) to ensure that any subclass must implement the abstract methods.
    However there are no abstract methods as of now.
    """

    def handle_events(self, events: List[pygame.event.Event]):
        """
        Handles input events for the current game state.

        Args:
            events (List[pygame.event.Event]): A list of events to process.
        """
        pass

    def update(self, delta_time: float):
        """
        Updates the game state, usually for animation or logic progression.

        Args:
            delta_time (float): The time elapsed since the last frame (in seconds).
        """
        pass

    def render(self):
        """
        Renders the current state of the game to the screen.
        """
        pass

TimelyUpdateGameState is a subclass of GameState that ensures updates occur at a fixed rate, defined by updates_per_second. Instead of updating continuously every frame, it accumulates elapsed time (delta_time) and only triggers an update when enough time has passed. The actual update logic is delegated to the perform_update method, which must be implemented by subclasses.

This is useful for managing time-sensitive logic, such as animations or physics updates, without being tied to the frame rate.

class TimelyUpdateGameState(GameState, ABC):
    """
    A subclass of GameState that handles time-based updates.

    This class adds functionality to ensure that updates to the game state 
    occur at a consistent rate, based on the specified updates per second 
    (FPS). It ensures that updates are triggered only after the specified 
    amount of time has passed.

    Args:
        game (Game): The game instance to which the state belongs.
        updates_per_second (float | int): The number of updates to be performed per second.
    """

    def __init__(self, game: Game, updates_per_second: float | int):
        """
        Initializes the state with the game instance and updates per second.

        Args:
            game (Game): The game instance to which the state belongs.
            updates_per_second (float | int): The number of updates per second for the game state.
        """
        self.game = game
        self.time_lapsed_since_last_update = 0
        self.updates_per_second = updates_per_second
        self.update_interval = 1 / updates_per_second

    def update(self, delta_time: float):
        """
        Updates the game state based on the elapsed time, ensuring that updates 
        occur at the specified rate.

        Args:
            delta_time (float): The time elapsed since the last frame (in seconds).
        """
        self.time_lapsed_since_last_update += delta_time
        if self.time_lapsed_since_last_update < self.update_interval:
            return
        self.time_lapsed_since_last_update -= self.update_interval
        self.perform_update()

    @abstractmethod
    def perform_update(self):
        """
        Performs the actual update logic for the game state. This method must 
        be implemented by any subclass.

        This method is called when the time threshold is reached for an update.
        """
        pass

The InitState class is responsible for initializing the starting screen of the game, where the user can choose how to generate the grid for the BFS simulation. It presents three options to the user: pressing the SPACE key for a random grid, ENTER for a successful path, and ESC for a failure path. The class organizes the display of these options using TextSprite objects and handles key events to transition to the next state based on the user’s input. Once an option is selected, it generates the corresponding grid and passes it to the SimulationState class to begin the BFS simulation.

class InitState(GameState):
    """
    Represents the initial state of the game, where the user can choose to start
    a random, successful, or failure path.

    In this state, the user is presented with instructions on how to proceed, 
    and their input determines the grid that will be generated for the next state.
    """

    def __init__(self, game: Game):
        """
        Initializes the InitState, which displays the initial instructions to the user.

        Args:
            game (Game): The game instance to which this state belongs.
        """
        self.game = game

        # Create text sprites to display on the screen with different instructions
        text_1 = TextSprite("Press SPACE to start randomly", 36, BLACK)
        text_2 = TextSprite("Press ENTER to start a successful path", 36, GREEN)
        text_3 = TextSprite("Press ESC to start a failure path", 36, RED)

        # Position the text sprites on the screen
        text_2.rect.center = (SCREEN_SIZE_X // 2, SCREEN_SIZE_Y // 2)
        text_1.rect.bottomleft = text_2.rect.topleft
        text_3.rect.topleft = text_2.rect.bottomleft

        # Add text sprites to the sprite group for rendering
        self.objects = pygame.sprite.Group()
        self.objects.add(text_1, text_2, text_3)

    def handle_events(self, events: List[pygame.event.Event]):
        """
        Handles input events for the InitState, where the user chooses how to proceed.

        Args:
            events (List[pygame.event.Event]): A list of events to process.
        """
        for event in events:
            if event.type == pygame.KEYUP:
                if event.key == pygame.K_SPACE:
                    # Start with a randomly generated grid
                    self._create_grid_and_navigate(GRID_SIZE, is_good=None)
                if event.key == pygame.K_KP_ENTER or event.key == pygame.K_RETURN:
                    # Start with a successful path grid
                    self._create_grid_and_navigate(GRID_SIZE, is_good=True)
                if event.key == pygame.K_ESCAPE:
                    # Start with a failure path grid
                    self._create_grid_and_navigate(GRID_SIZE, is_good=False)

    def _create_grid_and_navigate(
        self, size: int, is_good: bool | None = None
    ) -> List[List[int]]:
        """
        Creates a grid based on the chosen type (good or bad) and transitions to
        the simulation state.

        Args:
            size (int): The size of the grid.
            is_good (bool | None): Whether to create a good or bad grid. If None, 
                                   a random choice is made.

        Returns:
            List[List[int]]: The generated grid.
        """
        if is_good is None:
            is_good = random.choice([True, False])

        if is_good:
            # Generate a good grid
            grid = create_good_grid(size)
        else:
            # Generate a bad grid
            grid = create_bad_grid(size)

        # Transition to the simulation state with the generated grid
        self.game.next_state = SimulationState(
            self.game, grid=grid, start_pos=START_POS, end_pos=END_POS
        )

    def render(self):
        """
        Renders the initial state to the screen, displaying the instructions.

        This method fills the screen with a white background and draws the text
        sprites for user instructions.
        """
        screen = self.game.screen
        screen.fill(WHITE)
        self.objects.draw(screen)

The SimulationState class represents the BFS pathfinding simulation in the game. It manages the grid and its cells, keeping track of visited cells and updating the state of the game as the algorithm progresses. It initializes the grid, sets the start and end positions, and visualizes the pathfinding process with the help of sprites for cells and lines. The class is responsible for handling the BFS logic, updating the level, visiting neighboring cells, and drawing the path on the screen. If a path to the destination is found, the class reconstructs the final path with thicker lines, and transitions to a success state; otherwise, it transitions to a state indicating no path exists. Additionally, it handles user input, allowing the player to escape back to the initial state.

class SimulationState(TimelyUpdateGameState):
    """
    A game state representing the simulation of BFS pathfinding on a grid.
    """
    def __init__(
        self,
        game: Game,
        grid: List[List[int]],
        start_pos: tuple[int, int],
        end_pos: tuple[int, int],
    ):
        """
        Initializes the simulation state with the given parameters.
        
        Args:
            game (Game): The current game instance.
            grid (List[List[int]]): A 2D grid representing the game environment.
            start_pos (tuple[int, int]): The starting position for the pathfinding.
            end_pos (tuple[int, int]): The destination position for the pathfinding.
        """
        super().__init__(game, UPDATES_PER_SECOND)

        self.grid = grid
        self.grid_size = len(grid)  # Only works for square grids
        self.visited = [[False] * self.grid_size for _ in range(self.grid_size)]  # Track visited cells
        self.queue = deque([start_pos])  # Queue for BFS
        self.parents = {start_pos: None}  # Store parent of each cell for path reconstruction
        self.start_pos = start_pos
        self.end_pos = end_pos
        self.visited[start_pos[0]][start_pos[1]] = True  # Mark start position as visited
        self.cell_sprites = pygame.sprite.Group()  # Group for cell sprites
        self.line_sprites = pygame.sprite.Group()  # Group for lines representing the BFS path
        self.text_sprites = pygame.sprite.GroupSingle()  # Single group for text (level display)
        self.level = 0  # BFS level counter

        # Initialize cell sprites for the grid based on the type of each cell
        for x in range(len(self.grid)):
            for y in range(len(self.grid[x])):
                cell_type = "wall" if self.grid[x][y] == WALL else "unvisited"
                cell_sprite = CellSprite(x, y, cell_type)
                self.cell_sprites.add(cell_sprite)

        self.update_cell_type(start_pos[0], start_pos[1], "visited")

    def perform_update(self):
        """
        Perform one update step for the BFS pathfinding algorithm.
        If the queue is empty, it transitions to the next state.
        """
        if len(self.queue) == 0:
            # If the queue is empty, no path is found; transition to NoPathState
            entities = self.get_all_sprites_as_group()
            self.game.next_state = NoPathState(self.game, entities, self.level)
            return

        elements_at_level = len(self.queue)
        self.level += 1  # Increase the level (depth) of BFS

        # Process each element at the current BFS level
        for _ in range(0, elements_at_level):
            x, y = self.queue.popleft()
            if (x, y) == self.end_pos:
                # If the end position is reached, build the final path
                self.build_final_path()
                entities = self.get_all_sprites_as_group()
                # Navigate to CompletionState to display the result
                self.game.next_state = CompletionState(self.game, entities, self.level)
                return

            # Visit neighboring cells of the current position
            self.visit_neighbors(x, y)

    def visit_neighbors(self, x: int, y: int) -> None:
        """
        Visit all valid neighboring cells and update their state.
        
        Args:
            x (int): The x-coordinate of the current cell.
            y (int): The y-coordinate of the current cell.
        """
        # This function alters visited and queue
        neighbors = visit_neighbors(
            x, y, self.grid, self.grid_size, self.visited, self.queue
        )
        for neighbor in neighbors:
            self.parents[neighbor] = (x, y)  # Set parent for path reconstruction
            self.update_cell_type(neighbor[0], neighbor[1], "visited")
            self.add_line((x, y), neighbor)

    def handle_events(self, events: List[pygame.event.Event]):
        """
        Handle user input events, such as pressing the escape key to return to the initial state.
        
        Args:
            events (List[pygame.event.Event]): List of pygame events to handle.
        """
        for event in events:
            if event.type == pygame.KEYUP and event.key == pygame.K_ESCAPE:
                # Escape key pressed, go back to initial state
                self.game.next_state = InitState(self.game)
                return

    @property
    def level(self) -> int:
        """
        The current BFS level (depth).

        Returns:
            int: The current level.
        """
        return self._level

    @level.setter
    def level(self, value: int):
        """
        Set the level and update the displayed level text sprite.

        Args:
            value (int): The new level value.
        """
        self._level = value
        sprite = TextSprite(f"Current Level: {value}", 36, BLACK)
        sprite.rect.topleft = (THIN_LINE_WIDTH, self.grid_size * CELL_SIZE)
        self.text_sprites.add(sprite)

    def update_cell_type(self, x: int, y: int, cell_type: CellType) -> None:
        """
        Update the cell sprite type for the given position.
        
        Args:
            x (int): The x-coordinate of the cell.
            y (int): The y-coordinate of the cell.
            cell_type (CellType): The new cell type.
        """
        for sprite in self.cell_sprites:
            if sprite.x == x and sprite.y == y:
                sprite.update_type(cell_type)
                break

    def get_all_sprites_as_group(self) -> pygame.sprite.Group:
        """
        Get all sprites (cells, lines, text) as a pygame sprite group.

        Returns:
            pygame.sprite.Group: The group containing all sprites for rendering.
        """
        entities = pygame.sprite.Group()
        entities.add(self.cell_sprites)
        entities.add(self.line_sprites)
        return entities

    def add_line(
        self,
        from_point: tuple[int, int],
        to_point: tuple[int, int],
        line_width: int = THIN_LINE_WIDTH,
    ) -> None:
        """
        Add a line sprite between two points to represent the BFS path.

        Args:
            from_point (tuple[int, int]): The starting point of the line.
            to_point (tuple[int, int]): The ending point of the line.
            line_width (int, optional): The width of the line. Defaults to THIN_LINE_WIDTH.
        """
        line_sprite = LineSprite(from_point, to_point, line_width, RED)
        self.line_sprites.add(line_sprite)

    def build_final_path(self) -> None:
        """
        Reconstruct and display the final path from the end position to the start position.
        """
        current = self.end_pos
        self.update_cell_type(current[0], current[1], "final_path")

        # Reconstruct the path by tracing the parents
        while current != self.start_pos:
            previous = current
            current = self.parents[current]
            self.update_cell_type(current[0], current[1], "final_path")
            self.add_line(current, previous, line_width=THICK_LINE_WIDTH)

    def render(self):
        """
        Render all sprites (cells, lines, and text) to the screen.
        """
        screen = self.game.screen
        screen.fill(WHITE)

        self.cell_sprites.draw(screen)
        self.line_sprites.draw(screen)
        self.text_sprites.draw(screen)

The CompletionState represents the final state in the pathfinding simulation, indicating that a valid path has been found. It displays a message to the user showing the shortest path found and the level where it was discovered. The state also provides instructions to the player, allowing them to press the space bar to restart the simulation. This state helps conclude the simulation and provides the user with feedback on the success of the pathfinding process, offering a smooth transition to the next step in the simulation.

class CompletionState(GameState):
    """
    A game state that represents the completion of the BFS pathfinding simulation.

    This state is shown when the algorithm successfully finds a path to the destination.
    It displays the shortest path length and offers the player an option to restart the simulation.

    Attributes:
        game (Game): The game instance, used to transition between states.
        entities (pygame.sprite.Group): A group containing the text and sprite entities to be rendered.
        shortest_path (int): The length of the shortest path found during the simulation.
    """

    def __init__(self, game: Game, entities: pygame.sprite.Group, shortest_path: int):
        """
        Initializes the completion state with the game, entities, and shortest path length.

        Args:
            game (Game): The game instance, which handles the state transitions.
            entities (pygame.sprite.Group): The group of entities (sprites, text) to be displayed.
            shortest_path (int): The length of the shortest path found in the simulation.
        """
        self.game = game
        self.entities = pygame.sprite.Group()
        self.entities.add(entities)
        self.shortest_path = shortest_path

        text_1 = TextSprite(
            f"Shortest path found at level {self.shortest_path}", 32, GREEN
        )
        text_2 = TextSprite("Press space to go to the beginning", 32, BLACK)
        text_1.rect.topleft = (THIN_LINE_WIDTH, GRID_SIZE * CELL_SIZE)
        text_2.rect.topleft = text_1.rect.bottomleft
        self.entities.add(text_1, text_2)

    def handle_events(self, events: List[pygame.event.Event]):
        """
        Handles the user input events during the completion state.

        Specifically, listens for the spacebar key press to transition to the initial state.

        Args:
            events (List[pygame.event.Event]): A list of events that are checked for input.
        """
        for event in events:
            if event.type == pygame.KEYUP:
                if event.key == pygame.K_SPACE:
                    self.game.next_state = InitState(self.game)
                    return

    def render(self):
        """
        Renders the completion state to the screen, displaying the entities.

        Clears the screen and draws all entities (text and sprites) to indicate the completion
        of the pathfinding simulation.
        """
        screen = self.game.screen
        screen.fill(WHITE)
        self.entities.draw(screen)

The NoPathState is displayed when the pathfinding simulation reaches a point where no valid path is found after exploring all possible levels. It informs the user that the algorithm could not find a solution, showing the number of levels visited during the search. Similar to the CompletionState, the user can press the space bar to restart the simulation and attempt finding a path again. This state provides feedback on the failure of the algorithm and allows for a fresh start, ensuring that the user can continue experimenting with different scenarios.

class NoPathState(GameState):
    """
    A game state that represents the scenario where no path was found in the BFS pathfinding simulation.

    This state is shown when the algorithm fails to find a path after visiting a certain number of levels.
    It informs the user that no path was found and provides an option to restart the simulation.

    Attributes:
        game (Game): The game instance, used to transition between states.
        entities (pygame.sprite.OrderedUpdates): A group containing the text and sprite entities to be rendered.
        final_level (int): The number of levels visited before determining that no path was found.
    """

    def __init__(self, game: Game, entities: pygame.sprite.Group, final_level: int):
        """
        Initializes the no-path state with the game, entities, and the number of levels visited.

        Args:
            game (Game): The game instance, which handles the state transitions.
            entities (pygame.sprite.Group): The group of entities (sprites, text) to be displayed.
            final_level (int): The number of levels that were visited without finding a path.
        """
        self.game = game  # Store the game instance to facilitate state transitions
        self.entities = pygame.sprite.OrderedUpdates()  # Create an ordered sprite group for entities
        self.entities.add(entities)  # Add the provided entities (sprites, text) to the group

        # Create a text sprite to display the message about the path not being found
        text_1 = TextSprite(
            f"Shortest path not found after visiting {final_level} levels!", 32, RED
        )
        text_1.rect.topleft = (THIN_LINE_WIDTH, GRID_SIZE * CELL_SIZE)  # Position the text at the top left of the screen

        # Create another text sprite to instruct the player to press space to restart
        text_2 = TextSprite(f"Press space to go to the beginning", 32, BLACK)
        text_2.rect.topleft = text_1.rect.bottomleft  # Position this text below the first one

        # Create an overlay sprite that covers the grid area (used for background or effects)
        overlay = OverlaySprite(GRID_SIZE * CELL_SIZE, GRID_SIZE * CELL_SIZE)
        # Add the text and overlay sprites to the group of entities
        self.entities.add(text_1, text_2, overlay)

    def handle_events(self, events: List[pygame.event.Event]):
        """
        Handles the user input events during the no-path state.

        Specifically, listens for the spacebar key press to transition to the initial state.

        Args:
            events (List[pygame.event.Event]): A list of events that are checked for input.
        """
        for event in events:  # Loop through all the events to check for key presses
            if event.type == pygame.KEYUP:  # Check if a key has been released
                if event.key == pygame.K_SPACE:  # Check if the space key was pressed
                    self.game.next_state = InitState(self.game)  # Transition to the initial state

    def render(self):
        """
        Renders the no-path state to the screen, displaying the entities.

        Clears the screen and draws all entities (text and sprites) to indicate that no path was found
        in the pathfinding simulation.
        """
        screen = self.game.screen  # Get the game screen to render the state
        screen.fill(WHITE)  # Fill the screen with a white background

        self.entities.draw(screen)  # Draw all the entities (text, overlay, etc.) to the screen

`algorithm.py`

We have already seen some functions from this file in the 2nd post of this series: Solving Shortest Path in a Binary Matrix. We will add other helper functions to help our simulation create random grids.

def create_good_grid(
    size: int = 10,
    start_position: tuple[int, int] = (0, 0),
    end_position: Optional[tuple[int, int]] = None,
) -> List[List[int]]:
    """
    Creates a grid where a valid path exists from the start to the end position.

    Args:
        size (int): The size of the grid (default is 10).
        start_position (tuple[int, int]): The starting position in the grid (default is (0, 0)).
        end_position (Optional[tuple[int, int]]): The end position in the grid. If None, defaults to (size-1, size-1).

    Returns:
        List[List[int]]: A grid where the shortest path length is greater than 0 (i.e., a valid path exists).
    """
    return create_grid(
        size=size,
        start_position=start_position,
        end_position=end_position,
        predicate=lambda x: x > 0,  # Ensures a valid path exists
    )


def create_bad_grid(
    size: int = 10,
    start_position: tuple[int, int] = (0, 0),
    end_position: Optional[tuple[int, int]] = None,
) -> List[List[int]]:
    """
    Creates a grid where no valid path exists from the start to the end position.

    Args:
        size (int): The size of the grid (default is 10).
        start_position (tuple[int, int]): The starting position in the grid (default is (0, 0)).
        end_position (Optional[tuple[int, int]]): The end position in the grid. If None, defaults to (size-1, size-1).

    Returns:
        List[List[int]]: A grid where the shortest path length is -1 (i.e., no valid path exists).
    """
    return create_grid(
        size=size,
        start_position=start_position,
        end_position=end_position,
        predicate=lambda x: x == -1,  # Ensures no valid path exists
    )


def create_grid(
    size: int = 10,
    start_position: tuple[int, int] = (0, 0),
    end_position: Optional[tuple[int, int]] = None,
    predicate: Callable[[int], bool] = None,
) -> List[List[int]]:
    """
    Generates a grid based on the given size, start/end positions, and a predicate function.

    Args:
        size (int): The size of the grid (default is 10).
        start_position (tuple[int, int]): The starting position in the grid (default is (0, 0)).
        end_position (Optional[tuple[int, int]]): The end position in the grid. If None, defaults to (size-1, size-1).
        predicate (Callable[[int], bool]): A function that determines if the generated grid meets the desired condition.

    Returns:
        List[List[int]]: A grid that satisfies the predicate condition.

    Raises:
        ValueError: If the grid size is less than 3.
    """
    # Ensure the grid size is at least 3 to allow for meaningful simulation
    if size < 3:
        raise ValueError("Size must be at least 3")

    # Default end position to the bottom-right corner if not provided
    if end_position is None:
        end_position = (size - 1, size - 1)

    # Continuously generate grids until one satisfies the predicate condition
    while True:
        # Create a random grid with walls (1) and open cells (0)
        grid = [
            [random.choice([NON_WALL, WALL]) for _ in range(size)] for _ in range(size)
        ]

        # Ensure the start and end positions are open cells
        grid[start_position[0]][start_position[1]] = NON_WALL
        grid[end_position[0]][end_position[1]] = NON_WALL

        # Calculate the shortest path length using the BFS algorithm
        shortest_path_length = shortest_path(grid, start_position, end_position)

        # Return the grid if it satisfies the predicate condition
        if predicate(shortest_path_length):
            return grid

And there we have it — a fully functional BFS pathfinding simulation brought to life with Pygame! From designing sprites and managing game states to visualizing the algorithm step by step, we’ve covered the essentials of building an interactive simulation. This project not only solves the “Shortest Path in a Binary Matrix” problem but also provides a hands-on way to understand core game development concepts like game loops, frame rate independence, and scene management.

Here’s how it looks. Below, I’m sharing a GIF I created from the frames I stored during the simulation. I’ll dive into the full details of storing the frames and creating the GIF in Python in a future blog post.

Feel free to experiment with the code — try tweaking the grid size, colors, or even the algorithm itself. If you’re feeling adventurous, why not add new features like changing the grid size from initial screen or setting start/end coordinates dynamically or randomly? The possibilities are endless!

I haven’t shown all the code in this blog to keep it shorter, but you can always read it on GitHub. Here is the link: 💻 sedran/leetcode-pygame.

Whether this is the end of the series or just the beginning of another coding journey, I hope this post has inspired you to explore the intersection of algorithms and game development further. Happy coding, and may your paths always be the shortest! 🚀

Designing a Multi-Stage Simulation with Pygame

Sat, 22 Mar 2025 13:15:00 +0000

Building a simple shortest path simulation is easy, but where’s the fun in that? In this post, I explore the design of a multi-stage simulation using Pygame, where users interact with different states from setup to visualization and results. While adding complexity isn’t strictly necessary, it provides a great opportunity to learn core game development concepts like game loops, frame rate independence, and scene management. This post outlines the structure and expectations of the simulation before diving into the actual implementation.

Simulation

The simulation application will be a multi-stage application. This means the user will navigate between stages and experience different user interfaces at different times. There will be event handling, and the keyboard will play a role too! You might ask, “Was that complexity necessary?” Not at all! We are adding complexity purely to learn the Pygame library.

There’s no deep reason why I chose Pygame as my framework of choice. These days, I mostly write Python code, and I don’t want to stop using a language before building a user interface with it. This code could be much smaller if I used a different language or framework. For example, most of what I’m implementing now is handled automatically by Unity. However, I also believe that coding these basics helps me understand Unity and other full-fledged game engines better.

I am also learning Unity in parallel, and I am quite surprised when I saw how this guy called Mark created Flappy Bird in Unity in a 45-minute YouTube video. Unity will definitely be my next tool to explore. However, I can also go crazy and write Flappy Bird in Pygame although it may kill me.

Watch here: The Unity Tutorial For Complete Beginners

Expectations

Before going into the code, let’s discuss expectations from the simulation application. I am sharing the screenshots below to be able to explain it better.

1. Startup Screen

We want to present some alternative scenarios to the user. That’s why I added an empty startup screen to inform the user about how to start a simulation. All possible user choices will navigate us to the same simulation screen with different setups:

Pressing “Space” key will start a random simulation. We will not predetermine if finding a path from start position to end position is possible or not.
Pressing “Enter” will start a simulation that ends with a successful path from start to end. We will randomly create a grid and test it with our algorithm we implemented previously. We will create new grid and discard them until we find a grid with a possible solution.
Pressing “ESC” will start a simulation that ends with a failure to find a path. We will use the same brute-force grid creation logic as the success scenario.

2. Simulation Screen

This screen will take a grid and solve the problem! It will refresh the visual elements at every step of the algorithm. What we’ll do here is as follows:

Draw walls as squares and unvisited nodes as gray circles into the grid
Periodically process levels in the BFS algorithm – Do not process everything at one go, allow user to see it
Paint visited circles in blue color
Connect visited circles with a line between them and their parent circle. Parent circle is the circle who adds a child circle to the queue.
Repeat until the queue is empty, or we reach the end state.
- If we are at the end state, we navigate to the successful simulation screen
- If queue is empty, we navigate to the failed simulation screen
Current level should be visible to the user as a text at the bottom
Pressing ESC during a simulation will navigate us to the initial empty screen immediately

3. Simulation End Successfully Screen

This screen will show the same simulation view we were displaying in the above screen. It will also paint the nodes/circles that makes the shortest path in green color. Among the shortest path circles, the lines will be thicker than the other lines connecting other circles. We will show the current level with a different text. It will instruct user to use “Space” key to navigate to the initial empty screen for starting over.

4. Simulation Failed Screen

This is a very similar screen to the successful end screen. It will have a different text while it displays the current level. It will show the same grid, but it will add a semi-transparent overlay on top of it. This doesn’t have to be a good user experience. Remember we are doing things for learning.

Game Development Concepts

What we’re building in this simulation is simple for a game developer (not me). While it could be done without following game development best practices, I’m using this as a learning opportunity. Each of these concepts has extensive tutorials online, but here’s a brief (and possibly flawed) summary of them:

1. Game Loop

A game loop is what keeps a game running. It’s a continuous cycle that handles user input, updates the game state, and redraws everything on the screen. In Pygame, this means checking for events like key presses, updating objects, and rendering the latest frame. The loop keeps running until the game ends, making everything feel smooth and responsive.

Basically, a game loop is a while loop that runs forever unless user closes the game.

A basic game loop in Pygame looks like this:

import pygame

# Initialize Pygame
pygame.init()

# Set up screen and clock
screen = pygame.display.set_mode((800, 600))
clock = pygame.time.Clock()

# Game loop
running = True
while running:
    # Handle events
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False
        # Handle other events that are important to your application

    # Update game state
    # (update game objects, logic, etc.)
    update()  # Implement your update function and call it

    # Render the screen
    screen.fill((0, 0, 0))  # Clear screen with black
    # (draw game objects, etc.)
    draw()  # Implement your rendering function and call it

    pygame.display.flip()  # Update the display

    # Cap the frame rate to 60 frames per second
    clock.tick(60)

# Clean up
pygame.quit()

2. Frame Rate

Frame rate is how many frames (or images) your game renders per second. It’s usually measured in FPS (frames per second). A higher frame rate makes the game look smoother, while a lower frame rate can make it feel choppy. But it’s not just about visuals — if your game logic is tied directly to the frame rate, things can speed up or slow down depending on performance, which is why frame rate independence is important.

It is often recommended capping FPS for several reasons. While higher frame rates can make the game smoother, they may also lead to excessive CPU or GPU usage, leading to performance issues, overheating, and reduced battery life on portable devices. By capping the FPS, we ensure the game runs consistently across different hardware and prevent unnecessary performance spikes. A common cap, such as 60 FPS, provides a stable and smooth experience without overloading the system.

In the above code, we have the following code piece in the basic game loop. It allows at most 60 frames per second. It adds a calculated waiting time between frames. Without it, the program doesn’t wait between frames, keeps updating objects and rendering graphics at a very high speed.

# Cap the frame rate at 60 FPS
clock.tick(60)

3. Frame Rate Independence

Frame rate independence is the idea that your game’s logic (like movement, animations, and physics) should behave the same way regardless of how fast or slow frames are being rendered. Instead of relying on a fixed number of updates per second, you scale calculations based on elapsed time (delta time). That way, even if the frame rate fluctuates, things move at a consistent speed.

A simple (but not too precise) implementation of frame rate independence can be done as follows. It moves clock.tick to the beginning of the loop, stores the elapsed seconds since the previous frame in a variable, and passes that value to our imaginary update function.

# Main game loop
running = True
while running:
    # Get delta time from clock.tick (in seconds)
    delta_time = clock.tick(60) / 1000  # Convert to seconds

    # Event handling
    handle_events()

    # Update game state with delta time
    # We are passing delta_time to make components do time-based updates
    update(delta_time)

    # Render
    draw()

All components/sprites/game objects in the game should update their internal state based on the elapsed time.

speed = 10

# Bad: how fast character moves depends on the frame rate
player.x += speed

# Good: character moves with constant speed
player.x += speed * delta_time

4. Delta Time (Δt, Elapsed Time)

Delta time (Δt) represents the time difference between the current and the previous frame. Many game engines use this term when updating movement, animations, or physics to make sure things stay consistent, even if the frame rate fluctuates.

To demonstrate how delta time ensures consistent behavior despite varying frame rates, let’s look at a simple example where we increment a counter every second. The key idea here is to track the time between frames and update our game logic based on elapsed time, rather than relying on a fixed frame rate. This way, regardless of how fast or slow the frames are being rendered, the logic will behave consistently, and the counter will increment once every second. Here’s a simple code snippet showing how this works:

class Counter:
    counter = 0
    elapsed_time = 0

    def update(delta_time):
        elapsed_time += delta_time
        if elapsed_time >= 1:
            counter += 1
            elapsed_time -= 1

5. Multiple Scenes

In a game, we rarely have just one screen. We usually have a welcome screen, a main menu, a gameplay area, a pause menu, and maybe a game-over screen. Each of these different sections of the game is often called a scene.

A scene represents a self-contained part of the game with its own logic, visuals, and interactions. When transitioning between different parts of the game, we are essentially switching scenes. Some game engines explicitly use the term scene (like Unity and Godot), while others might call them screens, states, or stages.

Managing multiple scenes usually requires a system that can switch between them smoothly. Some games simply replace one scene with another, while others keep multiple scenes active at once—like having a gameplay scene running in the background while a pause menu scene is displayed on top.

An oversimplified scene transition might look like this:

class Scene:
    def update(self):
        pass

    def render(self, screen):
        pass


class Game:
    def __init__(self):
        self.scenes = {"menu": MenuScene(), "game": GameScene()}
        self.current_scene = self.scenes["menu"]

    def run(self):
        while True:
            self.current_scene.update()
            self.current_scene.render(screen)  # Assume screen is initialized


class MenuScene(Scene):
    def update(self):
        if user_presses_start():
            game.current_scene = game.scenes["game"]


class GameScene(Scene):
    def update(self):
        if user_presses_exit():
            game.current_scene = game.scenes["menu"]

6. Sprite

A sprite is a 2D image or animation that is used to represent an object in a game. It can be a character, an item, or any visual element in the game world. Sprites are typically drawn on a 2D canvas or screen, and they can be moved, rotated, and manipulated during the game to give the illusion of interaction or animation.

A simple player sprite that moves right on every frame:

class Player(pygame.sprite.Sprite):
    def __init__(self, image, x, y):
        super().__init__()
        self.image = image
        self.rect = self.image.get_rect(topleft=(x, y))
        self.speed = 5

    def update(self, delta_time):
        self.rect.x += self.speed * delta_time  # Move right

player = Player(load_image("player.png"), 100, 100)

In this post, we explored the design of a multi-stage simulation using Pygame, focusing on creating a user-interactive experience that navigates through different states—startup, simulation, success, and failure screens. By incorporating game development concepts like the game loop, frame rate independence, delta time, and scene management, we’re not just building a simulation but also gaining a deeper understanding of how games and interactive applications are structured. While the added complexity isn’t strictly necessary for solving the shortest path problem, it provides a valuable learning opportunity for those interested in game development and Pygame.

In the next post, we’ll dive into the actual implementation of this simulation. We’ll write the code to bring these stages to life, handle user input, and visualize the shortest path algorithm step by step. Get ready to see how all these concepts come together in a functional Pygame application!

Solving Shortest Path in a Binary Matrix

Sat, 22 Mar 2025 13:05:00 +0000

Hey all! This is the second post in the “Simulating Shortest Path in a Binary Matrix using Pygame” series. In this post, we will choose an algorithm and explain why we selected it as our preferred approach for this problem. We’ll also describe a few alternative algorithms commonly used for similar types of problems. Then, we’ll analyze the time and space complexity of the algorithm using Big-O notation. Finally, we will implement the algorithm in Python.

Choosing the Right Algorithm

When choosing an algorithm for finding the shortest path in a binary matrix, we need to consider both correctness and efficiency. A brute-force approach, such as trying all possible paths, is infeasible due to its exponential time complexity. A depth-first search (DFS) might seem like an option, but since it explores one path fully before backtracking, it doesn’t guarantee the shortest path in an unweighted grid. A* search is another possibility, as it uses heuristics to optimize the search, but implementing an effective heuristic for this specific problem adds complexity. Given that we are working with an unweighted grid where all movements have the same cost, Breadth-First Search (BFS) is the ideal choice—it explores all possible paths level by level, ensuring that the first time we reach the target, we’ve found the shortest path. Therefore, we will use BFS for our implementation.

Here’s why BFS is particularly suited for this problem and how it compares to other algorithms:

Guaranteed Shortest Path: Since BFS visits nodes layer by layer, the first time it encounters the target node, it has found the shortest path in terms of the number of moves.
Efficiency: BFS works efficiently in grid-based problems, like the one in this task, where we don’t need to worry about weighted edges or more complex conditions. Every move from one cell to another has the same “weight” (cost), which is a key factor in why BFS is optimal.

Other Algorithms:

While BFS is ideal for this problem, there are alternative approaches that can be used for pathfinding:

Depth-First Search (DFS): DFS explores deeper into the graph before backtracking, which makes it less suitable for shortest path problems. It may explore longer paths before finding the target, which means it could miss the shortest path unless additional logic is used to track distances.
Dijkstra’s Algorithm: Dijkstra’s algorithm is used for finding the shortest path in graphs with weighted edges. However, in this case, all moves have the same “cost”, making BFS a simpler and more efficient choice. Dijkstra’s algorithm is also more computationally expensive due to the priority queue management.
A* Search Algorithm: A* is an advanced pathfinding algorithm that uses heuristics to guide the search. While it can be faster than BFS in certain cases, it requires additional setup with heuristic functions. In this problem, a simple BFS is sufficient, and introducing heuristics would be an unnecessary complexity.

Space and Time Complexity of BFS

Time Complexity:

In BFS, the time complexity is often represented as O(V + E), where:

V is the number of vertices (nodes) in the graph.
E is the number of edges (connections between nodes).

For our grid problem, let’s consider:

V (vertices): In a grid of size N x N, there are N² vertices (one for each cell in the grid).
E (edges): Each vertex (cell) can have up to 8 neighbors (up, down, left, right, and the 4 diagonal neighbors). So, in the worst case, the number of edges will be 8 times the number of vertices, which gives us a maximum of 8 * N² edges.

Therefore, the time complexity of BFS can be expressed as:

O(V + E) = O(N² + 8 * N²) = O(9 * N²) = O(N²)

Since constants are dropped in Big-O notation, it simplifies to O(N²).

Space Complexity:

Queue: BFS uses a queue to store the vertices that need to be explored. In the worst case, the queue could hold all the vertices of the grid, as we could be exploring each one. Therefore, the space complexity for the queue is O(V). Since the grid has N² vertices, this becomes O(N²).
Visited List: BFS typically also keeps track of which vertices have been visited to avoid revisiting them. This requires storing a boolean value (True/False) for each vertex, which also takes O(N²) space for the grid, as there are N² vertices to track.
In summary:
- The queue will take up O(N²) space.
- The visited list will also take up O(N²) space.
- So, the total space complexity is O(N²) + O(N²) = O(N²).

Let’s Code the Algorithm

To begin with, it’s worth mentioning that I will implement the function with a different signature than what LeetCode requires for their question. I will also use these functions in the simulation code I will implement later. Inline comments will be included in the code, and I will minimize explanations outside the code.

Imports and Constants:

# This is a double-ended queue implementation in python.
# It is an efficient data structure for our queueing needs.
from collections import deque

# The partial() is used for partial function application which “freezes” some portion 
# of a function’s arguments and/or keywords resulting in a new object with a simplified signature.
from functools import partial

# This is to be used as type hints when we take the grid as a parameter to the functions
from typing import List

# Values inside the grid 2-D array.
# Using constants instead of numbers self-documents the code.
WALL = 1
NON_WALL = 0

# All directions we can go from any Vertex (cell in grid). Having them in an array reduces the code duplication 
# when we try finding all neighbors.
DIRECTIONS = [
    (1, 0),   # Right
    (1, 1),   # Bottom-Right
    (0, 1),   # Bottom
    (-1, 1),  # Bottom-Left
    (-1, 0),  # Left
    (-1, -1), # Top-Left
    (0, -1),  # Top
    (1, -1),  # Top-Right
]

Is a valid move?

def is_valid(
    x: int,
    y: int,
    grid: List[List[int]],
    size: int,
    visited: List[List[bool]],
) -> bool:
    """
    Given a position (x, y), verifies if it is within the grid's boundaries,
    if it is not a wall (grid[x][y] == 1), if it is not visited before.
    Use this function to test if a candidate neighbor can be queued for a visit.
    """
    if not (x >= 0 and x < size and y >= 0 and y < size):
        return False
    if grid[x][y] == WALL:
        return False
    if visited[x][y]:
        return False
    return True

Visiting Neighbors:

def visit_neighbors(
    x: int,
    y: int,
    grid: List[List[int]],
    size: int,
    visited: List[List[bool]],
    queue: deque,
) -> None:
    """
    Given a position (x, y), visit its neighbors and queue them for a visit.
    Returns the list of neighbors for further processing in the simulation.
    """
    is_valid_partial = partial(is_valid, grid=grid, size=size, visited=visited)
    neighbors = []

    for dx, dy in DIRECTIONS:
        new_x, new_y = x + dx, y + dy
        if is_valid_partial(new_x, new_y):
            visited[new_x][new_y] = True
            neighbors.append((new_x, new_y))

    queue.extend(neighbors)
    return neighbors

The algorithm:

def shortest_path(
    grid: List[List[int]],
    start: tuple[int, int] = (0, 0),
    end: tuple[int, int] = None,
) -> int:
    """
    Given a square grid, find the shortest path from the start to the end.
    Returns the number of steps required to reach the end from the start.
    If no path is found, returns -1.
    """

    # Size of the grid; assuming it is a square grid
    size = len(grid)

    # Initialize the level of the BFS traversal
    level = 0

    # If end is not provided, set it to the bottom-right corner of the grid
    if end is None:
        end = (size - 1, size - 1)

    # If start or end is a wall, return -1
    start_x, start_y = start
    end_x, end_y = end
    if grid[start_x][start_y] == WALL or grid[end_x][end_y] == WALL:
        return -1

    # Initialize the visited matrix and the queue for BFS traversal
    # Both data structures are initialized with the start position
    visited = [[False] * size for _ in range(size)]
    visited[start_x][start_y] = True
    queue = deque([start])

    # Perform BFS traversal. Loop until the queue is empty.
    while len(queue) > 0:
        # At each iteration, we exhaust all elements at the current level.
        level += 1
        
        # Loop through only the number of elements at the current level because the queue
        # will be modified during the iteration.
        elements_at_level = len(queue)
        for _ in range(0, elements_at_level):
            # Pop the element from the queue
            x, y = queue.popleft()
            # If the end is reached, return the level
            if x == end_x and y == end_y:
                return level
            # Visit the neighbors of the current element. They will be processed in the next level.
            visit_neighbors(x, y, grid, size, visited, queue)

    # There are no more elements to visit and the end was not reached
    return -1

This code defines the algorithm that returns either the length of the shortest path between start and end positions in the given square grid or -1 when there is no such path.

That’s it! We can test this function by providing some solvable and non-solvable grid examples.

Let’s test it with the first example we have given in the first post of this series and two examples shared on the original LeetCode question.

def test_shortest_path_2x2_solvable():
    # The first example on the LeetCode question
    grid = [
        [0, 1],
        [1, 0],
    ]
    assert 2 == shortest_path(grid)


def test_shortest_path_3x3_solvable():
    # The second example on the LeetCode question
    grid = [
        [0, 0, 0],
        [1, 1, 0],
        [1, 1, 0],
    ]
    assert 4 == shortest_path(grid)


def test_shortest_path_5x5_solvable():
    # Our randomly generated example we've seen in first post of this series
    grid = [
        [0, 0, 0, 1, 1],
        [1, 0, 1, 1, 1],
        [1, 0, 1, 0, 1],
        [0, 0, 1, 0, 0],
        [1, 0, 0, 0, 0],
    ]
    assert 7 == shortest_path(grid)


def test_shortest_path_5x5_unsolvable():
    # Just flipping (x=1, y=2) from 0 to 1, we have made our above example unsolvable
    grid = [
        [0, 0, 0, 1, 1],
        [1, 0, 1, 1, 1],
        [1, 1, 1, 0, 1],
        [0, 0, 1, 0, 0],
        [1, 0, 0, 0, 0],
    ]
    assert -1 == shortest_path(grid)

With our BFS implementation in place, we now have a solid foundation for solving the shortest path problem in a binary matrix. We’ve chosen BFS for its efficiency in unweighted grids and verified its correctness with test cases. This completes the algorithmic part of our journey. Now, we’re ready to shift our focus to visualization. In the next posts, we will bring this algorithm to life by simulating its execution step by step using Pygame. Stay tuned!

Introduction: Shortest Path in a Binary Matrix Problem

Sat, 22 Mar 2025 13:00:00 +0000

Hello! This is the first post of a new series I am starting about “Simulating Shortest Path in a Binary Matrix using Pygame”. In this series, I’ll walk through how I approached solving the “1091. Shortest Path in Binary Matrix” problem from LeetCode. This problem was not only an interesting coding challenge but also something I encountered during a job interview. After solving the problem, I also want to implement a visual simulation code that demonstrates how the algorithm works. I am not expert in simulating things and building visual software. I will use this challenge to learn how to use Pygame and how to simulate algorithms.

The Problem

The “1091. Shortest Path in Binary Matrix” problem from LeetCode is a classic pathfinding problem. The task is to find the shortest path from the top-left corner to the bottom-right corner in a binary matrix, where 0 represents an open cell and 1 represents a blocked cell. The catch is that you can only move horizontally, vertically, or diagonally, and the goal is to determine the shortest path if it exists.

Problem Breakdown:

Input: A binary matrix where each cell is either 0 (open) or 1 (blocked).

Output: The length of the shortest path from the top-left to the bottom-right corner of the matrix. If no path exists, return -1.

Conditions:

You can only move from a cell to its 8 surrounding cells (vertically, horizontally, or diagonally).
You cannot move through cells marked with 1.
The path must be the shortest possible route to the bottom-right corner.

Example:

Below is a 5x5 binary matrix example. You can see the diagram to better understand how we should navigate within the given grid.

grid = [
    [0, 0, 0, 1, 1],
    [1, 0, 1, 1, 1],
    [1, 0, 1, 0, 1],
    [0, 0, 1, 0, 0],
    [1, 0, 0, 0, 0],
]

Solving the problem for the above grid should give us 7 as the result since we are visiting seven locations to reach our destination. This result includes start and end locations as well.

This problem is a good exercise for practicing pathfinding algorithms and understanding how to deal with grid-based problems, which can often come up in interviews (happened to me) or real-world scenarios (never happened to me).

In the upcoming posts in this series, we will focus on implementing an algorithm solving the problem and simulating it visually. Before jumping into the next post, feel free to pause here and try solving it by yourself for more fun. You can click here to solve it on LeetCode.

Enjoy!

Tekrar Merhaba

Tue, 11 Feb 2025 23:11:50 +0000

Uzun bir aradan sonra, tekrar merhaba! Bu yazıda merak edenlere hayatımda bu süre içerisinde olup bitenleri kısaca özetliyor ve blogda her an meydana gelebilecek olası bir format değişikliğinden önce sizleri uyarıyorum.

Bu yazıdan önceki son yazımı Mayıs 2021’de Unit Test serisi altında yazmıştım. Henüz Türkiye’de, bir önceki işim Inomera‘da çalışıyordum ve başka şirketlerle iş görüşmelerine başlamamıştım. 2021 senesinin sonunda epey yoğun bir şekilde yurt dışı şirketlerle mülakatlara başladım ve 2022 senesinin başlarında Amazon’dan aldığım teklifi kabul ettim. Temmuz 2022 senesinde Londra’ya taşındık ve Amazon’da çalışmaya başladım.

Londra’yı keşfetme, buradaki arkadaşlarla sosyalleşme, iş yoğunluğu vs derken zaman çok hızlı geçti ve blog’u neredeyse unuttum. Blog’u HTML’e çevirip canlıya alan travisci’daki süreci Github Actions‘a taşınma işini bir ara yapmışım ama mesela yazılara yorum yapma özelliğini unutmuşum. Epeydir yazıların altında bir yorum formu bile yok ama ben fark etmemişim :)

2022 senesi bu şekilde geçerken 2023 senesi geldi. Bu seneye dair aklımda kalan en önemli şey eşimin hamileliği oldu. Oğlumuzun kalp atışını da ilk defa doğum günümde Londra’daki özel bir Türk kliniğinde duyma şansını yakaladım. Londra’ya bir şekilde yolu düşen Türk arkadaşların ihtiyacı olursa diye buraya web adreslerini bırakayım: Medstar

2024 senesinin Ocak ayında ise oğlumuz Ege ile sonunda yüz yüze tanışabildik.

Bu tarihten itibaren özel hayatımda bırakın blog yazmayı, whatsapp mesajlarına dönmeyi unuttuğum oldu. Evlat sahibi olmak nasıl hem dünyanın en güzel hem de en yorucu şeyi ailecek deneyimlemiş olduk. Ege’nin varlığıyla dünyadaki geri kalan her şey artık benim için ikinci plandan sekizinci veya dokuzuncu plana düşmüş bulunmaktadır. Bir kez daha iyi ki doğdun oğlum.

Ve gelgelelim sene 2025 olmuş. Artık yavaş yavaş tekrar akşamları bilgisayar başına oturmaya başlıyorum. “Uzun zamandır yoktum biri demiş öldü, şimdi de yazsınlar kral geri döndü.” gibi iddialı bir laf edecek kadar bir varlık göstereceğimi sanmıyorum. Bir önceki blog yazımı yazdığım zamanlarda insanlar o tür teknik içeriklere çoğunlukla Google’dan ulaşıp okurlardı. Şimdilerde ben çoğu sorumu Google yerine LLM’lere soruyorum ve insanların da artık yavaş yavaş buna adapte olduğunu varsayıyorum. Bu da uzun uzun teknik yazılar yazma veya giriş seviyesi bilgiler paylaşma hevesimi kırıyor. Artık bizim yazdıklarımız son kullanıcıya mı hitap ediyor yoksa yapay zekayı eğiten içeriklerden mi oluyor bilemiyorum.

Velhasıl kelam, önümüzdeki günlerde ara ara tekrar bir şeyler yazmayı deneyebilirim fakat söz veremem. Konseptimi de birazcık değiştirip artık uzun teknik yazılar yerine kısa kısa bilgiler paylaşabilirim. Bunlar da daha çok tuttuğum notların temize çekilmesi gibi görülebilir.

Amazon kariyerimde birçok yeni şey deneyimleme fırsatım oldu. Bunlardan en önemlilerinin de AWS’de bulunan birçok servisi bir şekilde kullanma fırsatı bulmam, ucundan kıyısından ML dünyasına giriş yapmam ve Python dilini öğrenmem olduğunu düşünyorum. Amazon kültürünü yerinde deneyimlemek ve birçok yetenekli insanla birlikte çalışmak da benim için çok büyük bir artı oldu. İlerleyen zamanlarda bu blogda pek aşina olmadığımız Python dilinde kodlara ve AWS terminolojisine denk gelme ihtimalimiz oldukça yüksek!

Daha fazla uzatmadan tekrar merhaba ve görüşmek üzere diyorum ve bu yazıyı kapatıyorum. Sağlıcakla!

Unit Test 05: Test Edilebilir Yazılım Nasıl Geliştirilir?

Tue, 18 May 2021 20:15:00 +0000

“Unit Test” yazı dizisinin bir önceki yazısında kaliteli unit test nasıl yazılır konusunu incelemiştik. Bu yazıda da test edilebilir yazılımlar nasıl tasarlanır sorusuna cevap arayacağız.

Unit test yazmaya başlayıncaya kadar oldukça kaliteli kod yazdığımı zannederdim. Artık yazamadığımı biliyorum.

Bir koda unit test yazamama durumu kodun yeteri kadar kaliteli olmadığını adeta bağıran bir durumdur. Aşağıda yazılımı unit test yazılması zor veya imkansız hale getirebilecek birkaç faktöre ve olası çözümlerine değineceğiz.

Sınıfların / Fonksiyonların Fazla Sorumluluk Yerine Getirmesi

Legacy projelerde bazen yüzden fazla satırdan oluşan metodlar içeren sınıflara test yazmak zorunda kaldığım oluyor. Test metodu çoğunlukla test edilen metoddan da uzun oluyor. Böyle sınıflara test yazmak hem çok uzun sürüyor hem de çok fazla veri oluşturmak, çok fazla bağımlılığı mock olarak tanımlamak, onlarca farklı koşula belki yüzlerce test yazmak gerekiyor.

Bu tür sınıflar genellikle çok da fazla değişim geçirdiklerinden, her bir değişiklikte bir anda yüzlerce testin hata vermeye başlaması ve test bakım maliyeti çıkıyor.

Sınıflarımızı SOLID prensiplerini göz önünde bulundurarak tasarlamamız gerekiyor. Özellikle de SOLID‘in S‘sine, yani “Single-responsibility” prensibine dikkat etmemiz gerekiyor:

Bir sınıfın sadece bir sorumluluğu olmalı, bir sınıfın değişmek için sadece bir sebebi olmalı.

Bunu başarabilmek için de sınıflarımızı tasarlarken tüm kodu bir dosyaya yazmak yerine tekrar kullanılabilir parçalar halinde tasarlamamız gerekiyor. Böylece testlerde bazı parçaları test edip bazı parçaları sahte/mock implementasyonlar ile izole edebiliriz.

Tekrar kullanılabilir yazılım bileşenleri üretebilmenin en şık yolu da genellikle doğru tasarım şablonlarını (Design Patterns) bulup kullanmaktan geçiyor. Yazılımcıların tasarım şablonlarına hakim olması kaliteli yazılım geliştirmede önemli bir basamak.

Gereğinden Fazla Statik Kod Kullanımı

Statik kod zehirlidir. Birazı kafa yapar, fazlası projeyi öldürür. Pek kıymetli Akın Kaldıroğlu hocamın da söylediği gibi “Statik kullanımı bulaşıcıdır”.

Bu statik kodların gereksiz yerlerde kullanılmaya başlanması veya dozunun ayarlanamaması projede IoC (Inversion of Control) prensibi kullanımını minimuma düşürür.

Bir API isteğini aldıktan sonra servis katmanı, iş mantığı, cache yapısı ve DAO (veritabanı) katmanının tamamen statik metodlar üzerinden yapıldığı bir projeye denk geldim yakın zamanda. Bu tip bir projede unit test yazmaya kalkarsanız kanser olabilirsiniz. Neredeyse hiçbir katman bir diğerini tamamen çalıştırmadan test edilemiyor.

Statik metod kullanımını yukarıda bahsettiğim gibi projede asıl işin yapıldığı sınıflarda tavsiye etmiyorum, kullanmamalıyız. Utility fonksiyon dediğimiz apache commons kütüphanelerindeki StringUtils, NumberUtils, CollectionUtils, vb. sınıfların statik metodlarını kullanabiliriz veya bunlara benzer metodları kendimiz projelerde statik olarak yazabiliriz. Bu tip fonksiyonlara pure (saf) fonksiyon deniyor. Yani herhangi bir çevresel faktöre bağlı olmayan, aynı girdilerle her zaman aynı çıktıyı veren fonksiyonlar.

Ortama bağımlı, kararsız, sağı solu belli olmayan, sistemde global state değişikliği yapan, yan etkileri olan statik metodlardan uzak durmalıyız.

Not: Statik metodların da mocklanabilmesi için Java’da “Power Mock” isimli bir kütüphane mevcut. Fakat bir gün statik bir metodu mocklama ihtiyacı hissedersek projeye “Power Mock” eklemeden önce kodu iyileştirerek bu ihtiyacı ortadan kaldırmaya çalışmalıyız.

Bağımlı Olunan Nesnelerin Sınıf İçinde Oluşturulması

Kodda her new anahtar kelimesi gördüğümüzde ufak bir şüphe duymalıyız.

Her sınıflar arası etkileşimi sahte/mock implementasyon olarak izole etmemeliyiz fakat aşağıda birkaç örnek verebileceğim bazı bağımlılıklar sahte/mock şekilde izole edilmelidir.

Öncelikle “unit test” kavramını herkes farklı tanımladığı için burada çok büyük anlaşmazlıklar ortaya çıkıyor. Benim görüşümde sadece bir sınıfın/metodun davranışını diğer sınıflardan izole bir şekilde test edebilmek unit testtir. Eğer kompleks sınıflar arası etkileşimleri/entegrasyonları test ediyorsam buna entegrasyon testi derim. Bu kapsamda unit test yazarken aşağıdaki durumlardaki sınıfları mock olarak kullanmayı tercih ederim:

Kompleks business logic içeren veya kendisi de başka sınıflara bağımlı olan sınıflar
Veritabanı, disk, network, API, vb. ortama ve başka sistemlere bağımlı olan sınıflar
Birbirinden farklı mantıksal katmanlardaki sınıflar (Misal Controller -> Servis veya Servis -> DAO etkileşimi)
Global state üzerinde değişiklik yapan sınıflar
Kararsız, tutarsız veya saf olmayan fonksiyonlar içeren sınıflar

Bunların dışında basit DTO, JPA Entity, String, Calendar, Date, vb. sınıflarda mümkün olduğunca gerçek sınıfları kullanmaya çalışırım.

Gereğinden fazla mock kullanımı testleri hem kırılgan hem okuması zor bir hale getirebilir. Burada dengeyi iyi kurmamız gerekiyor. Test yazdıkça bu dengenin yazılımcıda içgüdüsel olarak geliştiğini düşünüyorum.

Bu bağlamda düşündüğümüzde eğer sahte/mock olarak kullanmak istediğimiz bir sınıf varsa ve bu sınıfı test edeceğimiz kod new anahtar kelimesi ile kendi içerisinde oluşturuyorsa, bu bağımlılıkları sahteleri ile değiştirmek oldukça zorlaşır. Daha önce statik metodlarda kullanıldığından bahsettiğim “Power Mock” kütüphanesi gibi bir kütüphane ile bu sınıfların constructor’larını mock’lamak gibi saçma işlere girişmemiz gerekir.

Bunun önüne geçebilmek için de testlerde sahtesi ile değiştirilmesi gereken bağımlılıkları constructor ile test edilecek olan sınıfa parametre olarak almamız gerekiyor. Eğer OOP yerine fonksiyonel programlama yapıyorsanız da test edilen fonksiyona bu bağımlılıklar parametre olarak geçilebilir.

Örneğin yukarıdaki başlıklarda verdiğim FrequentlyAskedQuestionServiceImpl ve PersonServiceImpl sınıflarının ikisinde de dışarıdan alınan bağımlılıklar constructor parametresi olarak geçilmiş durumda. PersonServiceImpl sınıfının metod içerisinde oluşturduğu Person nesnesi ise sahtesi ile değiştirmeye gerek duymadığım basit bir DTO/JPA Entity sınıfı, ya da data sınıfı diyebiliriz bu tür sınıflara.

Eğer PersonServiceImpl veritabanına erişimde kullandığı PersonRepository arayüzünün bir implementasyonunu aşağıdaki koddaki gibi constructor içerisinde kendisi oluştursaydı, sahtesi ile değiştirmek için test kodunda taklalar atmamız gerekirdi.

public class PersonServiceImpl implements PersonService {
    private final PersonRepository personRepository;

    public PersonServiceImpl() {
        final var mongoClient = MongoClients.create();
        this.personRepository = new PersonRepositoryImpl(mongoClient);
    }

    @Override
    public Person createPerson(CreatePersonRequest createPersonRequest) {
        final var firstName = Objects.requireNonNull(createPersonRequest.getFirstName(), "firstName cannot be null");
        final var lastName = Objects.requireNonNull(createPersonRequest.getLastName(), "lastName cannot be null");
        final var phone = Objects.requireNonNull(createPersonRequest.getPhone(), "phone cannot be null");
        final var person = new Person(firstName, lastName, phone);
        return personRepository.savePerson(person);
    }
}

Test yazılamamasının yanında kaliteli kod yazım standartlarına da ters düşen bir yanı var, PersonServiceImpl sınıfı concrete bir PersonRepository implementasyonuna ihtiyaç duyuyor. Interface’ler üzerinden etkileşim kurma özelliğini kaybediyoruz.

Ayrıca PersonServiceImpl sınıfının PersonRepositoryImpl sınıfının nasıl oluşturulacağı bilgisine de gereksiz yere sahip olmuş oluyor.

Bu kodun mock olmadan yazılan testinin çalışması için gerçekten bir mongodb veritabanını ayağa kaldırmamız gerekiyor. Bu da yazacağımız testi unit değil entegrasyon testi yapar.

Saf Olmayan Methodların Kullanılması

Eğer saf olmayan veya kararsız da diyebileceğimiz metodlar test etmeye çalıştığımız kod tarafından kullanılıyorsa testlerimiz zaman ve ortam bağımlı hale gelebilir. Bu tür testler de çoğu zaman çalışırken ara sıra sebebini anlamak için vakit kaybedeceğimiz hatalar verebilirler.

Bu konuda Java’da kullanmayı en sevmediğim metodlar arasında şu tarih/zaman fonksiyonları başı çekiyor:

new Date()
Calendar.getInstance()
System.currentTimeMillis()

Bu tip sistemin o anki zamanını dönen metodları kullanan kodların testlerinde yazacağımız assertion’lar, genellikle testin hızlı çalışmasına bağlı olarak başarılı bitebilse de, testlerin çalışması sırasındaki birkaç milisaniyelik gecikme ile patlayabilirler.

Örneğin aşağıdaki 1000 iterasyonluk RepeatedTest metodu 1000 iterasyonun 33 defasında hata verdi:

public Date getCurrentDate() {
    System.out.println("getCurrentDate called");
    final var date = new Date();
    System.out.println("getCurrentDate result=" + date);
    return date;
}

@RepeatedTest(1000)
void getCurrentDate_returnsCurrentDate() {
    final var actual = getCurrentDate();
    final var expected = new Date();
    assertEquals(expected, actual);
}

Verdiği hatalardan bir tanesi de şu şekilde:

expected: java.util.Date@96901dd<Tue May 18 00:53:54 EET 2021> but was: java.util.Date@1cccaa86<Tue May 18 00:53:54 EET 2021>

Görüldüğü gibi expected ve actual Date nesneleri logda saniyesine kadar aynı görünüyor, o bir iki milisaniyelik farkı hata mesajından anlayamıyoruz bile.

Bu gibi durumlar için sistem zamanını bize dönen bir sınıf oluşturuyor ve bu sınıfı testlerde sahte bağımlılık olarak kullanıyoruz. Biz önceden bu iş için kendi Clock sınıfımızı yazarken Java 8 sonrası java.time.Clock sınıfını kullanmaya başladık.

Şimdi aşağıdaki gibi constructor argümanı olarak Clock alan bir sınıf yazalım:

public class DateRangeValidator {
    private final Clock clock;

    public DateRangeValidator(Clock clock) {
        this.clock = clock;
    }

    public void validateDateRange(Date startDate, Date endDate) {
        final var now = new Date(clock.millis());

        if (startDate.after(now)) {
            throw new IllegalArgumentException("startDate cannot be after current date");
        }

        if (endDate.before(now)) {
            throw new IllegalArgumentException("endDate cannot be before current date");
        }
    }
}

Bu sınıf için yazdığımız testlerde tarihler arası farkları aşağıdaki gibi birer milisaniye bile yapsak 1000 iterasyondan hiçbirinde hata vermemekte. Hem test ettiğimiz kod, hem de yazdığımız test ortam bağımsız şekilde aynı girdilerde hep aynı sonucu üretmekte.

@RepeatedTest(1000)
void validateDateRange_systemDateIsBetweenStartAndEndDates_doesNotThrowException() {
    final var startDate = 1621289298097L;
    final var now = startDate + 1;
    final var endDate = now + 1;
    final var clock = Clock.fixed(Instant.ofEpochMilli(now), ZoneId.systemDefault());
    final var validator = new DateRangeValidator(clock);

    validator.validateDateRange(new Date(startDate), new Date(endDate));
}

Global Değişiklik Yapan Yöntemlerin Tercih Edilmesi

Bu da gereksiz statik metod kullanımına benzer bir kötü pratiktir fakat bu kötü pratiğin sonuçları test edilemez bir kod yazmış olmaktan ziyade şöyle ortaya çıkıyor: Yazılan testler rastgele bir şekilde bazen başarılı olup bazen hata veriyor.

Örneğin kodda global bir değişken (static) tanımladık ve bir metod bu değişkenin değerini değiştiriyor. Bu değeri değiştirirken de varolan değer üzerinden bir hesaplama yapıyor. Bu metodun 10-12 tane testini yazdık. Her test bu global değişkende farklı bir durum değişikliğine neden olursa bir süre sonra işin ucu kaçar. Testlerin de hangi sırayla çalışacağının garantisi olmadığından, hangi test çalıştığında global değişken hangi değeri tutuyor gibi bilgileri kontrol etmek oldukça zorlaşır.

Global statik mutable değişken kullanmaktan ve bu değişkenler üzerinde değişiklik yapan metodlar yazmaktan mümkün olduğunca uzak durmalıyız.

Bu tip global state üzerinden iş yapan kodlar testleri ayrı thread’ler ile paralel koşmanın da önüne engel koyuyor. Aynı anda iki thread global state’e değişiklik yapabilir ve bu sebeple kodda bir hata meydana gelmese bile test kodundaki assertion’a yazdığımız expected result tutmayabilir.

Örneğin global bir AtomicInteger tuttuğumuzu ve bu sayıyı arttıran metodları iki farklı testin tetiklediğini düşünelim. Birinci test değeri 1 iken bir arttırıp 2 olduğunu assert ediyor fakat testler paralel koştuğu için o sırada ikinci test de değeri arttırdığından değer 3 geliyor. Böyle senaryolarda kodun çalışması tamamen doğru olduğu halde testler hata verebilir.

Biz ekipçe genellikle statik global state tutmadığımız için global state konusunda en çok karşılaştığım problemleri genelde ThreadLocal kullanımı sebebiyle yaşamışızdır. Thread Local Thread üzerinde global veri tutulması ve farklı thread’lerin bu veriyi görememesi için tasarlanmış bir nesne fakat fazla/hatalı kullanımında o da test yazılması zor kodlara sebep olabilmekte. Burada da testleri paralel koşmadığımızda hepsinin aynı thread tarafından çalıştırıldığını unutmayalım. Yani ThreadLocal bir nevi tüm test suite için global bir değişken haline geliyor.

Bitiş

Unit test yazı dizimizin bu yazısında test edilebilir yazılım nasıl geliştirilir konusunu inceledik.

Yazı dizisinin bu noktaya kadar olan yazılarıyla birlikte düşündüğümüzde, etkili unit testler yazdığımızda projenin yazılım kalitesinin nasıl artabileceğini artık daha iyi anlıyoruz. Kaliteli unit testler yazmaya çabaladığımızda sadece testlerin değil production kodunun da kalitesinin artmaya başladığını fark edeceğiz. Unit test yazacağını bilerek kod yazan geliştirici ya yazılımı baştan test edilebilir şekilde tasarlar ya da test yazamadığı noktada yazılımı test edilebilir hale dönüştürmeye çalışır.

Bu konular kesin doğrusu olmayan ve tartışmaya çok açık konular olduğu için, ben de bu konular üzerinde tartışmayı sevdiğim için, fikir ayrılıklarına düştüğümüz noktalarda ya da hemfikir olduğumuz noktalarda lütfen yorumlarınızı esirgemeyin.

Unit Test 04: Kaliteli Unit Test Nasıl Yazılır?

Tue, 18 May 2021 20:10:00 +0000

“Unit Test” yazı dizisinin bir önceki yazısında neden unit test yazarız sorusuna cevaplar arayıp unit testlerin faydalarına değinmiştik. İkna olduysak artık test yazmaya başlayabiliriz. Peki unit test nasıl yazılmalı? Unit test yazarken nelere dikkat etmeliyiz? Unit testlerimizin kaliteli, faydalı ve amaca yönelik olması için takip etmemiz gereken kurallar nelerdir? Bu yazıda da konunun bu boyutunu ele alıyor olacağız.

Küçük Testler Yazalım

Unit testler olabildiğince küçük kod parçaları olmalılar. Hata veren bir unit test çok hızlı bir şekilde okunabilmeli, testteki veri mi yoksa test edilen kod mu sıkıntılı çabucak anlaşılabilir olmalıdır.

Ayrıca uzun test fonksiyonları küçük değişikliklerden daha sık etkilenirler ve bu test kodlarında sonradan değişiklik yapmak da zorlaşır. Bu da kodun bakım maliyetinin yanında testlerin de bakım maliyetlerini arttırır.

Bağımlılıklardan İzole Edelim

Unit testi “unit” yapan şey sadece ve sadece test ettiği kodu test ediyor oluşudur. Test edilen kodun herhangi bir bağımlılığı varsa test sırasında bu bağımlılık izole edilir. Yani bağımlı olan sınıfın belirli bir davranışı sergilediği varsayılır, simüle edilir. Buna mocking denir ve birçok dilde bunu yapmamızı sağlayan kütüphaneler vardır.

Not: Ben bu yazıda birçok farklı izolasyon yöntemine mocking diyorum. Production için tasarlanmış bir bağımlılığın/nesnenin test amacıyla değiştirilmesi işinin genel adı literatüre Test Double olarak geçmiş ve birçok Test Double çeşidi var. Mocking bu çeşitlerden sadece bir tanesi fakat bizim dilimize malesef böyle yerleşmiş. Martin Fowler’ın sitesinde yazdığı diğer Test Double çeşileri: Dummy, Fake, Stub ve Spy

Bağımlı olduğumuz fonksiyonda bir hata varsa bunu nasıl yakalarız diye soruyorsanız, onu da bağımlı olduğumuz sınıf/fonksiyon için yazdığımız unit testlerde yakalamamız gerekiyor.

Java’da bu mocking işlemini yapmamızı ve bağımlılıklar varmış gibi davranmamızı sağlayan kütüphanelerin başını Mockito çekiyor. Aşağıda Mockito kullanarak yazdığım bir örneği anlatacağım.

Aşağıdaki PersonServiceImpl isimli sınıfın createPerson isimli metodunu test etmek istediğimizi düşünelim. Bu sınıfın PersonRepository isimli bir interface bağımlılığı var. Bu repository muhtemelen bir veritabanına insert işlemi yapmakta olup, ne yaptığı bizi hiç ama hiç ilgilendirmiyor.

public class PersonServiceImpl implements PersonService {
    private final PersonRepository personRepository;

    public PersonServiceImpl(PersonRepository personRepository) {
        this.personRepository = personRepository;
    }

    @Override
    public Person createPerson(CreatePersonRequest createPersonRequest) {
        final var firstName = Objects.requireNonNull(createPersonRequest.getFirstName(), "firstName cannot be null");
        final var lastName = Objects.requireNonNull(createPersonRequest.getLastName(), "lastName cannot be null");
        final var phone = Objects.requireNonNull(createPersonRequest.getPhone(), "phone cannot be null");
        final var person = new Person(firstName, lastName, phone);
        return personRepository.savePerson(person);
    }
}

Hatta ben bu sınıf için test yazarken PersonRepository arayüzü için bir implementasyon sınıfı bile yazmadım. Mockito kullanarak PersonRepository arayüzünün sahte (mock) bir implementasyonunu hazırladım ve savePerson metodu çağırıldığında ne dönmesini istediğimi aşağıdaki test metodunda belirttim.

@Test
void createPerson_validCreatePersonRequest_returnsSamePersonReturnedFromRepository() {
    // Arrange
    final var personRepository = Mockito.mock(PersonRepository.class);
    final var personService = new PersonServiceImpl(personRepository);
    final var expectedResult = new Person("Serdar", "Kuzucu", "+905554443322");
    Mockito.doReturn(expectedResult)
        .when(personRepository)
        .savePerson(Mockito.any(Person.class));

    // Act
    final var actualResult = personService.createPerson(CreatePersonRequest.builder()
            .firstName("Serdar")
            .lastName("Kuzucu")
            .phone("+905554443322")
            .build());

    // Assert
    assertSame(expectedResult, actualResult);
}

Bu test kaynak kodda PersonRepository arayüzünün herhangi bir implementasyonu olmasa bile başarılı bir şekilde geçiyor. Eğer bu izolasyonu sağlamasaydık gerçek bir PersonRepository implementasyonuna ihtiyacımız olacaktı. Bu durumda da bu implementasyon bir veritabanı kullanıyorsa testleri çalıştırabilmek için bizim de bir veritabanı bağlantısı kurmamız gerekecekti. Böyle bir test de unit test değil entegrasyon testi olacaktır.

Birbirinden Bağımsız Testler Yazalım

Unit testler asla birbirine bağımlı olmamalıdır. Bir unit testin çalışması için öncesinde başka bir testin başarıyla çalışmış olması gerekmemelidir. Böyle bir bağımlılık testlerin sıralı çalıştırılmasını zorunlu kılar ve çoğu test suite yazılımı (junit, vb.) test senaryolarının sıralı çalışacağını garanti etmez. Lokalimizde bir test sınıfındaki tüm testler doğru sırayla çalışıp başarılı olurken, CI/CD ortamında farklı sırayla çalışıp hata alabilirler.

Testler arası state paylaşımından olabildiğince kaçınmamız gerekiyor. Her test kendi state’ini oluşturmalı ve test sonrasında gerekiyorsa temizlemelidir. Eğer bir test sınıfındaki tüm testlerde başlangıç ve bitiş durumları için aynı kodları yazmak gerekiyorsa bunu bir testte yapıp diğerlerinin sırayla çalışacağını varsaymak yerine, kullandığımız test framework’ünün Setup ve TearDown özelliklerini kullanmalıyız.

Java’da çoğunlukla kullandığımız junit test framework’ünde bu “Setup” ve “TearDown” özellikleri, kullandığımız junit versiyonuna göre, @Before, @After, @BeforeClass, @AfterClass, @BeforeEach, @AfterEach, @BeforeAll ve @AfterAll gibi anotasyonlar ile sağlanıyor.

AAA Tasarım Şablonuna Uyalım

Yazı dizisinin ilk yazısında da değindiğim Arrange-Act-Assert, kısaca AAA, tasarım şablonunu mümkün olduğunca uygulayalım. Bu şablon hem dünya çapında genel geçer bir tasarım şablonu hem de testlerin okunabilirliğini arttıran bir yöntem. Testin okunabilir olması testin ne amaçla yazıldığını anlamayı kolaylaştırır. Anlaşılabilir bir test hata verdiğinde testteki veya koddaki hatanın bulunması da daha kolay olur.

Testlerimizi bu 3 aşamayı düşünerek yazdığımızda “ben bu test koduyla neyi test ediyorum” sorusunu kendi kendimize cevaplamamızı da kolaylaştıracaktır.

Bir Testte Sadece Bir Şeyi Test Edelim

Son derece normal bir şekilde test ettiğimiz fonksiyonun birden fazla dalı olabilir. Farklı girdilerde farklı çıktılar üreten değişik iş akışlarına sahip olabilir. Hata veren testlerden koddaki hatayı daha hızlı anlayabilmemiz için bir testin sadece tek bir şeyi test ediyor olması gerekmekte.

Örnek olarak aşağıdaki servis sınıfımızı düşünelim:

public class FrequentlyAskedQuestionServiceImpl implements FrequentlyAskedQuestionService {
    private final FrequentlyAskedQuestionRepository frequentlyAskedQuestionRepository;
    private final EventPublisher eventPublisher;

    public FrequentlyAskedQuestionServiceImpl(FrequentlyAskedQuestionRepository frequentlyAskedQuestionRepository,
                                              EventPublisher eventPublisher) {
        this.frequentlyAskedQuestionRepository = frequentlyAskedQuestionRepository;
        this.eventPublisher = eventPublisher;
    }

    @Override
    public SaveFAQResult saveFaq(String question, String answer) {
        if (frequentlyAskedQuestionRepository.existsByQuestion(question)) {
            return SaveFAQResult.ALREADY_EXISTS;
        }
        final var faq = new FAQ(question, answer);
        final var persistedFaq = frequentlyAskedQuestionRepository.saveFAQ(faq);
        eventPublisher.fireEvent(new FAQSavedEvent(persistedFaq));
        return SaveFAQResult.SUCCESS;
    }
}

Burada aşağıdaki gibi 6 farklı senaryoyu test edebiliriz:

Başarılı işlemde SUCCESS cevabı dönmeli:

@Test
void saveFaq_validQuestionAndAnswer_returnsSuccess() {
    final var question = "How to deorbit a satellite?";
    final var answer = "Lorem ipsum dolor sit amet...";
    final var repository = Mockito.mock(FrequentlyAskedQuestionRepository.class);
    final var eventPublisher = Mockito.mock(EventPublisher.class);
    Mockito.doReturn(false)
            .when(repository)
            .existsByQuestion(question);
    Mockito.doReturn(new FAQ(question, answer))
            .when(repository)
            .saveFAQ(Mockito.any(FAQ.class));
    final var service = new FrequentlyAskedQuestionServiceImpl(repository, eventPublisher);

    final var result = service.saveFaq(question, answer);

    assertEquals(SaveFAQResult.SUCCESS, result);
}

Başarılı işlemlerde FrequentlyAskedQuestionsRepository üzerindeki saveFAQ metodu doğru argümanlar ile tetiklenmeli:

@Test
void saveFaq_validQuestionAndAnswer_callsRepositorySaveMethodWithTheSameQuestionAndAnswerValues() {
    final var question = "How to deorbit a satellite?";
    final var answer = "Lorem ipsum dolor sit amet...";
    final var repository = Mockito.mock(FrequentlyAskedQuestionRepository.class);
    final var eventPublisher = Mockito.mock(EventPublisher.class);
    Mockito.doReturn(false)
            .when(repository)
            .existsByQuestion(question);
    Mockito.doReturn(new FAQ(question, answer))
            .when(repository)
            .saveFAQ(Mockito.any(FAQ.class));
    final var service = new FrequentlyAskedQuestionServiceImpl(repository, eventPublisher);

    service.saveFaq(question, answer);

    final var faqArgumentCaptor = ArgumentCaptor.forClass(FAQ.class);
    Mockito.verify(repository, Mockito.times(1))
            .saveFAQ(faqArgumentCaptor.capture());

    assertEquals(question, faqArgumentCaptor.getValue().getQuestion());
    assertEquals(answer, faqArgumentCaptor.getValue().getAnswer());
}

Başarılı işlemlerde EventPublisher üzerindeki fireEvent metodu doğru argümanlar ile tetiklenmeli:

@Test
void createFaq_validQuestionAndAnswer_firesFAQSavedEvent() {
    final var question = "How to deorbit a satellite?";
    final var answer = "Lorem ipsum dolor sit amet...";
    final var repository = Mockito.mock(FrequentlyAskedQuestionRepository.class);
    final var eventPublisher = Mockito.mock(EventPublisher.class);
    Mockito.doReturn(false)
            .when(repository)
            .existsByQuestion(question);
    Mockito.doReturn(new FAQ(question, answer))
            .when(repository)
            .saveFAQ(Mockito.any(FAQ.class));
    final var service = new FrequentlyAskedQuestionServiceImpl(repository, eventPublisher);

    service.saveFaq(question, answer);

    final var eventArgumentCaptor = ArgumentCaptor.forClass(FAQSavedEvent.class);
    Mockito.verify(eventPublisher, Mockito.times(1))
            .fireEvent(eventArgumentCaptor.capture());

    assertEquals(question, eventArgumentCaptor.getValue().getQuestion());
    assertEquals(answer, eventArgumentCaptor.getValue().getAnswer());
}

FrequentlyAskedQuestionRepository sınıfındaki existsByQuestion metodu true dönerse servis metodumuz ALREADY_EXISTS değerini dönmeli.

@Test
void createFaq_alreadyExistingQuestion_returnsAlreadyExists() {
    final var question = "How to deorbit a satellite?";
    final var answer = "Lorem ipsum dolor sit amet...";
    final var repository = Mockito.mock(FrequentlyAskedQuestionRepository.class);
    final var eventPublisher = Mockito.mock(EventPublisher.class);
    Mockito.doReturn(true)
            .when(repository)
            .existsByQuestion(question);
    final var service = new FrequentlyAskedQuestionServiceImpl(repository, eventPublisher);

    final var result = service.saveFaq(question, answer);

    assertEquals(SaveFAQResult.ALREADY_EXISTS, result);
}

FrequentlyAskedQuestionRepository sınıfındaki existsByQuestion metodu true dönerse FrequentlyAskedQuestionRepository sınıfındaki saveFAQ metodu hiç çağırılmamalı.

@Test
void createFaq_alreadyExistingQuestion_doesNotCallSaveFaqMethodOfRepository() {
    final var question = "How to deorbit a satellite?";
    final var answer = "Lorem ipsum dolor sit amet...";
    final var repository = Mockito.mock(FrequentlyAskedQuestionRepository.class);
    final var eventPublisher = Mockito.mock(EventPublisher.class);
    Mockito.doReturn(true)
            .when(repository)
            .existsByQuestion(question);
    final var service = new FrequentlyAskedQuestionServiceImpl(repository, eventPublisher);

    service.saveFaq(question, answer);

    Mockito.verify(repository, Mockito.never()).saveFAQ(Mockito.any());
}

FrequentlyAskedQuestionRepository sınıfındaki existsByQuestion metodu true dönerse EventPublisher sınıfındaki fireEvent metodu hiç çağırılmamalı.

@Test
void createFaq_alreadyExistingQuestion_doesNotPublishAnyEvent() {
    final var question = "How to deorbit a satellite?";
    final var answer = "Lorem ipsum dolor sit amet...";
    final var repository = Mockito.mock(FrequentlyAskedQuestionRepository.class);
    final var eventPublisher = Mockito.mock(EventPublisher.class);
    Mockito.doReturn(true)
            .when(repository)
            .existsByQuestion(question);
    final var service = new FrequentlyAskedQuestionServiceImpl(repository, eventPublisher);

    service.saveFaq(question, answer);

    Mockito.verify(eventPublisher, Mockito.never()).fireEvent(Mockito.any());
}

Bu şekilde unit testleri sadece bir şeyi test eder şekilde kurguladığımızda ileride kodda yapılacak bir değişikliğin tam olarak hangi senaryoyu veya senaryoları etkilediğini aldığımız hatadan nokta atışı bulabiliriz.

Bu arada bu örnek testleri yazarken yine daha önce yaptığım gibi FrequentlyAskedQuestionServiceImpl dışındaki hiçbir sınıfı doğru düzgün geliştirmedim. Testlerdeki izolasyon sayesinde buna ihtiyacım kalmadan yazdığım tüm testler başarılı bir şekilde çalıştı.

Hızlı Çalışan Testler Yazalım

Unit testleri hızlıca çalıştırılıp sonuç alabileceğimiz şekilde yazmalıyız. Uzun test çalışma süreleri genellikle geliştiricilerin testleri çalıştırmadan build almasıyla sonuçlanıyor.

Bir zamanlar üzerinde çalıştığım bu şekilde bir proje vardı. Çalışan testler çok uzun sürüyordu, birçoğu da çalışmıyordu. Nasıl olsa testler çalışmıyor diye kimse testleri çalıştırarak build almıyordu, kimse hataları düzeltmeye bile çalışmıyordu. Problem projedeki tüm testlerin silinmesiyle sonuçlandı.

Yavaş testler, test edilen sınıftaki bağımlılıkların testlerde yeterince izole edilmediğinin veya test edilen kodun aslında test edilebilir bir kod olmadığının göstergesi olabilir.

İlk Olarak En Basit Başarılı Senaryoyu Test Edelim

Test edeceğimiz kodun ne yapması gerekiyor? Asıl varoluş amacı ne? Bu soruya vereceğimiz en basit ve hızlı cevap için hemen bir test yazalım.

Örneğin bir String’i ters çeviren bir kodu test ediyorsak önce ters çevirilebilir kısa bir metin ile test edelim.

@Test
void reverse_threeLetterString_returnsReversedString() {
    final var text = "abc";
    final var result = StringUtils.reverse(text);
    assertEquals("cba", result);
}

Daha sonraki testlerde daha kompleks akışlara, uç senaryolara ve istisna durumlarına geçebiliriz.

@Test
void reverse_nullArgument_returnsNull() {
    final String text = null;
    final var result = StringUtils.reverse(text);
    assertNull(result);
}

Uç Senaryoların Testlerini Yazalım

Test edilen kodun uç senaryolarını da düşünelim ve mutlaka bu senaryolar için test yazalım.

Parametre null gelirse ne olur?
DB’den bir sonuç beklerken iki sonuç gelirse ne olmalı? Hiç sonuç gelmezse?
Bölme işlemi içeren bir fonksiyonda paydaya 0 (sıfır) gelme ihtimali var mı?
Beklediğimden büyük bir sayı gelirse integer overflow olur mu?
Kullanıcı adı boş String ("") geldiğinde fonksiyon ne yapmalı?
Javascript kodum null, undefined, 0, false ve "" arasındaki farkı ayırt edebiliyor mu?
…

Daha aklımıza gelebilecek bir çok senaryoyu buraya ekleyebiliriz ve çoğu kodda da geçerlidir bu durumlar.

Eğer kodumuz sınırlı bir veri aralığı ile ilgiliyse bu sınırların çizgilerini, sınırın bir miktar dışını, bir miktar içini de testlerimize eklemeliyiz.

Örneğin bir kullanıcının 3 defa şifresini yanlış girme hakkı varsa bu kontrolü yapan kodu şifrenin doğru girilmesi için test ettiğimiz gibi mutlaka 2, 3 ve 4 gibi sayılar ile test etmeliyiz.

Tüm Yol Ayrımlarını Test Edelim

Test edilen kodda yol ayrımları (if/else, loop, vb.) varsa mutlaka o yol ayrımlarına giren ve girmeyen testleri ayrı ayrı yazmaya özen gösterelim.

Bu hem coverage denen testlerin kodun ne kadarını kapsadığı metriğini arttırır hem de bu tür durumlarda olabilecek hataların erken fark edilmesini sağlar.

Kullanılan dile ait enum gibi bazı yapılar da gizli yol ayrımlarına neden olabilirler. enum tipinde bir veri üzerinde çalışan kodların testlerini yazarken enum üzerinde tanımlanmış tüm olası değerler için birer test yazmalıyız.

Hata Bulmak İçin Test Yazalım

Eğer kodda belirli bir durumda bir hata oluştuğu iddia ediliyorsa, kodu okuyup bug-fix geliştirmeden önce bu hatayı oluşturan bir unit test yazalım.

Testi çalıştırdığımızda hata alıyorsa doğru yoldayız demektir. Sonrasında istersek doğrudan koda dalabiliriz veya kod okumak için çok karışıksa testi debug modda çalıştırarak debug edebiliriz.

Koddaki düzeltmeyi yaptığımızda yazmış olduğumuz testin başarılı olduğunu görürsek tebrikler! Hem bir hatayı çözmüş oluruz hem de bu hatanın bir daha ortaya çıkmayacağını garanti altına alan nur topu gibi bir unit testimiz olur.

İsimlendirmelere Dikkat Edelim

Test isimlendirme konusunda çok farklı yazım standartları var ve birçok farklı standart farklı farklı geliştiriciler tarafından benimsenmiş durumda. Burada testlerimizi kesin şu şekilde isimlendirmeliyiz diyemiyoruz.

Şu makalede 7 farklı popüler isimlendirme örneği gösterilmiş. Hepsinin kendi avantajları ve dezavantajları var. Şu makalede ise test kodundaki isimlendirmelerin öneminden bahsedilmiş. Böyle konular çok tartışmaya açık konular olduğundan bu tip konularda fikir alışverişi de fazla oluyor.

Burada önerebileceğim en önemli şey şu, test ismine bakıldığında neyin test edildiği anlaşılmalı. test01, test02 gibi isimlendirmelerden veya fonksiyon ismi + sayı gibi hangi fonksiyonun test edildiği dışında bir bilgi vermeyen isimlendirmelerden kaçınmalıyız.

Bir diğer önerim de ekip içerisinde popüler bir isimlendirme standartına karar verilip onun uygulanması. Bir projede farklı diğerinde farklı isimlendirmeler yapılması bir süre sonra kafa karışıklığına yol açıyor ve devamında aynı projede farklı isimlendirme standartları ortaya çıkmaya başlıyor.

Ben şahsi olarak Java dilinde geliştirme yaparken Java metod isimlendirme kurallarına mümkün olduğunca uyulmasından yanayım. Sonuçta test metodu da bir Java kodu. Bu sebeple metod isimlerine büyük harf ile başlamayı kesinlikle sevmem. Fakat test metod isminin uzunca bir cümle olabileceğinden dolayı cümlenin farklı parçalarını _ ile ayırmayı da severim. Bu okunabilirliği arttırır. Unutmayalım bir test hata verdiğinde test isminin ne kadar okunabilir olduğu önemlidir.

Bu sebeple favori test metod ismi yazım stilim olan [testEdilenMetodİsmi]_[verilenGirdi|testEdilenDurum]_[beklenenÇıktı|beklenenDavranış] stilini kullandım bu yazıdaki örneklerde de.

Bahsettiğim standart ile yazılmış bazı örnekler:

registerUser_nullUsername_throwsException
reverseString_emptyString_returnsEmptyString
fireEvent_subscriptionCreatedEvent_writesEventToKafka

Bazen test edilecek metod herhangi bir state veya input bağımlılığı olmadan çok basit bir işlem yapıyor olabilir. Bu durumda test ismi yazacağız diye bir şeyler uydurmaya çalışmaya gerek yok. Bazı kısımları atlayabiliriz.

getUsername_returnsUsername
getCurrentTime_returnsCurrentTime

vb. örnekler çoğaltılabilir.

İstisnaları (Exceptions) Test Edelim

Test edilen kodun istisna durumları varsa, Java’da buna Exception deniyor, bunlar için de test yazmalıyız.

Çehov'un silahı

“Eğer birinci perde açıldığında duvarda bir tüfek asılıysa takip eden sahnede tüfek mutlaka patlamalı. Aksi takdirde oraya koymayın.”

Anton Çehov

Test edilen kodda bir yerde bir Exception fırlatıldığını görüyorsak, bu durumun doğru bir şekilde gerçekleştiğinden de emin olmalıyız.

Eğer unit test ile bile o istisna durumunu sağlayamıyorsak o koşulu kodumuzdan silebiliriz, büyük ihtimalle gereksizdir ve canlıda da karşımıza çıkmayacaktır.

Java 8 öncesi biraz daha zahmetli olan Exception testi yazma konusu Java 8 ve Junit 5 kütüphanesinin gelmesiyle aşağıdaki gibi oldukça kolaylaşmış ve yazması keyifli hale gelmiş durumda.

// Test edilen kod

public void throwIfUserDoesNotHavePrivilege(UserDetails user, String privilege) {
    user.getAuthorities()
            .stream()
            .map(GrantedAuthority::getAuthority)
            .filter(privilege::equals)
            .findFirst()
            .orElseThrow(() -> new AccessDeniedException("Privilege: " + privilege));
}

// Test kodu

@Test
void throwIfUserDoesNotHavePrivilege_userDoesNotHavePrivilege_throwsAccessDeniedException() {
    final var privileges = Set.of(
            new SimpleGrantedAuthority("PRIV_CHANGE_PASSWORD"),
            new SimpleGrantedAuthority("PRIV_VIEW_PROFILE"));
    final var user = new User("username", "password", privileges);

    final var exception = assertThrows(AccessDeniedException.class,
            () -> throwIfUserDoesNotHavePrivilege(user, "PRIV_UPDATE_PROFILE"));

    assertEquals("Privilege: PRIV_UPDATE_PROFILE", exception.getMessage());
}

Testlerimiz Başarısız Olduğunda Sebebi Belli Olsun

Bir test hata vermeye başladığında test kodunu okumadan önce hatanın hangi senaryoda ve hangi durumda olduğunu anlayabiliyor olmalıyız.

Bunun için anlamlı test metodu isimleri kullanma başlığında anlattıklarımın dışında bir de doğru assert kullanımı konusu var.

Eğer elimizde karşılaştırabileceğimiz iki değer varsa assertEquals veya assertSame kullanmalıyız. Böyle durumlarda karşılaştırmayı kendimiz yapıp assertTrue kullanırsak patlayan testin verdiği hata mesajından test ettiğimiz kodun ürettiği sonucu göremeyiz.

Örneğin aşağıda aynı hatalı kontrollerin assertEquals ve assertTrue ile verdiği hata mesajlarını okuyalım:

final int actualResult = 5;

assertTrue(4 == actualResult);
// Hata mesajı: expected: <true> but was: <false>

assertEquals(4, actualResult);
// Hata mesajı: expected: <4> but was: <5>


final String actualResult = "Lorem ipsam";

assertTrue("Lorem ipsum".equals(actualResult));
// Hata mesajı: expected: <true> but was: <false>

assertEquals("Lorem ipsum", actualResult);
// Hata mesajı: expected: <Lorem ipsum> but was: <Lorem ipsam>

Tabi ki boolean dönen bir metodun testini yazarken mecburen assertTrue kullanmamız gerekiyor. İki elimiz kanda da olsa assertTrue kullanmayalım gibi bir durum yok. O assertion’ın da bir varoluş sebebi var kütüphanede.

Ek olarak test yazarken kendimize sık sık bu soruyu da soralım: “Bu test bu assert sebebiyle patladığında hata mesajında ne yazar?” Hata mesajındaki bilginin yetersiz olacağını düşündüğümüz noktada, kullandığımız test kütüphanesi izin veriyorsa assert mesajına özel bir de bilgi de ekleyebiliriz.

Örneğin aşağıdaki kodda assertTrue kullandık fakat hata mesajını özelleştirdik:

final boolean startsWithPriv = privilegeName.startsWith("PRIV_");
assertTrue(startsWithPriv, "Privilege " + privilegeName + " does not start with PRIV_ prefix!");

// Hata mesajı: Privilege PR_AAA does not start with PRIV_ prefix! ==> expected: <true> but was: <false>

Ortam Bağımsız Çalışsın

Unit testler üzerinde çalıştığı ortamdan bağımsız şekilde her yerde çalışabilecek kadar izole geliştirilmeli. Yabancı bir blogda unit testler annenizin bilgisayarında bile çalışabilmeli yazmıştı bilgili bir abimiz.

Özellikle platform bağımsız dillerde dil farklı makineleri ve işletim sistemlerini destekliyor olsa bile yazılımcılar spesifik ortamlara bağımlı kodlar yazabilmektedir. Test edilen kodun ortam bağımsız olması ile ilgili konuları yazı dizimizin bir sonraki yazısı olan test edilebilir kod yazmak ile ilgili başlıkta da inceleyeceğiz.

Koddaki veritabanı, disk veya network gibi dış bileşenlerin kullanıldığı kısımları testlerde mock implementasyonlar kullanarak izole ederek ortam bağımsız hale getirebiliriz.

Linux/Windows arası dosya sistemindeki klasör ayracı (/, \) değişiyor. Bu tür şeylere dikkat ederek işletim sistemi ile ilgili problemlerden kurtulabiliriz.

Tarih/Zaman ile çalışan kodlarda tarih/zaman’ın sistemden okunması ile ilgili kısımları koddan izole ederek farklı zaman + timezone problemlerinden kurtulabiliriz.

Benim en çok karşılaştığım problem timezone oldu bugüne kadar. CI/CD sunucusu GMT+0 zamanında çalışırken geliştirici ekip olarak biz Türkiye’de GMT+3 zamanında çalışıyoruz. Test kodunda bir tarihi elle String olarak yazıp formatladığımızda lokalde çalışan testler CI/CD sunucusunda hata veriyor. Bununla ilgili kullandığımız çözümü de bir sonraki yazıda paylaşacağım.

Sonuç

Unit test yazı dizimizin bu yazısında, unit testlerin nasıl daha kaliteli, okunabilir ve işe yarar şekilde geliştirilebileceği konusunu inceledik.

Bir test metodu ile sadece bir şeyi test etmemiz gerekirken, test edilen koddaki her bir farklı senaryo için de ayrı bir test yazmamız gerekiyor.

Unit testi diğer test çeşitlerinden ayıran özelliklere gerçekten sahip olabilmemiz için bu yazıdaki her bir maddeye özen göstererek testlerimizi geliştirmemiz gerekiyor.

Bu maddelere uyabilmemiz için de test edilebilir, kaliteli bir production koduna ihtiyacımız var. Yazı dizimizin bir sonraki yazısında da test edilebilir kod nasıl yazılır konusunu inceleyeceğiz.

Unit Test 03: Neden Unit Test Yazarız?

Tue, 18 May 2021 20:05:00 +0000

“Unit Test” yazı dizisinin bir önceki yazısında unit test ve diğer test çeşitlerini birbirinden ayıran temel farkları incelemiştik. Bu yazıda neden unit test yazmalıyız sorusuna cevap arayacağız. Bu soruya bulduğumuz cevaplar bize aslında unit test yazmanın faydalarını anlatıyor olacak.

Şimdi unit test yazmak için bizleri motive edecek birkaç tane sebebi inceleyelim.

Hataların Erken Fark Edilmesi

Unit test yazılarak geliştirilen bir kodda yapılabilecek hatalar henüz o kodun geliştirme aşamasında fark edilecektir. Kendi tecrübelerimden gördüğüm kadarıyla bu şekilde çok farklı şekillerde hatalar bulunabiliyor. Hata bulma işlemi testleri yazıp çalıştırdığımızda beklenen sonucun gelmemesi sonucunda testin patlaması şeklinde gerçekleşebileceği gibi, test yazımı ile kodun geliştirilmesi birlikte ilerlediğinden, test yazarken koddaki hatayı gözle daha testi çalıştırmadan yakalamamız şeklinde de gerçekleşebiliyor.

Yukarıdaki grafik Steve McConnell tarafından yazılmış olan meşhur Code Complete kitabında yer alıyor. Grafiği en basit haliyle şöyle yorumlayabiliriz; bir hatanın oluşması ile fark edilmesi arasında ne kadar zaman geçerse, hatanın çözülmesi maliyeti o kadar artar. Grafiğe göre en maliyetli hatalar gereksinim belirleme aşamasında oluşup canlıya alım sonrası ortaya çıkan hatalar.

Unit testler birçok hatanın geliştirme sırasında bulunmasını ve çözülmesini sağladığı için hata çözme maliyetimizi minimum seviyeye indirmemizi sağlar. Yine de geliştirme öncesinde yapılacak olan gereksinim belirleme, analiz, sistem mimarisi çalışmalarının da minimum hata ile yapılmasının ve bu aşamalarda olabilecek hataların çözümünün geliştirme sürecine kadar gelmemesi gerektiğinin de altını çizmek gerekiyor.

Unit Test Kodun Dökümantasyonudur

Kaliteli kod kendisinin dökümantasyonudur bakış açısına benzer şekilde, kaliteli testler de test ettiği kodun bir dökümantasyonudur.

Karışık bir algoritma içeren bir fonksiyonu kaynak kodunu okuyarak anlamaktan daha kolayı unit testleri okuyarak anlamaktır. Özellikle benim gibi kod okurken fonksiyonlara soyut seviyelerde bakmayı seviyorsanız, siz de kodun içeriğine fazla girmeden dışarıdan baktığınızda ne yaptığını anlamak istersiniz. Bunun için çoğu durumda fonksiyonların isimlendirmeleri yeterli olsa da bazen birkaç tane unit testi okumak daha faydalı ve yeterli olabiliyor.

İyi yazılmış, okunaklı unit testler incelediğimiz fonksiyona veya bileşene hangi girdiler verildiğinde hangi çıktıların alınacağını gösteren çok güzel örnekler barındırır. Test edilen kodun happy path olarak nasıl çalıştığını, uç senaryolarının neler olduğunu örnekler ile görmemizi sağlar.

Unit Test Kodu İstenmeyen Değişikliklerden Korur

Burası unit testlerin en sevdiğim kısmı. Geliştirdiğiniz özellikleri unit testler ile koruma altına alabilirsiniz. Biz veya bir başkası bir gün bu kodda herhangi bir değişiklik yaptığında, eğer beklenmedik bir hataya sebep oluyorsa bu hata daha önce bu kod için yazmış olduğumuz testler tarafından yakalanacaktır.

Testleri yazılmış bir sınıfa yeni bir özellik eklediğimizde genellikle yeni eklediğimiz özelliğin testlerine odaklanırız. Bu yeni özellik düzgün çalışıyor olsa bile bu sınıfın mevcutta yerine getirebildiği bir özelliği yerine getirememesine sebep olabilir. Varolan bir kodun tüm uç senaryolarını tek tek test etmeyi çoğu zaman atlarız. Böyle durumlarda varolan özelliklerin önceden yazılmış testlerinin olması istenmeyen hatalardan bizi korur.

Ek olarak bu koruma bize özgüven verir. Normalde canlıda çalışan ve kritik öneme sahip bir fonksiyonda bir değişiklik yapmak en junior geliştiricisinden en senior geliştiricisine kadar herkesi korkutan bir süreçtir ve fonksiyonun kritikliğine göre bazen tüm projenin baştan uçtan uca test edilmesine kadar götürebilir. Unit testlerin varlığı o fonksiyonu değiştirme konusundaki cesaretimizi ve özgüvenimizi arttırır. Yaptığımız değişikliğin başka bir şeyi bozmadığından emin olmamızı sağlar.

Unit Test Kodun Karmaşıklığını Azaltır, Kalitesini Arttırır

Unit test yazabilmek için en küçük yazılım bileşenlerinin bile tasarımında planlı olmamız gerekir. Karmaşık, kompleks bir kodun testi de o kadar karmaşık ve yazması maliyetli olacaktır. Bu maliyet bizi daha test edilebilir, daha ufak sınıflar/fonksiyonlar yazmaya zorlar. Bu zorunda kalmışlık kodun daha okunabilir, daha az kompleks ve sonunda daha kaliteli olmasını sağlar.

Test edilebilir kod yazmaya çalışmak başlangıçta zor gibi gelse de zamanla iyi bir alışkanlığa dönüşüyor. Farkında olarak veya olmayarak SOLID, KISS, DRY, YAGNI, vb. bazı temel yazılım geliştirme prensiplerine uymamızı sağlar. Testini yazdığımız bileşenleri bağımlı olduğu diğer kod parçalarından bağımsız, izole bir şekilde test etme gereksinimi bu bileşenleri soyutlayabilmemizi ve tekrar kullanılabilir (reusable) küçük parçalar halinde kodumuzu tasarlayabilmemizi sağlar.

Bu sayede zamanla iki-üç satırlık küçük kodları bile ihtiyaç duyulan yerlere kopyala yapıştır yapmaktan, ayrı bir sınıf/fonksiyon şekline çevirerek kullanan bir geliştiriciye doğru evrim geçirdiğimizi fark ederiz.

Burada ayrıca ek bir noktaya da değinmeden geçmeyelim. Ufak bir kodu kopyala yapıştır usulü yazdığımız her fonksiyonda, o kod için tekrar tekrar test yazmamız gerekirken, ayrı bileşen yolunu tercih edersek o bileşen için bir defa test yazmamız yeterli olur. O bileşeni kullanan diğer fonksiyonlar, o bileşenin zaten test edildiğini bilerek sadece kendi fonksiyonalitelerinin testlerine odaklanırlar.

Hata Bulmayı (Debugging) Kolaylaştırır

Yazılımda bir hata olduğunu ve sadece debug ederek bulabileceğiniz bir durum olduğunu düşünün. Bunun için de tüm sistemi ayağa kaldırıp, arayüz üzerinden test verisi üretmeniz gerektiğini ve sonra spesifik bir aksiyonu tetikleyip kodun tüm katmanlarında breakpoint’ler yardımıyla satır satır debug ettiğinizi düşünün.

Sistemin büyüklüğüne ve geliştiricinin sistem üzerindeki tecrübesine göre bu hata arayışı saatlerce hatta tüm gün boyunca da sürebilir.

Bunun yerine aynı şeyi unit testler ile yaptığımızı düşünelim. Problemli olduğu düşünülen işlemin geçtiği kod bileşenlerine hataya sebep olabilecek test verilerinin girdi olarak verildiği ve çıktıların kontrol edildiği bir birim test yazabiliriz. Bu birim testi IDE üzerinde debug modda çalıştırabiliriz. Bu esnada sadece o sınıfı debug etmiş oluruz. Unit testlerde herhangi bir dış entegrasyon veya bağımlılık olmadığından test daha hızlı sonuçlanır. Tüm uygulamayı veya tüm sistemi bilgisayarımızda ayağa kaldırmamış oluruz. Hatayı bulma süreci daha hızlı ve daha az sancılı sonuçlanır.

Hatayı tespit ederken ve çözerken oluşturduğumuz unit test kodu projenin artık bir parçasıdır ve bu test senaryosu sayesinde aynı hatanın artık tekrarlanmayacağını da biliriz.

Not: Bir projenin kendi bilgisayarımızda ayağa kaldırılarak debug edilmesi senaryosunu neden abarttığım anlaşılmıyor olabilir. Çalıştığım bir mikro servis projesinde böyle bir debug yapabilmek için bazen bilgisayarımda 3-4 tane farklı mikro servisi, bu mikro servislerin kullandığı Oracle DB, Cassandra gibi iki farklı veritabanını, Kafka ile Zookeeper’ı ve Hazelcast uygulamasını ayağa kaldırmam gerekebiliyor. Böyle bir ortamı, düşük sistem özelliklerine sahip bir bilgisayarda ayağa kaldıran geliştirici arkadaşların bilgisayarlarında genellikle kod yazacak kadar bellek kalmıyor.

Önemli Bir CI (Continuous Integration, Sürekli Entegrasyon) Adımıdır

Sürekli Entegrasyon, veya İngilizcesi Continuous Integration, önemli bir yazılım geliştirme aracıdır. Yazılımdaki her bir değişiklikte tüm sistemin build edilmesi ve herhangi bir şeyin bozulmadığının kontrol edilmesi amacıyla yapılır. Bu işlem genellikle Jenkins gibi araçlar ile otomatize şekilde gerçekleştirilir.

Unit testleri olmayan projelerde CI işlemi sadece projenin build olabildiğini, derleyici hatası içermediğini garanti edebilir. Unit testleri olan projelerde ise derleme sonrasında test kodu otomatik olarak çalışacağından aynı zamanda varolan fonksiyonalitenin bozulmadığı da anlaşılmış olur.

Biz ne kadar yazdığımız kod sonrası tüm testleri çalıştırıp kontrol ediyor olsak da, kalabalık geliştirici ekiplerinde mutlaka bu kontrolü yapmadan doğrudan repository’ye kodu gönderecek olan arkadaşlar çıkacaktır. Aynı şeyi baskı altında kaldığımda, acilen bir fix göndermem gerektiğinde, yoğun olduğumda vb. benim de yaptığım oluyor. Bu gibi durumlarda daha ürünü paketleyip müşteriye teslim edemeden Jenkins’den gelen bir “Build Failed” e-postası ile yaptığımız değişikliğin bozduğu testleri görüyoruz.

Sonuç

Unit test yazı dizisinin bu yazısında neden unit test yazmamız gerektiğini inceledik. Unit testlerin okunabilir, kaliteli ve hatasız kod yazabilmek için kullanabileceğimiz en önemli araçlardan birisi olduğunu görmüş olduk. Unit testler ile olası hatalardan korunan projelerde kodda değişiklik yaparken hiç testi olmayan projelere kıyasla gönlümüzün daha ferah olabileceğini öğrendik.

Geliştirdiğimiz yazılımın kaliteli olması için geliştireceğimiz unit testlerin de kaliteli olması gerekir. Bir sonraki yazımızda kaliteli unit test nasıl yazılır sorusunun cevabını arayacağız.

Unit Test 02: Unit Test'in Diğer Test Çeşitlerinden Farkları Nedir?

Tue, 18 May 2021 20:00:00 +0000

“Unit Test” yazı dizisinin bir önceki yazısında unit test nedir kısaca onu incelemiştik. Şimdi diğer bazı test çeşitleri nelerdir ve unit testleri diğer test çeşitlerinden ayıran temel özellikler nelerdir bunları inceleyeceğiz.

Diğer Test Çeşitleri Nelerdir?

Kaliteli unit testler yazabilmemiz için unit testin ne olduğunu iyi anlamamız gerekiyor. Bunu anlayabilmemiz için de diğer test çeşitlerini bilmemiz ve unit testleri diğer testlerden ayırabilmemiz gerekiyor.

“Types of Software Testing” veya “Yazılım Test Çeşitleri” şeklinde araştırmaya başladığımızda her biri ayrı bir makale olabilecek kadar çok sayıda test çeşidi olduğunu görüyoruz. Hem iyi hem de kötü haber; bu test çeşitleri hangisi daha iyi veya hangisini kullanmalıyım şeklinde karşılaştırabileceğimiz şeyler değil. Hepsinin farklı bir amacı ve yazılım geliştirme ve devreye alma yaşam döngüsünde ayrı bir yeri var.

Birçok kaynakta test çeşitlerinin öncelikle iki kümeye ayırıldığını görmekteyiz. Ayrıca farklı kaynaklarda test çeşitlerinin ayrıldığı kümeler de değişebilmektedir.

Testleri yapan veya hazırlayan kişinin bakış açısına göre test çeşitleri gruplandığında “white-box testing” ve “black-box testing” şeklinde ikiye ayrılmaktadır.

White-box Testing: Yazılımın iç yapısının nasıl kurgulandığının ve nasıl çalıştığının bilindiği test türüdür. Yazılımın bütününü oluşturan parçaların doğru girdiler ile doğru çıktıları, davranışları veya değişiklikleri üretebildiği test edilir. Unit testler çoğunlukla bu kategoriye dahildir. Test ettiğimiz kod bir işlevi gerçekleştirirken diğer kod bileşenleri ile kurduğu etkileşimleri de test etmiş oluruz bu seviyede. Örneğin bir methodu birinci tetiklememizde veritabanına sorgu atması, sonucu cache kütüphanesine de kaydetmesi ve ikinci tetiklememizde veritabanı yerine cache üzerindeki veriyi getirmesini test etmek istediğimizde kodun işlevi kadar kullandığı diğer sınıfları veya fonksiyonları da bilmemiz gerekiyor.
Black-box Testing: Yazılımın nasıl çalıştığı bilinmeden veya önemsenmeden fonksiyonalitesi test edilir. Test yapanlar yazılımın iç yapısını bilmeden ve kaynak koda bakmadan, son kullanıcıya beklenilen faydayı üretip üretemediğini doğrularlar. Genellikle sistem seviyesi testlerdir fakat unit testlerde de bu yaklaşımın kullanıldığı uygulamalar olabilmektedir. Örnek bir blackbox testi uygulama arayüzüne girip bir butona tıklamamız ve sonrasında arayüzde gerçekleşen davranışı veya sonucu kontrol etmemiz olabilir. Böyle bir testi yaparken sistemin hangi bileşenlerden oluştuğunu hatta hangi dil ile yazıldığını dahi bilmemize gerek yoktur. Sistem bizim için tamamen bir kara kutudur.

Testin konusuna veya testin amacına göre kategorilere ayırdığımızda genellikle şu iki kategorinin kullanıldığını görüyoruz:

Fonksiyonel Testler: Fonksiyonel gereksinimler belirli girdilere veya tetikleyicilere karşılık sistemin hangi davranışları veya çıktıları üretmesini beklediğimizi belirler. Fonksiyonel testler sistemin veya sistemdeki parçaların fonksiyonel gereksinimleri doğru şekilde gerçekleştirdiğinin kontrolünün yapılmasını sağlar. Duman Testi, (Smoke Testing), Doğruluk Testi (Sanity Testing), Sistem Testi, Entegrasyon Testi, Tekrar veya Regresyon Testi (Regression Testing), vb. birçok test çeşidi bu gruba dahildir. Birim test (Unit test) de birçok kaynakta fonksiyonel test olarak kategorilendirilmektedir fakat unit testlerin yazılım geliştirme süreçlerindeki konumu konusunda epey tartışma mevcut. Bu konuya ileride tekrar geleceğiz.
Fonksiyonel Olmayan Testler: Fonksiyonel olmayan gereksinimlerin sağlanıp sağlanmadığının kontrolünü sağlar. Yük testi, performans testi, güvenlik testi, vb. birçok test çeşidi fonksiyonel olmayan gereksinimlerin testleridir.

Aşağıda birkaç farklı test çeşidinin tanımlarını örnek olarak yazacağım fakat burada yazdıklarımdan çok daha fazla test çeşidi olduğunu da önceden belirteyim. Daha fazla test çeşidini merak edip öğrenmek isterseniz yazının sonundaki kaynakçadaki linkleri takip edebilirsiniz.

Integration Test (Entegrasyon Testi): Yazılım bileşenleri arasındaki arayüzlerin (interface) ve etkileşimlerin (interaction) test edilmesi amacıyla yapılır. Geliştirilen yazılım tarafından kullanılan veritabanı, cache server, entegre olunan başka uygulamalar, farklı network bileşenleri, dosya sistemi, vb. sistemler ile geliştirilen yazılımın entegrasyonları test edilir. Unit test ile çok karıştırılmaktadır ve bazılarımız unit test yazdığımızı sanarken entegrasyon testi yazmışızdır birçok defa.
System Test (Sistem Testi): Tüm sistemin entegre olduğu dış bileşenler ile birlikte gereksinimleri yerine getirip getiremediğinin test edilmesidir. Elle manuel olarak koşulacak testler olabileceği gibi yazılım ile otomatize edilmiş test senaryoları da olabilir.
Regression Test (Regresyon/Tekrar Testi): Kodda yapılan bir değişiklik sonrası sistemin geri kalanında bir hata olup olmadığını anlamak amacıyla yapılır. Bu hatalar varolan bir özelliğin düzgün çalışmamaya başlaması veya daha önce çözülmüş bir hatanın tekrar hortlaması şeklinde gerçekleşebilir. Kodda yapılan değişikliğin veya yeni geliştirilen özelliğin değil, önceden varolan özelliklerin testidir. Genellikle önceden yazılmış ve test edilmiş test senaryolarının tekrar çalıştırılmasıyla bu test yapılır.
Acceptance Test (Kabul Testi): Uygulamayı alacak olan müşterinin kabul testidir. Müşteri uygulamayı almak için belirlediği kabul kriterlerinin karşılanıp karşılanmadığını test eder. Operasyonel kabul testi (Operational acceptance test, OAT), kullanıcı kabul testi (User acceptance test, UAT), son kullanıcı testi (End-user test) gibi birçok çeşidi vardır.
Smoke Test (Duman Testi): Uygulamanın hayati fonksiyonlarının hızlıca test edilerek daha ileri seviye testlere hazır olup olmadığını anlamak amacıyla yapılır. Uygulama hatasız şekilde ayağa kalkıyor mu, ana sayfa açılıyor mu, login olunabiliyor mu gibi basit senaryolar hızlıca test edilir. Basit senaryolarda hata varsa uygulama teste alınmaz. Duman testi isminin elektronik donanım testlerinden geldiği rivayet ediliyor. Bir elektronik devreyi elektriğe bağladığınızda duman çıktığını görürseniz elektriği kesersiniz ve başka test yapmaya ihtiyaç kalmaz mantığı ile böyle bir isim verilmiş.
Sanity Test (Doğruluk Testi): Bu test duman testine benzerlik gösterse de aynı şey değil. Doğruluk testinde, daha kapsamlı testlere geçmeden önce uygulamanın en önemli fonksiyonlarının çalışıp çalışmadığı test edilir. Duman testinde uygulamanın kalp atışı gibi hayati fonksiyonlarının testi yapılırken doğruluk testinde spesifik özellikler test edilir. Bu bakımdan doğruluk testini Inomera’da geliştirdiğimiz uygulamaları müşterinin test ekibine teslim etmeden önce test ekibine yaptığımız demoya benzetiyorum. Test ekibinin hazırladığı detaylı test senaryolarının arasından önemli özelliklere ait birkaç tane test senaryosu seçiliyor ve uygulama o testlerden başarıyla geçtikten sonra test ekibi detaylı testlere başlıyor.
Performance Test (Performans Testi): Belirli bir iş yükünün altında sistemin nasıl performans gösterdiğinin ölçülmesi işlemidir. Performans testlerinde sistemin yük altında cevap süresinde uzama oluyor mu, bellek, işlemci veya disk gibi kaynak tüketimleri ne seviyelerde artıyor, uygulamanın kullanılabilirliği ne derece etkileniyor, uygulama aynı anda kaç kullanıcıya cevap verebiliyor gibi birçok metrik ölçümlenir. Yazılım yukarı ve aşağı yönde ölçeklenebilir bir yapıdaysa yük arttığında gerçekten instance sayısı artıyor mu veya yük kesildiğinde azalıyor mu kontrolleri yapılır. Sık kullanıldığını gördüğüm ve birbirine karıştırılan iki performans testi çeşidi şunlardır:
- Load Test (Yük Testi): Belirli bir yükün/trafiğin altında sistemin ölçülmesi. Sistemin desteklemek için tasarlandığı ortalama ve/veya maksimum yük miktarı ile yapılmalıdır.
- Stress Test (Stres Testi): Sistemin taşımak için tasarlandığından daha fazla yük altında nasıl davrandığının ölçülmesidir.
Security Test (Güvenlik Testi): En kaba tabiriyle sistemin hacklenmesinin engellenmesi ve yetki gerektiren verinin sadece yetkili kullanıcılar tarafından kullanılabildiğinin görülmesi için yapılır. Hassas verilerin yetkisiz kullanıcıların eline geçmeyeceğinin kontrolüdür. Çalıştığım projelerde müşterilerin güvenlik ekipleri tarafından Fortify gibi programlar ile statik kod analizi yapıldığına ve sızma testi (Penetration Test) gibi çeşitli araçlar ile çeşitli güvenlik açıkları arandığına şahit oldum.

Yazılımda daha birçok test çeşidi, kategorisi, yöntemi, vb mevcut. Bu yazının konusunun dışına fazla çıkmamak için genel kültür amaçlı yazdığım bu başlığı burada kesiyorum.

Unit Testi Diğer Testlerden Ayıran Özellikler Nelerdir?

Bazı diğer test çeşitlerini yukarıda liste halinde gördükten sonra unit testlerin bu testlerden farkına bakalım. Buradaki bazı özellikler aynı zamanda daha sonraki yazılarda ele alacağımız “Nasıl Unit Test Yazmalıyız” gibi başlıklarda da karşımıza gereksinim olarak çıkacak.

Unit Testlerin Kapsamı Küçüktür

Öncelikle unit testlerin en büyük farkı kapsamlarıdır. Çok küçük kod parçalarını test ederler. Bir araba üreticisi olduğumuzu düşünelim. Bu arabada kullanılan vidaların uygun bir delik üzerinde dik konumda doğru yönde çevirildiğinde deliğe girip girmediğini arabadaki diğer parçalardan bağımsız şekilde test etmemiz bir unit testtir. Bu vidanın ters yönde çevirildiğinde delikten çıktığını doğrulamamız da ikinci bir unit testtir.

Unit Testleri Çalıştırmak Hızlıdır

Unit testler, her bir ufak kod değişikliğinde geliştiricilerin çok az vakitlerini harcayarak uygulamadaki tüm unit testleri baştan sona çalıştırabileceği kadar hızlıdır. Hızlı olmalıdır.

Bir geliştiriciden yeni bir özellik geliştirdiğinde elle tüm uygulama özelliklerini arayüz veya API kullanarak test etmesini bekleyemezsiniz fakat tüm birim testleri çalıştırmasını bir kural haline getirebilirsiniz.

Bir şirket sunucusuna Jenkins gibi bir continuous integration ortamı kurup her bir kod değişikliğinde tüm testlerin otomatik olarak çalışmasını ve birisi testleri patlattığında tüm ekibe e-posta göndermesini sağlayabilirsiniz.

Unit Test Kolay Yazılır

Sistem testi veya entegrasyon testi gibi testleri yazmak çok zaman alır ve daha fazla kod gerektirir. Bu tip testlerde sistemin belirli bir durumda olması simüle edilir ve bunun için veritabanına, diske, cache server’a, vb. birçok ortama kod ile data üretmek, test sonunda bu datayı temizlemek gibi işlemler yapmak gerekir.

Unit testler ise çok küçük bir kod parçası için yazıldığından çok daha kolay yazılır. Unit testlerde bağımlı olunan veritabanı veya network katmanı gibi dış faktörler tamamen ortadan kaldırılır. Bu tür bağımlılıkların davranışları da simüle edilerek sadece test edilen sınıf/metod ile ilgili senaryolar test edilmiş olur.

Unit Test Bir Test Süreci Değildir

Hatta bu başlığın daha tartışmaya açık hali “Unit test test değildir” şeklinde ve ben de katılıyorum. Unit test, test değil geliştirmedir. Yazılım geliştirme sürecinin ayrılmaz bir parçasıdır. Testçi değil geliştirici tarafından yazılır. Geliştiricinin “ben bu kodu geliştirdim ve bu kod parçasının çalıştığına kefilim” deme şeklidir. Inomera’da çalıştığım ekipte bir süredir geliştiricilerin bir işi bitirebilmesi için unit testlerinin yazılmış olması ön koşulunu uyguluyoruz. Unit testi yazılmamış geliştirmeyi geliştirilmiş saymıyoruz.

Unit Test Sistemin Çalıştığını Göstermez

Tüm unit testler başarıyla çalışsa bile bu bize sistemin doğru şekilde çalışacağını, hatta ayağa kalkacağını bile göstermez. Unit testler sistem seviyesinde bilgi vermezler. Geliştirdiğimiz ürünün fonksiyonel gereksinimlerinin karşılandığını göstermezler.

Unit test sadece geliştirilen kod parçalarının veya fonksiyonların doğru geliştirildiğini gösterir. Bu bakımdan her bir satırı unit testler tarafından kapsanmış (coverage) bir kodun hala diğer test çeşitlerine ihtiyacı vardır.

Unit testler ile doğruluğu ispatlanmış kod parçaları bir araya geldiğinde entegrasyon sorunları, iş akışı hataları veya eksik özellikleri olabilir. Bu sebeple entegrasyon testi, duman testi, doğruluk testi, fonksiyonel testler, güvenlik testleri, performans testleri, vb. tüm testler gereklidir ve unit test yaptık test ekibine ihtiyacımız yok diyemeyiz.

Test Piramidi

Hazır bu karşılaştırma işine bulaşmışken test piramidinden de bahsedelim. Test piramidi epey farklı çeşitleri olan fakat özünde aynı konuyu açıklayan bir görsel. Piramidin amacı test çeşidine göre yazılması gereken test miktarının ve bu çeşitlerdeki testlerin özelliklerinin görselleştirilmesi.

Aşağıdaki görseli Jessie Leung The Test Pyramid başlıklı blog yazısında paylaşmış. Piramidin internetteki birçok çeşidi arasından benim en beğendiğim hali bu oldu.

Piramidin altına doğru indikçe genişlemesi yazmamız gereken test miktarının artması gerektiğini göstermekte. Unit testlerin sayıca diğer testlerden fazla olması gerektiğini buradan anlıyoruz. Piramitte aşağı indikçe testlerin daha hızlı ve geliştirme maliyetinin daha düşük olması gerektiğini görüyoruz. Yukarı çıkıldığında ise hem testlerin çalışma süresi, hem de testleri geliştirmek için harcanan süre artıyor. Bu da testlerin geliştirme maliyetini arttırıyor. Bu aynı zamanda bakım (maintenance) maliyetini de arttırıyor.

Sadece unit test yazmıyorsak, entegrasyon testi ve uçtan uca (end-to-end, e2e) test de yazıyorsak, bu piramide uymamızda fayda var. Yoksa geliştirme maliyeti, bakım maliyeti ve zaman kaybı işin içinden çıkamayacağımız noktalara gelebilir.

Ek olarak bu konuda en önemli nokta bence unit testler ile diğer test çeşitlerini her ne kadar kodlayarak geliştiriyor olsak da ayrı yazmamız gerekiyor. Unit testler ile aynı test suite içerisinde geliştirdiğimiz diğer test çeşitleri geliştiricilerin unit testleri çalıştırmasını çok uzun süren bir süreç haline getirerek bir süre sonra testleri hiç çalıştırmadan kod yazan geliştiricilerin çoğalmasına sebep olacaktır.

Farklı test çeşitleri gradle ile birbirinden nasıl ayrılır konusu tamamen başka bir yazıda anlatılabilecek bir konu fakat merak edenler için Petri Kainulainen tarafından yazılmış “Getting Started With Gradle: Integration Testing” başlıklı yazıdan bir fikir edinebilirler.

Sonuç

Unit test yazı dizisinin bu yazısında diğer test çeşitlerinin bazılarının ne olduğunu ve unit testleri diğer test çeşitlerinden ayıran temel özellikleri inceledik.

Bu yazıdaki birçok madde ilerleyen başlıklarda da önümüze tekrar tekrar çıkacaktır. Unit testlerin özellikleri bunlardır dediğimizde, her yazdığımız unit test metodu doğuştan bu özelliklere sahiptir demiş olmuyoruz. Bizim kendimizin bu özelliklere sahip olacak şekilde unit test yazmamız gerekiyor.

Projelerimizin selameti için, unit test yazmayı kolaylaştırmalıyız, zorlaştırmamalıyız.

Buraya kadar okuduğunuz için teşekkürler, umarım herkese faydalı olmuştur. Bir sonraki yazımızda “Neden Unit Test Yazarız?” sorusuna cevaplar arayacağız.