Testing Guide - martinmendozadev/StateForce GitHub Wiki

🧪 Testing Guide

This page explains how to run, write, and maintain tests for the StateForce project using Minitest, the default testing framework in Ruby on Rails.

🎯 Philosophy & Goals

Confidence: Ensure that new changes don't break existing functionality.
Documentation: Tests serve as living documentation for how components are expected to behave.
Refactoring: Enable safe refactoring of code with a safety net.
Design: Writing tests first (TDD) can help drive better software design.

📂 Types of Tests

StateForce uses the following test types, located under the test directory:

1. Unit Tests

Scope: Models, services, and validators (test/models/, test/services/, test/validators/).
Purpose: Verify that individual components work correctly in isolation.
Speed: Fastest to run.

2. Integration Tests

Scope: Controllers, mailers, jobs, and routes (test/controllers/, test/jobs/, test/routes/).
Purpose: Ensure multiple parts of the app integrate and communicate as expected.
Speed: Slower than unit tests, faster than system tests.

3. System Tests

Scope: End-to-end user flows, simulated via a browser (test/system/).
Purpose: Verify complete user interactions with the UI.
Speed: Slowest to run due to browser involvement.

▶️ Running the Test Suite

Run All Tests:

rails test

Run Specific Test Types:

rails test:system      # System tests
rails test:models      # Model tests
rails test:controllers # Controller tests

Run a Specific Test File:

rails test test/models/user_test.rb

Run a Specific Test Case by Line Number:

rails test test/models/user_test.rb:15

Run a Specific Test Case by Name:

rails test test/models/user_test.rb -n /test_should_be_valid/

⚙️ Test Environment Setup

Prepare the Test Database:

rails db:test:prepare

Create the Test Database:

rails db:create RAILS_ENV=test

Migrate the Test Database:

rails db:migrate RAILS_ENV=test

Reset the Test Database:

rails db:setup RAILS_ENV=test

✍️ Writing Tests

General Principles:

Arrange, Act, Assert (AAA): Structure tests into setup, execution, and verification phases.
Descriptive Test Names: Use test "description of behavior" do ... end.
Independence: Tests should not rely on each other or the order they are run.
Test Behavior, Not Implementation: Focus on what the code does, not how it does it.

Examples:

Model Test (Unit):

require "test_helper"

class UserTest < ActiveSupport::TestCase
  setup do
    @valid_attributes = { name: "Martin", email: "[email protected]", password: "password123" }
  end

  test "should be valid with valid attributes" do
    user = User.new(@valid_attributes)
    assert user.valid?, "User should be valid with all required attributes."
  end
end

Controller Test (Integration):

require "test_helper"

class PostsControllerTest < ActionDispatch::IntegrationTest
  setup do
    @user = users(:martin)
    sign_in @user
  end

  test "should get index" do
    get posts_url
    assert_response :success
  end
end

System Test:

require "application_system_test_case"

class UserLoginTest < ApplicationSystemTestCase
  test "user logs in successfully" do
    visit login_path
    fill_in "Email", with: "[email protected]"
    fill_in "Password", with: "password"
    click_on "Log in"
    assert_text "Welcome back!"
  end
end

🧪 Fixtures & Test Data

Rails Fixtures:

Located in test/fixtures/*.yml.
Access via users(:martin) or posts(:one).

Dynamic Factories (FactoryBot):

If adopted, factories provide greater flexibility for creating test objects.

📊 Test Coverage

Use SimpleCov to measure code coverage.

rails test
open coverage/index.html

🔄 Continuous Integration (CI)

CI runs the full test suite for all pull requests using GitHub Actions.
All tests must pass before merging.

🐛 Debugging Tests

Use puts or Rails.logger.debug for debugging.
System Test Screenshots: Configure Capybara to save screenshots on failure.

🧯 Troubleshooting

Pending Migrations: Run rails db:migrate RAILS_ENV=test.
Fixture Errors: Ensure associations and validations are correct in .yml files.
System Tests Flakiness: Update browser drivers and increase Capybara's wait time.

📚 Resources

This guide provides all the tools necessary for writing reliable and scalable tests within the StateForce project. For suggestions or improvements, feel free to open a GitHub issue.