Testing Guide

🧪 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: "hey@martinmendoza.dev", 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: "test@example.com"
    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

• Rails Testing Guide
• Capybara Documentation
• SimpleCov for Code Coverage

---

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.