Merge pull request #383 from Xronophobe/csanad--review-chapter-27

Csanád's review of chapter 27 and the AI Preface

Author: hjwp

chapter_27_hot_lava.asciidoc

@@ -11,7 +11,8 @@ and the end of our journey with this to-do app and its tests.
 Let's recap our test structure so far:
 
 * We have a suite of functional tests that use Selenium to test that the whole app really works.
-  On several occasions, the FTs have saved us from shipping broken code—whether it was broken CSS, a broken database due to filesystem permissions, or broken email integration.
+  On several occasions, the FTs have saved us from shipping broken code--whether it was broken CSS,
+  a broken database due to filesystem permissions, or broken email integration.
 
 * And we have a suite of unit tests that use Django test client, enabling us to test-drive our code for models, forms, views, URLs, and even (to some extent) templates.
   They've enabled us to build the app incrementally, to refactor with confidence,
@@ -250,11 +251,23 @@ Functional/end-to-end tests::
     including all dependencies and connected external systems.
     An FT is the ultimate test that it all hangs together,
     and that things are "really" going to work.
-
+    // CSANAD: I find the expression 'things are "really" going to work' too vague.
+    // I would rather mention User Stories here, since they very often can be turned into
+    // functional/end-to-end tests: they are worded similarly and they both cover specific
+    // functionalities that are valuable for a given user (edit: well, you talk
+    // about this below, under "On Acceptance Tests").
+    // Furthermore, I would maybe give an example for each:
+    // "Francis starts a new list by entering a new item."
 
 Integration tests::
     The purpose of an integration test should be to check that the code
     you write is integrated correctly with some "external" system or dependency.((("integration tests")))
+    // CSANAD: this one is more tricky to find integration tests for, since we
+    // didn't create separate 'integration tests'. Maybe an example could be
+    // checking whether Bootstrap is loaded correctly, or perhaps the email.
+    // Something like that would be helpful in my opinion, especially because
+    // we promised in Chapter 05 ("Unit Tests Versus Integration Tests, and the Database")
+    // that we would further clarify the difference.
 
 
 (True) unit tests::
@@ -263,10 +276,16 @@ Integration tests::
     The ideal unit test is fully isolated((("unit tests")))
     from everything external to the unit under test,
     such that changes to things outside cannot break the test.
+    // CSANAD: I was trying to find an example of a pure unit test. I recall
+    // we may have had some helper function at some point, for which there was
+    // no need to use Django's TestCase but I can't find it. Maybe I'm
+    // remembering wrong.
 
 The canonical advice is that you should aim to have the majority of your tests
 be unit tests, with a smaller number of integration tests,
 and an even smaller number of functional tests—as in the classic "test pyramid" of <<test_pyramid>>.
+// CSANAD: in the HTML, it read: "as in the classic 'Test Pyramid' of The Test Pyramid".
+
 
 [[test_pyramid]]
 .The test pyramid
@@ -291,6 +310,10 @@ Top layer: a minimal set of functional/end-to-end tests::
     But because they are the slowest and most brittle,
     we want as few of them as possible.
 
+// CSANAD: I think explaining the layers after having explained the types of
+// tests just above it, seems a little redundant. I wonder if we should combine
+// them.
+
 
 [[acceptance_tests]]
 .On Acceptance Tests
@@ -338,6 +361,8 @@ Ed Jung calls this https://oreil.ly/sm16H[Mock Hell].
 This isn't to say that mocks are always bad!
 But just that, from experience,
 attempting to use them as your primary tool for decoupling
+// CSANAD: I think we could actually argue that by using mocks, we
+// accept that the code is tightly coupled with its dependencies.
 your tests from external dependencies is not a viable solution;
 it carries costs that often outweigh the benefits.
 
@@ -350,8 +375,9 @@ NOTE: I'm glossing over the use of mocks in a London-school
 
 The actual solution to the problem isn't obvious from where we're standing. It lies in rethinking the architecture of our application.((("architectures of applications")))
 In brief, if we can _decouple_ the core business logic of our application
-from its dependencies, then we can write true unit tests for it
-that do not depend on those, um, dependencies.((("business logic, decoupling from dependencies")))((("dependencies", "decoupling business logic from")))
+from its dependencies, then we can write true, isolated unit tests for it
+that do not depend on those, um, dependencies.
+((("business logic, decoupling from dependencies")))((("dependencies", "decoupling business logic from")))
 
 Integration tests are most necessary at the _boundaries_ of a system--at
 the points where our code integrates with external systems—like the database, filesystem, network, or a UI.((("boundaries between system components", "integration tests and")))
@@ -389,7 +415,14 @@ call this approach "Ports and Adapters" (see <<ports-and-adapters>>).
 .Ports and Adapters (diagram by Nat Pryce)
 image::images/tdd3_2702.png["Illustration of ports and adapaters architecture, with isolated core and integration points"]
 
-This pattern, or variations of it, are known as
+
+// CSANAD: I haven't found the original diagram by Nat Pryce. I would recommend
+// maybe a making the next header "Functional Core, Imperative Shell" formatted
+// differently, making it more obvious that it's an explanation of the diagram.
+// Or, we could just add a "Legend" under the diagram, explaining what the
+// nodes, arrows and different shades of the layers depict.
+
+This pattern, or variations on it, are known as
 "Hexagonal Architecture" (by Alistair Cockburn),
 "Clean Architecture" (by Robert C. Martin, aka Uncle Bob),
 or "Onion Architecture" (by Jeffrey Palermo).
@@ -535,7 +568,7 @@ What that means is that some of the more advanced uses of TDD,
 particularly the interplay between testing and architecture,
 have been beyond the scope of this book.
 
-But I hope that this chapter has been a bit a guide to find your way
+But I hope that this chapter has been a bit of a guide to find your way
 around that topic as your career progresses.
 
 [role="pagebreak-before less_space"]
@@ -589,3 +622,9 @@ A take from the world of functional programming::
     _Grokking Simplicity_ by Eric Normand
     explores the idea of "Functional Core, Imperative Shell".
     Don't worry; you don't need a crazy functional programming language like Haskell or Clojure to understand it—it's written in perfectly sensible JavaScript.
+    // CSANAD: Shouldn't we provide a link to this book too?
+    // https://www.oreilly.com/library/view/grokking-simplicity/9781617296208/
+    // O'Reilly resources usually have a different kind of link though.
+
+
+Happy testing!