Merge pull request #218 from Xronophobe/update--chapter-12

Update chapter 12

Author: Xronophobe

chapter_12_organising_test_files.asciidoc

@@ -159,7 +159,7 @@ and wait until we're back to a fully passing test suite before refactoring.
 
 Kent Beck has a book-length exploration of the tradeoffs
 of refactor-now vs refactor-later, called
-https://learning.oreilly.com/library/view/tidy-first/9781098151232/[Tidy First?]
+https://www.oreilly.com/library/view/tidy-first/9781098151232/[Tidy First?]
 **********************************************************************
 
 
@@ -262,6 +262,9 @@ class FunctionalTest(StaticLiveServerTestCase):
 NOTE: Keeping helper methods in a base `FunctionalTest` class
     is one useful way of preventing duplication in FTs.
     Later in the book (in <<chapter_page_pattern>>) we'll use the "Page pattern",
+// CSANAD: is this reference to the chapter "The Token Social Bit, the Page
+//         Pattern, and an Exercise for the Reader" as chapter_page_pattern
+// still clear in print?
     which is related, but prefers composition over inheritance--always a good thing.
 
 Our first FT is now in its own file,
@@ -291,7 +294,7 @@ Some people like to use them a lot in Django code
 (e.g., your views might import models using `from .models import List`,
 instead of `from list.models`).
 Ultimately this is a matter of personal preference.
-I prefer to use relative imports only when I'm super-super
+I prefer to use relative imports only when I'm super-super confident
 that the relative position of the thing I'm importing won't change.
 That applies in this case because I know for sure
 all the tests will sit next to _base.py_, which they inherit from.
@@ -378,14 +381,16 @@ AssertionError: write me!
 Brilliant--no need to sit around waiting for all the FTs
 when we're only interested in a single one.
 Although we need to remember to run all of them now and again, to check for regressions.
-Later in the book we'll see how to give that task over to an automated Continuous Integration loop.
-For now, let's commit!
+Later in the book we'll set up a Continuous Integration (CI) server to run all the tests automatically,
+for example every time we push to master.
+For now, a good prompt for running all the tests is "just before you do a commit",
+so let's get into that habit now:
 
 [subs="specialcharacters,quotes"]
 ----
 $ *git status*
 $ *git add src/functional_tests*
-$ *git commit -m "Moved Fts into their own individual files"*
+$ *git commit -m "Moved FTs into their own individual files"*
 ----
 
 Great.  We've split our functional tests nicely out into different files.
@@ -547,6 +552,8 @@ Like this:
 ((("Python 3", "lambda functions")))
 `lambda` in Python is the syntax for making a one-line, throwaway function--it
 saves you from having to use `def..():` and an indented block:
+// CSANAD: the `def..` and the `():` renders apart from each other, on two
+//         lines. I couldn't find out how to keep them together.
 
 [role="skipme"]
 [source,python]
@@ -561,9 +568,10 @@ saves you from having to use `def..():` and an indented block:
 5
 ----
 
-In our case, we're using it to transform a bit of code that would otherwise be
-executed immediately into a function that we can pass as an argument,
+In our case, we're using it to transform a bit of code--that would otherwise be
+executed immediately--into a function that we can pass as an argument,
 and that can be executed later, and multiple times:
+// CSANAD: I think it's easier to read like this.
 
 [role="skipme"]
 [source,python]
@@ -621,18 +629,24 @@ FAILED (errors=1)
 The order of the traceback is a little confusing, but we can more or less follow
 through what happened:
 
-<1> At line 15 in our FT, we go into our `self.wait_for` helper,
-    passing it the `lambda`-ified version of the `assertEqual`.
+<1> In our FT, we call our `self.wait_for` helper, where we pass
+    the `lambda`-ified version of `assertEqual`.
 
 <2> We go into `self.wait_for` in _base.py_,
-    where we can see that we're inside `fn()`,
-    which is the name for our lambda inside the helper.
+    where we're calling (and returning) `fn()`, which refers to the passed
+    lambda function encapsulating our test assertion.
 
 <3> To explain where the exception has actually come from,
     the traceback takes us back into _test_list_item_validation.py_
     and inside the body of the `lambda` function,
-    and tells us that it the attempt to find the `.invalid-feedback` element
+    and tells us that it was attempt to find the `.invalid-feedback` element
     that failed.
+// CSANAD: I changed two things here:
+//   First, I think it's better to remove the specific line number which may
+// vary due to personal formatting preferences (and following the pep8 puts
+// this on line 16 for me)
+//   Secondly, we say we go into self.wait_for in step#2. Here, in step#1 we
+// are only calling it. Overall, I tried making it clearer a bit.
 
 
 ((("functional programming")))
@@ -767,7 +781,8 @@ $ *cp src/lists/tests/test_views.py src/lists/tests/test_models.py*
 ----
 
 And strip _test_models.py_ down
-to being just the one test--it means it needs far fewer imports:
+to being just the one test:
+// CSANAD: the imports are unchanged, only the view-related tests are removed
 
 [role="sourcecode"]
 .src/lists/tests/test_models.py (ch11l016)
@@ -792,10 +807,10 @@ Whereas _test_views.py_ just loses one class:
 ----
 --- a/src/lists/tests/test_views.py
 +++ b/src/lists/tests/test_views.py
-@@ -103,34 +104,3 @@ class ListViewTest(TestCase):
-         self.assertNotContains(response, "other list item 1")
-         self.assertNotContains(response, "other list item 2")
+33 +74,3 @@ class NewItemTest(TestCase):
+         )
 
+         self.assertRedirects(response, f"/lists/{correct_list.id}/")
 -
 -
 -class ListAndItemModelsTest(TestCase):