process todos up to middle of 4

hjwp · hjwp · commit 114ff86c9504 · 2025-04-11T15:41:37.000+01:00
diff --git a/appendix_purist_unit_tests.asciidoc b/appendix_purist_unit_tests.asciidoc
@@ -374,8 +374,8 @@ for it to pass.   We've started trying to make it more isolated, so let's now go
 all the way.
 
 
-Keep the Old Integrated Test Suite Around as a Sanity Check
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Keep the Old Integrated Test Suite Around as a Sense Check
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Let's rename our old `NewListTest` class to `NewListViewIntegratedTest`,
 and throw away our attempt at a mocky test for saving the owner, putting
@@ -1864,7 +1864,7 @@ integration problems.  That's perfectly valid.
 
 On the other hand, we saw how integrated tests can warn you when you've made
 small mistakes in integrating your layers.  We could keep just a couple of
-tests around as "sanity checks", to give us a quicker feedback cycle.
+tests around as "sense checks", to give us a quicker feedback cycle.
 
 How about these three:
 
diff --git a/chapter_02_unittest.asciidoc b/chapter_02_unittest.asciidoc
@@ -166,13 +166,6 @@ which you can get a taste of by reading
 his https://web.stanford.edu/~ouster/cgi-bin/cs190-spring16/lecture.php?topic=comments[lecture notes from the chapter on comments.]
 *******************************************************************************
 
-// CSANAD: In my opinion, this would be a good place for the second commit, before we change it to use the unittest module.
-//
-//         edit:
-//         Actually, from the diff of the commit at the end of this chapter, it is clear that a commit has been made after
-//         adding the user story. But it isn't mentioned in the chapter.
-
-
 You'll notice that, apart from writing the test out as comments,
 I've updated the `assert` to look for the word ``To-Do'' instead of Django's ``Congratulations''.
 That means we expect the test to fail now.  Let's try running it.
diff --git a/chapter_03_unit_test_first_view.asciidoc b/chapter_03_unit_test_first_view.asciidoc
@@ -45,25 +45,22 @@ so do stick it out!
 
 ((("Test-Driven Development (TDD)", "additional resources")))
 ((("getting help")))
-You can always drop me an email (or try the
-https://groups.google.com/forum/#!forum/obey-the-testing-goat-book[Google
-Group]) if you get really stuck.  Happy debugging!
+You can always drop me an email[mailto:obeythetestinggoat@gmail.com]
+if you get really stuck.  Happy debugging!
 *******************************************************************************
 
 
 
-
 === Our First Django App, and Our First Unit Test
 
 ((("Django framework", "code structure in")))
 ((("Django framework", "unit testing in", id="DJFunit03")))
-Django encourages you to structure your code into _apps_: the theory is that
-one project can have many apps, you can use third-party apps developed by other
-people, and you might even reuse one of your own apps in a different
-project...although I admit I've never actually managed it myself!  Still, apps
-are a good way to keep your code organised.
-// CSANAD: I would probably mention explicitly that despite of rarely re-using
-//         our own apps, we do regularly re-use apps written by other developers.
+Django encourages you to structure your code into _apps_:
+the theory is that one project can have many apps,
+you can use third-party apps developed by other people,
+and you might even reuse one of your own apps in a different project...although
+I have to say I've never actually managed the latter, myself!
+Still, apps are a good way to keep your code organised.
 
 Let's start an app for our to-do lists:
 
@@ -144,8 +141,8 @@ You can see that, all the way through,
 the functional tests are driving what development we do from a high level,
 while the unit tests drive what we do at a low level.
 
-The functional tests don't aim to cover every single tiny detail of our
-app's behaviour, they are there to reassure us that everything is wired up correctly.
+The functional tests don't aim to cover every single tiny detail of our app's behaviour,
+they are there to reassure us that everything is wired up correctly.
 The unit tests are there to exhaustively check all the lower level details and corner cases.
 
 NOTE: Functional tests should help you build an application that actually works,
@@ -172,10 +169,12 @@ Enough theory for now—let's see how it looks in practice.
 |Provides confidence that everything is wired together correctly, works end-to-end
 |Can exhaustively check permutations, details, edge cases
 
-|===
+|Can warn about problems without telling you exactly what's wrong
+|Can point at exactly where the problem is
 
-// DAVID: Could include something about how unit tests provide more 'signal' about what went wrong.
-// SEBASTIAN: How about adding also performance aspect? That Unit Tests will generally run faster thus provide feedback earlier?
+|Slow
+|Fast
+|===
 
 === Unit Testing in Django
 
@@ -195,18 +194,19 @@ from django.test import TestCase
 ====
 
 
-Django has helpfully suggested we use a special version of `TestCase`, which
-it provides. It's an augmented version of the standard `unittest.TestCase`,
-with some additional Django-specific features, which we'll discover over the
-next few chapters.
+Django has helpfully suggested we use a special version of `TestCase`, which it provides.
+It's an augmented version of the standard `unittest.TestCase`,
+with some additional Django-specific features,
+which we'll discover over the next few chapters.
 
-You've already seen that the TDD cycle involves starting with a test that
-fails, then writing code to get it to pass. Well, before we can even get that
-far, we want to know that the unit test we're writing will definitely be
-run by our automated test runner, whatever it is.  In the case of
-_functional_tests.py_, we're running it directly, but this file made by Django
-is a bit more like magic. So, just to make sure, let's make a deliberately
-silly failing test:
+You've already seen that the TDD cycle involves starting with a test that fails,
+then writing code to get it to pass.
+Well, before we can even get that far,
+we want to know that the unit test we're writing
+will definitely be run by our automated test runner, whatever it is.
+In the case of _functional_tests.py_ we're running it directly,
+but this file made by Django is a bit more like magic.
+So, just to make sure, let's make a deliberately silly failing test:
 
 [role="sourcecode"]
 .lists/tests.py (ch03l002)
@@ -223,8 +223,8 @@ class SmokeTest(TestCase):
 ====
 
 
-Now let's invoke this mysterious Django test runner. As usual, it's a
-_manage.py_ [keep-together]#command#:
+Now let's invoke this mysterious Django test runner.
+As usual, it's a _manage.py_ [keep-together]#command#:
 
 
 [subs="specialcharacters,macros"]
@@ -250,8 +250,8 @@ FAILED (failures=1)
 Destroying test database for alias 'default'...
 ----
 
-Excellent.  The machinery seems to be working. This is a good point for a
-commit:
+Excellent.  The machinery seems to be working.
+This is a good point for a commit:
 
 
 [subs="specialcharacters,quotes"]
@@ -293,13 +293,6 @@ Django's workflow goes something like this:
   the request (this is referred to as _resolving_ the URL).
 3. The view function processes the request and returns an HTTP _response_.
 
-// CSANAD: below > "remember, a view function takes an HTTP request as input"
-//         but it wasn't _explicitly_ mentioned here. We could add something like:
-//
-//         "2. Django uses some rules to decide which _view_ function should deal with
-//            the request, and passes the request as a parameter for the view fuction. This
-//            is referred to as _resolving_ the URL."
-
 
 So, we want to test two things:
 
@@ -315,12 +308,6 @@ Let's start with the first.
 
 === Unit Testing a View
 
-// CSANAD: what do you think about sharing the thought process on how we find the specific classes to use?
-//         eg.: "Now that we know we need to make a request, let's discover what Django has to
-//         offer" then look up "http request" on docs.djangoproject.com, maybe mention the first link,
-//         `topics/http` being a manual, and the second one is a reference where we can see what classes
-//         Django has; what kind of attributes they have. We could point out the `content` before using it.
-
 ((("unit tests", "in Django", "unit testing a view", secondary-sortas="Django")))
 Open up _lists/tests.py_, and change our silly test to something like this:
 
@@ -368,10 +355,9 @@ So, to test that:
     with the words "To-Do lists" in it--because
     that's what we specified in our functional test.
 
-<5> And we can do a vague sanity check that it's valid html, by checking
+<5> And we can do a vague sense-check that it's valid html, by checking
     that it starts with an `<html>` tag which gets closed at the end.
 
-// DAVID: 'sanity check' is seen by some people as ableist, might be worth removing the 'sanity'?
 
 So, what do you think will happen when we run the tests?
 
@@ -544,12 +530,6 @@ from django.http import HttpResponse
 def home_page(request):
     return HttpResponse()
 ----
-// CSANAD: using `django.http.HttpResponse` feels like a bit of a jump to me from the atomic step-by-step
-//         approach. Of course, creating a dummy class with a `content` would be an overkill, but I think
-//         some explanation on how the HttpResponse looks like would be helpful. This, actually, could be
-//         mentioned earlier, because how do we know what we would be looking for in the response is called
-//         the `content`?
-// SEBASTIAN: HTTPResponse was in fact mentioned earlier
 ====
 
 * Tests again:
@@ -681,7 +661,7 @@ FAILED (failures=1)
 Looks like something isn't quite right.  This is the reason we have functional
 tests!
 
-Do you remember at the beginning of the chapter, we said we needed to do two things,
+Do you remember at the beginning of the chapter, we said we needed to do two things:
 firstly create a view function to produce responses for requests,
 and secondly tell the server which functions should respond to which URLs?
 Thanks to our FT, we have been reminded that we still need to do the second thing.
@@ -694,10 +674,6 @@ But we want to test more layers of the Django stack.
 Django, like most web frameworks, supplies a tool for doing just that, called the
 https://docs.djangoproject.com/en/5.2/topics/testing/tools/#the-test-client[Django Test Client].
 
-// CSANAD: it might be a little confusing first why we add a _unit_ test, considering this second
-//         test case is closer to a user's point of view. We could point out this to be one example
-//         to the problem mentioned earlier - the line between these tests being a bit vague at times.
-
 Let's see how to use it by adding a second, alternative test to our unit tests:
 
 [role="sourcecode"]
@@ -706,7 +682,7 @@ Let's see how to use it by adding a second, alternative test to our unit tests:
 [source,python]
 ----
 class HomePageTest(TestCase):
-    def test_home_page_returns_correct_html(self):
+    def test_home_page_returns_correct_html(self):  <1>
         request = HttpRequest()
         response = home_page(request)
         html = response.content.decode("utf8")
@@ -715,16 +691,14 @@ class HomePageTest(TestCase):
         self.assertTrue(html.endswith("</html>"))
 
     def test_home_page_returns_correct_html_2(self):
-        response = self.client.get("/")  # <1>
-        self.assertContains(response, "<title>To-Do lists</title>")  # <2>
+        response = self.client.get("/")  # <2>
+        self.assertContains(response, "<title>To-Do lists</title>")  # <3>
 ----
 ====
 
-// DAVID: Minor point, but I originally read this as a second test class. Personally I would find it a nicer
-// reading experience if the test method we've already seen was replaced by a `...`. Though
-// it probably would need an explanation that it's a convention we're using.
+<1> This is our existing.
 
-<1> We can access the tests client via `self.client`,
+<2> In our new test, we access the test client via `self.client`,
     which is available on any test that uses `django.test.TestCase`.
     It provides methods like `.get()` which simulate a browser making http requests,
     and take a URL as their first parameter.
@@ -815,16 +789,10 @@ of _our own application code_ which was involved with the problem.  In this
 case it's all Django code, but we'll see plenty of examples of this fifth step
 later in the book.
 
-Pulling it all together, we interpret the traceback as telling us that,
-when we tried to do our assertion on the content of the response,
-Django's test helpers failed saying that they could not do that, because
-the response is an HTML 404 "Not Found" error instead of a normal 200 OK response.
-// CSANAD: This sentence is a little too long, might be difficult to interpret. Maybe making it a list?
-//
-// Pulling it all together, we interpret the traceback as the following:
-// - when we tried to do our assertion on the content of the response for requesting the root URL `/`
-// - Django's test helpers failed saying that they could not do that
-// - because the response is an HTML 404 "Not Found" error instead of a normal 200 OK response.
+Pulling it all together, we interpret the traceback as telling us that:
+* When we tried to do our assertion on the content of the response...
+* Django's test helpers failed, saying that they could not do that...
+* Because the response is an HTML 404 "Not Found" error, instead of a normal 200 OK response.
 
 In other words, Django isn't yet configured to respond to requests for the
 root URL ("/") of our site.  Let's make that happen now.
@@ -869,13 +837,6 @@ urlpatterns = [
 ----
 ====
 
-
-WARNING: If your _urls.py_ looks different or if it mentions a function called
-    `url()` instead of `path()`, it's because you've got the wrong version of
-    Django.  This book is written for Django v5.  Take another look at
-    the <<pre-requisites>> section and get the right version before you
-    go any further.
-
 As usual, lots of helpful comments and default suggestions from Django.
 In fact, that very first example is pretty much exactly what we want!
 Let's use that, with some minor changes.
@@ -902,8 +863,8 @@ urlpatterns = [
 <3> And we wire it up here, as a `path()` entry in the `urlpatterns` global.
     Django strips the leading slash from all urls,
     so `"/url/path/to"` becomes `"url/path/to"`
-    and the base URL is just the empty string, `""`.  So this config
-    says, the "base url should point to our home page view"
+    and the base URL is just the empty string, `""`.
+    So this config says, the "base url should point to our home page view"
 
 Now we can run our unit tests again, with *`python manage.py test`*:
 
diff --git a/chapter_04_philosophy_and_refactoring.asciidoc b/chapter_04_philosophy_and_refactoring.asciidoc
@@ -307,12 +307,12 @@ $ *git commit -am "Functional test now checks we can input a to-do item"*
 
 
 
-=== The ``Don't Test Constants'' Rule, and Templates to the Rescue
+=== The "Don't Test Constants" Rule, and Templates to the Rescue
 
 
 ((("“Don’t Test Constants” rule", primary-sortas="Don’t Test Constants rule")))
 ((("unit tests", "“Don’t Test Constants” rule", secondary-sortas="Don’t Test Constants rule")))
-Let's take a look at our unit tests, 'lists/tests.py'.
+Let's take a look at our unit tests, _lists/tests.py_.
 Currently we're looking for specific HTML strings,
 but that's not a particularly efficient way of testing HTML.
 In general, one of the rules of unit testing is 'Don't test constants',
@@ -343,12 +343,14 @@ It's not _quite_ that simple, since HTML is code after all,
 and we do want something to check that we've written code that works,
 but that's our FT's job, not the unit tests'.
 
-In any case, mangling raw strings in Python
+So maybe "don't test constants" isn't the online guideline at play here,
+but in any case, mangling raw strings in Python
 really isn't a great way of dealing with HTML.
 There's a much better solution, which is to use templates.
 Quite apart from anything else,
 if we can keep HTML to one side in a file whose name ends in '.html',
 we'll get better syntax highlighting!
+
 There are lots of Python templating frameworks out there,
 and Django has its own which works very well.
 Let's use that.
@@ -487,10 +489,6 @@ Another chance to analyse a traceback:
 <4> Finally, we look for the part of our own application code that caused the
     failure: it's when we try to call `render`.
 
-// CSANAD: This was not in sync with the previous chapter's instructions. At
-//         chapter_03_unit_test_first_view.asciidoc#urlspy we said "We don’t need two
-//         separate tests,(...) and got rid of the first version.
-
 So why can't Django find the template?
 It's right where it's supposed to be, in the _lists/templates_ folder.
 
@@ -638,8 +636,16 @@ class HomePageTest(TestCase):
 // (I derived this approach for test quality evaluation from this book: https://www.manning.com/books/unit-testing?query=%20Vladimir%20Khorikov)
 
 The main point, though, is that instead of testing constants
-we're testing our implementation.
-Great!
+we're testing at a higher level of abstraction.
+Great!footnote:[
+I'm glossing over some trade-offs here.
+Yes, on the plus side, our tests no longer care about the specific content of our HTML
+so they are no longer brittle with respect to minor changes to the copy in our template.
+But on the other hand, they depend on some Django implementation details,
+so they are brittle with respect to changing the template rendering library,
+or even just renaming templates.
+So it's a compromise, as always, but `assertTemplateUsed()` is quite a common
+pattern in the Django world for a basic test of 200/GET requests]
 
 
 
diff --git a/chapter_16_advanced_forms.asciidoc b/chapter_16_advanced_forms.asciidoc
@@ -314,7 +314,7 @@ class ListAndItemModelsTest(TestCase):
 ====
 
 That's more than enough really--a check of the default values of attributes
-on a freshly initialized model object is enough to sanity-check that we've
+on a freshly initialized model object is enough to sense-check that we've
 probably set some fields up in 'models.py'.  The "item is related to list" test
 is a real "belt and braces" test to make sure that our foreign key relationship
 works.
@@ -1248,7 +1248,7 @@ class ListViewTest(TestCase):
 <6> For POST requests, make sure you test both the valid case and the invalid
     case.
 
-<7> Optionally, sanity-check that your form is rendered, and its errors are
+<7> Optionally, sense-check that your form is rendered, and its errors are
     displayed.
 ******************************************************************************
 
