Merge pull request #255 from Xronophobe/re-rita-review-chapter-12

Re: Rita's review on chapter 12

Author: hjwp

chapter_12_organising_test_files.asciidoc

@@ -1,16 +1,6 @@
 [[chapter_12_organising_test_files]]
 == Splitting Our Tests into Multiple Files, and a Generic Wait Helper
 
-// RITA: Reword/remove this warning since you have reviewed the chapter text in detail?
-.🚧 Warning, chapter update in progress
-*******************************************************************************
-This chapter is currently in the process of being rewritten for the 3e.
-
-The code listings should all be valid,
-and work with Python3.12 + Django 4,
-but I haven't reviewed the chapter text in detail yet.
-
-*******************************************************************************
 
 Back to local development!
 The next feature we might like to implement is a little input validation.
@@ -894,10 +884,15 @@ Don't forget the "Refactor" in "Red, Green, Refactor"::
     ((("Red/Green/Refactor")))
 
 Don't refactor against failing tests::
-// RITA: Why shouldn't you refactor against failing tests in general? A brief explanation would be nice here for clarity.
-    * In general!
-// RITA: Please clarify the next line. It's somewhat ambiguous. Are you saying that you should refactor against failing tests in the FT you're currently working on?
-    * But the FT you're currently working on doesn't count.
+    * The general rule is that you shouldn't mix refactoring and behaviour
+      change. Having green tests is our best guarantee that we aren't changing
+      behaviour. If you start refactoring against failing tests, it becomes much
+      harder to spot when you're accidentally introducing a regression.
+    * This applies strongly to unit tests. With functional tests, because we
+      often develop against red FTs anyway, it's sometimes more tempting to
+      refactor against failing tests. My suggestion is to avoid that temptation
+      and use an early return, so that it's 100% clear if, during a refactory,
+      you accidentally introduce a regression that's picked up in your FTs.
     * You can occasionally put a skip on a test which is testing something you
       haven't written yet.
     * More commonly, make a note of the refactor you want to do, finish what