From e8f81e3c3b654f3709122869a9826706975a2a8a Mon Sep 17 00:00:00 2001 From: Clemens Kofler Date: Fri, 6 Sep 2024 23:58:41 +0200 Subject: [PATCH] docs: add section on testing style that we promote (#1645) (#1649) * docs: add section on testing style that we promote (#1645) * Update README.md Co-authored-by: Matheus Sales --------- Co-authored-by: Matheus Sales --- README.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/README.md b/README.md index e960a6397..4d1b802be 100644 --- a/README.md +++ b/README.md @@ -346,6 +346,25 @@ RSpec.describe Person, type: :model do end ``` +### A Note on Testing Style + +If you inspect the source code, you'll notice quickly that `shoulda-matchers` +is largely implemented using reflections and other introspection methods that +Rails provides. On first sight, this might seem to go against the common +practice of testing behavior rather than implementation. However, as the +available matchers indicate, we recommend that you treat `shoulda-matchers` as +a tool to help you ensure correct configuration and adherence to best practices +and idiomatic Rails in your models and controllers - especially for aspects +that in your experience are often insufficiently tested, such as ActiveRecord +validations or controller callbacks (a.k.a. the "framework-y" parts). + +For testing your application's unique business logic, however, we recommend focusing on +behavior and outcomes over implementation details. This approach will better support +refactoring and ensure that your tests remain resilient to changes in how your code +is structured. While no generalized testing tool can fully capture the nuances of your +specific domain, you can draw inspiration from shoulda-matchers to write custom +matchers that align more closely with your application's needs. + ## Matchers Here is the full list of matchers that ship with this gem. If you need details