Table Of ContentEarly praise for Effective Testing with RSpec 3
Ruby embraces the old Lisp idea that you should “build up a language” to address
your problem, and RSpec carries this approach into the world of testing. But
RSpec is a big toolbox, and in order to harness its full power you need a guide.
This is that guide: the bridge you need to take you from writing tests, to expressing
your design requirements in code.
➤ Avdi Grimm
Author of Confident Ruby and Exceptional Ruby and Head Chef, RubyTapas
Effective Testing with RSpec 3 does a great job of explaining both the main features
of RSpec as well as its lesser known, powerful, and often overlooked features. It’s
an essential resource for Rubyists looking to learn RSpec, or for those who use it
every day. I’ve already started using it regularly as a resource.
➤ Noel Rappin
Author of Rails 4 Test Prescriptions and Director of Development, Table XI
Myron and Ian have written the essential “missing” manual for modern RSpec,
connecting all the latest best practices for TDD and BDD. If you were having
trouble mastering modern testing with RSpec, this book will sort you out.
➤ Sam Joseph
Co-instructor on the BerkeleyX Agile Development using Ruby on Rails MOOC
and co-founder, AgileVentures Charity
Myron has been the driving force behind RSpec development for years. He is an
expert on testing practices and getting the most out of the RSpec suite. His care
and attention to detail are impeccable, and it shows in both the codebase and
this book.
➤ Xavier Shay
RSpec core team member and Payments Engineering Lead, Square
Having worked with Myron for many years on the RSpec core team, I’m very
pleased to see Effective Testing with RSpec 3. This book contains everything you
need to learn not only how RSpec works, but how to test effectively with the
framework. If you’re working with RSpec on a daily basis and looking to get better
at working with the framework, I could not recommend this book more heartily.
➤ Sam Phippen
RSpec core team member and engineer, Digital Ocean
The exercises are illustrative and challenging. The final chapter on test doubles
really synthesizes the best way to use these tools. You’ll write far more readable
and robust specs after reading this book, especially when interfacing with the
shifting sands of third-party APIs.
➤ Nigel Lowry
Company Director and Principal Consultant, Lemmata
Effective Testing with RSpec 3 is well worth a read: it is much more than a technical
reference and will make you a better developer by teaching you how to write more
expressive, robust, and maintainable tests.
➤ Alessandro Bahgat
Professional software developer
Effective Testing with RSpec 3
Build Ruby Apps with Confidence
Myron Marston
Ian Dees
The Pragmatic Bookshelf
Raleigh, North Carolina
Many of the designations used by manufacturers and sellers to distinguish their products
are claimed as trademarks. Where those designations appear in this book, and The Pragmatic
Programmers, LLC was aware of a trademark claim, the designations have been printed in
initial capital letters or in all capitals. The Pragmatic Starter Kit, The Pragmatic Programmer,
Pragmatic Programming, Pragmatic Bookshelf, PragProg and the linking g device are trade-
marks of The Pragmatic Programmers, LLC.
Every precaution was taken in the preparation of this book. However, the publisher assumes
no responsibility for errors or omissions, or for damages that may result from the use of
information (including program listings) contained herein.
Our Pragmatic books, screencasts, and audio books can help you and your team create
better software and have more fun. Visit us at https://pragprog.com.
The team that produced this book includes:
Publisher: Andy Hunt
VP of Operations: Janet Furlow
Executive Editor: Susannah Davidson Pfalzer
Development Editor: Jacquelyn Carter
Indexing: Potomac Indexing, LLC
Copy Editor: Liz Welch
Layout: Gilson Graphics
For sales, volume licensing, and support, please contact [email protected].
For international rights, please contact [email protected].
Copyright © 2017 The Pragmatic Programmers, LLC.
All rights reserved.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted,
in any form, or by any means, electronic, mechanical, photocopying, recording, or otherwise,
without the prior consent of the publisher.
Printed in the United States of America.
ISBN-13: 978-1-68050-198-8
Encoded using the finest acid-free high-entropy binary digits.
Book version: P1.0—August 2017
Contents
Foreword . . . . . . . . . . . . . . ix
Acknowledgments . . . . . . . . . . . xi
Introduction . . . . . . . . . . . . xiii
Part I — Getting Started
1. Getting Started With RSpec . . . . . . . . . 3
Installing RSpec 4
Your First Spec 5
Understanding Failure 7
Sharing Setup (But Not Sandwiches) 8
Your Turn 13
2. From Writing Specs to Running Them . . . . . . 15
Customizing Your Specs’ Output 16
Identifying Slow Examples 20
Running Just What You Need 20
Marking Work in Progress 26
Your Turn 30
3. The RSpec Way . . . . . . . . . . . . 33
What Your Specs Are Doing for You 33
Comparing Costs and Benefits 36
Different Types of Specs 39
Guidelines 40
Contents • vi
Part II — Building an App With RSpec 3
4. Starting On the Outside: Acceptance Specs . . . . . 45
First Steps 45
Deciding What to Test First 49
Checking the Response 52
Filling In the Response Body 53
Querying the Data 54
Saving Your Progress: Pending Specs 57
Your Turn 58
5. Testing in Isolation: Unit Specs . . . . . . . . 61
From Acceptance Specs to Unit Specs 62
Filling In the First Spec 65
Handling Success 69
Refactoring 72
Handling Failure 73
Defining the Ledger 75
Your Turn 77
6. Getting Real: Integration Specs . . . . . . . . 81
Hooking Up the Database 82
Testing Ledger Behavior 84
Testing the Invalid Case 89
Isolating Your Specs Using Database Transactions 92
Filling In the Behavior 94
Querying Expenses 95
Ensuring the Application Works for Real 98
Your Turn 101
Part III — RSpec Core
7. Structuring Code Examples . . . . . . . . . 107
Getting the Words Right 107
Sharing Common Logic 112
Sharing Example Groups 122
Your Turn 128
8. Slicing and Dicing Specs with Metadata . . . . . . 131
Defining Metadata 131
Contents • vii
Reading Metadata 137
Selecting Which Specs to Run 138
Sharing Code Conditionally 140
Changing How Your Specs Run 141
Your Turn 142
9. Configuring RSpec . . . . . . . . . . . 145
Command-Line Configuration 145
Setting Command-Line Defaults 149
Using a Custom Formatter 150
RSpec.configure 156
Your Turn 165
Part IV — RSpec Expectations
10. Exploring RSpec Expectations . . . . . . . . 169
Parts of an Expectation 170
How Matchers Work 174
Composing Matchers 176
Generated Example Descriptions 180
Your Turn 183
11. Matchers Included in RSpec Expectations . . . . . 187
Primitive Matchers 187
Higher-Order Matchers 197
Block Matchers 203
Your Turn 209
12. Creating Custom Matchers . . . . . . . . . 215
Delegating to Existing Matchers Using Helper Methods 216
Defining Matcher Aliases 218
Negating Matchers 219
Using the Matcher DSL 220
Defining a Matcher Class 225
Your Turn 228
Part V — RSpec Mocks
13. Understanding Test Doubles . . . . . . . . 233
Types of Test Doubles 233
Usage Modes: Mocks, Stubs, and Spies 235
Contents • viii
Origins: Pure, Partial, and Verifying Doubles 241
Your Turn 245
14. Customizing Test Doubles . . . . . . . . . 251
Configuring Responses 251
Setting Constraints 255
Your Turn 261
15. Using Test Doubles Effectively . . . . . . . . 265
Constructing Your Test Environment 265
Stubject (Stubbing the Subject) 268
Using Partial Doubles Effectively 271
Connecting the Test Subject to Its Environment 274
The Risks of Mocking Third-Party Code 281
High-Fidelity Fakes 283
Faking I/O with StringIO 284
Wrapping a Third-Party Dependency 286
Your Turn 290
A1. RSpec and the Wider Ruby Ecosystem . . . . . . 293
Bundler 293
Rake 295
Using Parts of RSpec With Other Test Frameworks 296
A2. Using RSpec with Rails . . . . . . . . . . 299
Installation 299
Using rspec-rails 300
Spec Types 301
Spec Types Cheat Sheet 302
Rails Matchers Cheat Sheet 304
A3. Matcher Cheat Sheet . . . . . . . . . . 307
Value Matchers 307
Block Matchers 311
A4. Bibliography . . . . . . . . . . . . 315
Index . . . . . . . . . . . . . . 317
