How to approach testing

By the time you reach this chapter, you have already run Minitest in your own Recipes app and you have names for the folders under test/. That is a real win. Chapter 2 gave you the map. Chapter 3 gave you the toolbox words: assertions, fixtures, Capybara, and when something heavier like WebMock might show up later.

This chapter is different on purpose. You will not type new automated tests here. You will not change the small app you generated in Chapter 1. Instead, you will clone a separate reference Recipes app and practice the habit I wish someone had handed me earlier: describe what should happen in plain language, prove it by hand, and only then think about Ruby.

I still remember opening test/models/ with a blank file and a blank mind at the same time. My brain wanted to jump straight to assertions and green dots in the terminal. The tests I wrote that way felt random. What helped was slowing down and writing the same steps I would use if I were clicking through the app myself. This chapter is that slowdown, written out.

What you will know by the end #

When you finish reading and doing the drills, you should be able to:

1. Write a scenario in four plain language pieces: who acts, what was true before, what they do, and what “good” looks like after.
2. Turn that scenario into a manual check in the browser or in bin/rails console before you open a file under test/.
3. Run a simple three-step loop (what you would check by hand, what you are changing on purpose, how you would know it passed) that maps directly to setup, action, and assertions in Chapter 5.
4. Work through Recipes practice drills in the reference sample app you clone from the minitestrails Github, then compare your thinking with hidden example answers.

None of that requires memorizing every Minitest helper yet. You are building judgment first. The syntax comes next.

Approaching a test: where do I even start? #

If you have ever stared at an empty test file and felt stuck, you are not alone. The terminal and the test runner feel like they want an answer immediately. It is easy to forget that a test is just a repeatable version of a question you already know how to ask when you are debugging by hand.

When I feel that pressure, I ask one question before I write Ruby: “How would I prove this works if I were sitting at the app right now?” Maybe that means opening the browser. Maybe it means pasting two lines into bin/rails console. Maybe it means watching a redirect after a form submit. Whatever channel I pick, I write those steps down as a short numbered list.

This guide calls that list a “scenario”. Once the scenario is clear, the test file stops being scary. You are not inventing behavior from syntax. You are encoding a check you already trust.

A small login example (manual first, code second) #

Take a boring, familiar flow: “a user logs in successfully.” Before any test "..." block, I would write what I would do by hand:

1. Visit the landing page at http://localhost:3000.
2. Click Login.
3. Confirm I am on the login page and I can see email and password fields.
4. Type an email.
5. Type a password.
6. Click Login button.
7. Confirm I land on the dashboard (or whatever page my app uses after sign-in).

Only after those steps make sense would I open test/system/ and automate them. The automated version is the robot repeating a script I already ran:

# test/system/login_test.rb
require "application_system_test_case"

class LoginTest < ApplicationSystemTestCase
  test "user logs in successfully" do
    visit root_path
    click_on "Login"
    assert_text "Login to the app"
    fill_in "Email", with: "test@email.com"
    fill_in "Password", with: "testpass1234"
    click_on "Login"
    assert_current_path dashboard_path
  end
end

Do not worry if every helper name is new. The point of this chapter is the order: manual steps first, automated script second. Chapter 5 will do that with Recipes. For now, notice how each assert_* line is just one observable outcome from the manual list.

Scenario building #

A scenario is a short story in normal language. It describes one thing that happens in your app and what should change (or stay the same) when that thing is done. It is not Ruby. It is the contract your test will enforce later.

Good scenarios are small. They force you to name one actor, one starting point, one action, and one main outcome. That sounds rigid, but it saves you from the “mega test” that signs someone up, creates a recipe, shares it by email, and deletes it in one method. When that mega test fails on step six, you still do not know which step broke.

What goes into a scenario #

Think in four pieces. You can use them as a worksheet before every test you write in later chapters:

If you skip starting point, you will fight random data later. “Sometimes it passes” often means the scenario never said whether the list was empty, whether the user was signed in, or which recipe id you were editing. If you skip expected outcome, you end up adding assertions until something turns green without knowing what you proved. I have done that. It feels productive for five minutes and painful the next day.

Write the scenario before code #

Say the feature idea is “Recipes need a title.”

A vague scenario like “Test recipes” does not help you tomorrow. A useful scenario like the following does:

• Actor: anyone creating a recipe
• Starting point: a new, unsaved recipe record
• Action: set title to blank and ask whether the record is valid
• Expected outcome: the app says the record is invalid and complains about title

That scenario can become a model test in test/models/. It can also become a browser check later if you want the error on the form. The scenario comes first; the folder comes second.

Keep the slice small #

One scenario should usually become one test "..." method with one main outcome. If your story includes sign up, email confirmation, create recipe, and share link, split it into four scenarios. You can always add more tests. You cannot easily debug one long test when it fails in the middle and you are not sure which step broke.

Where the scenario lives in test/ folder #

Once the story is clear, use Chapter 2 as the backstop:

• Outcome is mostly data and Ruby rules → test/models/
• Outcome needs HTTP, sessions, or redirects → test/controllers/ or test/integration/
• Outcome needs what a human sees in a real browser → test/system/

Chapter 5 walks through one model scenario, your first HTTP integration tests, and one browser smoke in your own app. The pattern stays the same after that: scenario first, folder second, code last.

Manual testing before automated testing #

Manual testing means you run the scenario yourself before you lock it into Minitest. You are not replacing automation. You are proving the scenario is real and observable.

Automated tests are expensive in time and attention. They are worth it once you know what “correct” means. While you are still figuring that out, manual checks are cheap. I still do them when a feature is new or when a test fails and I need to remember what I was trying to prove.

You are not “only doing QA.” Developers run these micro checks all day: one console line, one form submit, one redirect. The difference in this guide is that you write the steps down on purpose instead of keeping them in your head.

Types of manual channels #

Pick the smallest channel that can falsify your scenario. If console already proves the validation, you do not need a browser for the same rule.

Turn a scenario into a manual script #

Take the blank title scenario and write numbered steps you could hand to a teammate:

1. Start the app (bin/rails server or bin/dev) for a UI check, or use console only for a model-only rule.
2. Create a recipe with an empty title (form submit or Recipe.new(title: "") in rails console).
3. Observe: invalid record, error on title. For a full app check in the browser, confirm a new row was not added to the list.

If step 3 is unclear, fix the app or fix the scenario before you write assert_* lines. Later chapters assume you could have done this by hand. The automated test is the robot that repeats your check.

What manual testing is not #

Manual checks do not replace a test suite in CI. They are not an excuse to skip edge cases once the happy path works. They are not only for staging. They are how you earn the right to automate.

Automated tests are the repeatable version of a manual script you already trust.

The habit loop #

Once the scenario is clear and you have a manual script, translate it in three passes. I still use this on features I have shipped for years.

1. What would I check by hand?

Copy your manual steps here. Be boring and specific. “Click Save” is weaker than “submit the new recipe form with title left blank and look for an error on the title field.”

If you cannot check it by hand, you are not ready to automate it yet. Build or spike the feature first.

2. What am I changing on purpose?

Write only the inputs and conditions that matter for this check. Optional fields you are not testing can stay out of the story.

For example, if the scenario is “blank title is rejected”, what you are changing on purpose is the title (empty). You do not need to mention prep time, servings, or description in that scenario unless you are actually testing those fields. Leaving them out does not mean they are forbidden in the app. It means they are optional for this test and would only add noise.

Same idea elsewhere: if you are testing “guest cannot open edit”, you need signed-out user and an edit URL. You do not need to spell out every field on the recipe show page unless the test is about that page content.

3. How will I know it passed?

List observable results: valid? is false, response is 422, page shows “can’t be blank”, count did not change. Each line becomes an assertion in Chapter 5.

Carry the scenario into the test file #

When you open test/models/recipe_test.rb next, keep the scenario visible. Paste the story in comments above the test method. Delete the comments later if the code reads clearly on its own. The point is to never start from a blank file and a blank mind at the same time.

Here is the blank title scenario carried into a file you will write soon in Chapter 5. You do not need to type this yet. Read how the comments line up with the Ruby:

# test/models/recipe_test.rb
require "test_helper"

class RecipeTest < ActiveSupport::TestCase
  # Scenario: Recipes need a title
  # Actor: anyone creating a recipe
  # Starting point: a new, unsaved recipe record
  # Action: set title to blank and check valid?
  # Expected outcome: invalid; error on title mentions blank
  #
  test "rejects a blank title" do
    recipe = Recipe.new(title: "")
    assert_not recipe.valid?
    assert_includes recipe.errors[:title], "can't be blank"
  end
end

The comment block is your checklist. The three lines inside test "..." are the robot version. When a test fails, compare the failure to the comments first, not to a vague memory of what you meant to test.

You do not need to memorize assertion syntax yet. Chapter 3 lists the helpers in a table; subsequent chapters walk through assertions line by line when you write your first real test.

Practice: scenario drills #

Enough of the theory, let’s dive into some practical drill now. I built a reference Recipes app on GitHub so you can practice without touching the smaller app from Chapter 1. Clone it, run bin/setup, and walk through the drills below. When you are done with this chapter, you can delete the clone if you want. Your Chapter 1 app stays where it is for Chapter 5.

The reference clone already has sign-in and guest read-only rules (browse recipes, but no create/edit/destroy without logging in). Your own app from Chapter 5 will stay simpler for several chapters: guests can still use full CRUD until you add authentication in Chapter 11. That split is intentional so drills here feel like a real app while your test chapters do not overwhelm you with sessions too early.

git clone git@github.com:minitestrails/recipe-scenario-drill.git
cd recipe-scenario-drill
bin/setup

How to use each group #

The groups go from simple to complex. Model rules use bin/rails console only and do not need a browser session. Browser drills assume you are signed in as Alice, which the next section walks through. Authorization is last and is the only place you change users on purpose.

Login to the app #

Do this once after bin/setup and before you open the first browser drill (everything from Sign in through Share email in the table above). The reference clone already has authentication and authorization pre-configured. Guests can browse recipes, but creating, editing, destroying, and most of the drills that change data expect a signed-in user. If you skip login, you will hit redirects or missing buttons and think the drill is broken when the app is doing what it was built to do.

Signing in once also saves time so you do not have to keep logging in and out between practice drills. Stay logged in as Alice (alice@example.com) for every browser drill through Share email. You only sign out or switch to Bob in the Authorization group at the end, when the story is explicitly about two different users or a guest who must not edit someone else’s recipe.

1. Start the clone with bin/dev or bin/rails server and open the app in your browser (usually http://localhost:3000). If you followed instructions to clone the app then your app should already be running without you needing to do anything else.
2. Click on the “Sign in” button to open the sign-in page.
3. At the bottom of the sign-in page, the app lists test accounts with emails and passwords for local development. Use alice@example.com and the password shown there for Alice.
4. Submit the form and confirm you are signed in. You should see “Sign out” button in the UI.
5. Leave that session open while you work through List and read, Create, Update and destroy, Nested ingredients, Steps, and Share email. Do not sign out between those groups unless a drill tells you to.

When you reach the Authorization group, you will sign in as Bob or sign out to play a guest on purpose. Until then, treat “already logged in as Alice” as part of your starting point for each browser scenario.

Scenario Practice Drills #

Now we will practice scenario drills. For each group, work in this order for making the drill effective:

1. Start with the first (main) drill in the group.
2. Click Open worksheet (write your answer first) and fill in actor, starting point, action, expected outcome, manual steps, and which folder under test/ you would use later (for example test/models/).
3. Run those manual steps in the cloned app. Use bin/dev or bin/rails server for browser work. Use bin/rails console for model rules.
4. When you are done, click Show example answer and compare. Try not to peek before you run the steps yourself.
5. Do the shorter follow-up drills in the same group. They reuse the same pattern with a different edge case.

Do not write Minitest in this chapter. You are training judgment and manual proof. The robot (minitest / automated test) comes in the next chapter.

You just practised the scenario-first habit, which is what makes later automated tests easier to trust.

How the rest of the guide uses this chapter #

Everything after this chapter assumes you are not jumping straight from a feature idea to assert_* lines. The order is deliberate, and it matches how most of us actually debug: you decide what should happen, you prove it by hand once, and only then you ask Minitest to repeat that proof on every run.

That is not slower for its own sake. It is slower in the moment so you waste less time later. When a test fails, the failure message is only useful if you already know which story you were telling. “Expected true, got false” does not help if you never wrote down who was signed in or what the page was supposed to show.

The guide keeps the same three passes in later chapters. They map cleanly to what you practiced here:

1. Scenario in plain language (this chapter). Who acts, what was true before, what they do, what “good” looks like after. You wrote that in the drill worksheets and in the habit loop above.
2. Manual check in the browser or console (this chapter, using the reference clone). You ran the steps yourself before peeking at the example answers. That is the proof the scenario is real.
3. Automated test in the right folder under test/ (starting in Chapter 5, in your own Recipes app). The test file is the robot script for a manual check you already trust.

Chapter 5 is where the robot shows up in your Recipes app you generated in Chapter 1. You will still write the scenario first, then automate. Fixtures, system tests, mailers, and jobs later all reuse the same habit. The folder under test/ changes (models vs integration vs system vs mailers), but the order does not.

Two apps, one habit. This chapter used the reference clone so you could practice auth, ownership, and share-email flows without your own app having those features yet. From Chapter 5 onward you change your Recipes app and add tests there. When a later chapter says “write the scenario first,” it means the same worksheet questions you used in the drills, not a new ritual though you will write them in the test file itself instead of a worksheet.

When a test feels too big, too vague, or stuck on the wrong failure, come back here before you add more assertions. Shrink the story to one actor, one starting point, one action, and one outcome. Run the manual steps again in the browser or console. If you cannot prove it by hand, the test is not ready yet.

Chapters on writing your first test, CRUD system tests, mailers, background jobs, and authorization will point you at this chapter on purpose. They will not re-teach scenario building from scratch every time. They will remind you to use the loop you already practiced.

What is next #

You have the map from Chapter 2, the toolbox names from Chapter 3, and a repeatable loop from this chapter. You also have muscle memory from the drills: who acts, what was true before, what they did, what should have happened, and where that story would live under test/.

Next you will automate your first scenarios in the Recipes app you generated in Chapter 1: a model validation that fails then passes, integration tests for Recipes over HTTP, and one system smoke test. Same habit, new file extensions.

Continue to Your first test.