more on working incrementally, some text/whitespace reflowing

Author: hjwp

chapter_working_incrementally.asciidoc

@@ -4,21 +4,20 @@ Working Incrementally
 
 ((("Test-Driven Development (TDD)", "adapting existing code incrementally", id="TDDadapt07")))
 ((("Testing Goat", "working state to working state")))
-Now let's address our real problem, which is that our design only allows for
-one global list.  In this chapter I'll demonstrate a critical TDD technique:
-how to adapt existing code using an incremental, step-by-step process which
-takes you from working state to working state. Testing Goat, not Refactoring
-Cat.
+Now let's address our real problem, which is that our design only allows for one global list.
+In this chapter I'll demonstrate a critical TDD technique:
+how to adapt existing code using an incremental, step-by-step process
+which takes you from working state to working state.
+Testing Goat, not Refactoring Cat.
 
 
 Small Design When Necessary
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ((("small vs. big design", id="small07")))
 ((("multiple lists testing", "small vs. big design", id="MLTsmall07")))
-Let's have a think about how we want support for multiple lists to
-work.  Currently the FT (which is the closest we have to a design document)
-says this:
+Let's have a think about how we want support for multiple lists to work.
+Currently the FT (which is the closest we have to a design document) says this:
 
 [role="sourcecode currentcontents dofirst-ch07l000"]
 .functional_tests/tests.py
@@ -36,9 +35,10 @@ says this:
 ----
 ====
 
-But really we want to expand on this, by saying that different users
-don't see each other's lists, and each get their own URL as a way of
-going back to their saved lists.  What might a new design look like?
+But really we want to expand on this,
+by saying that different users don't see each other's lists,
+and each get their own URL as a way of going back to their saved lists.
+What might a new design look like?
 
 
 
@@ -49,34 +49,33 @@ Not Big Design Up Front
 ((("Big Design Up Front")))
 ((("minimum viable applications")))
 TDD is closely associated with the agile movement in software development,
-which includes a reaction against 'Big Design Up Front', the
-traditional software engineering practice whereby, after a lengthy requirements
-gathering exercise, there is an equally lengthy design stage where the
-software is planned out on paper. The agile philosophy is that you learn more
-from solving problems in practice than in theory, especially when you confront
-your application with real users as soon as possible.
-Instead of a long up-front design phase, we try to put a 'minimum viable
-application' out there early, and let the design evolve gradually based on
-feedback from real-world usage.
-
-
-But that doesn't mean that thinking about design is outright banned! In the
-last big chapter we saw how just blundering ahead without thinking can
-'eventually' get us to the right answer, but often a little thinking about
-design can help us get there faster. So, let's think about our minimum viable
-lists app, and what kind of design we'll need to deliver it:
+which includes a reaction against 'Big Design Up Front',
+the traditional software engineering practice whereby,
+after a lengthy requirements gathering exercise,
+there is an equally lengthy design stage where the software is planned out on paper.
+The agile philosophy is that you learn more from solving problems in practice than in theory,
+especially when you confront your application with real users as soon as possible.
+Instead of a long up-front design phase,
+we try to put a 'minimum viable application' out there early,
+and let the design evolve gradually based on feedback from real-world usage.
+
+
+But that doesn't mean that thinking about design is outright banned!
+In the last big chapter we saw how just blundering ahead without thinking can 'eventually' get us to the right answer,
+but often a little thinking about design can help us get there faster.
+So, let's think about our minimum viable lists app,
+and what kind of design we'll need to deliver it:
 
 * We want each user to be able to store their own list--at least one, for now.
-* A list is made up of several items, whose primary attribute is a bit of
-descriptive text.
-* We need to save lists from one visit to the next.  For now, we can give
-each user a unique URL for their list.  Later on we may want some way of
-automatically recognising users and showing them their lists.
+* A list is made up of several items, whose primary attribute is a bit of descriptive text.
+* We need to save lists from one visit to the next.
+  For now, we can give each user a unique URL for their list.
+  Later on we may want some way of automatically recognising users and showing them their lists.
 
-To deliver the "for now" items, it sounds like we're going to store
-lists and their items in a database.  Each list will have a unique URL,
-and each list item will be a bit of descriptive text, associated with a
-particular list.
+To deliver the "for now" items,
+it sounds like we're going to store lists and their items in a database.
+Each list will have a unique URL,
+and each list item will be a bit of descriptive text, associated with a particular list.
 
 
 YAGNI!
@@ -85,19 +84,20 @@ YAGNI!
 
 ((("Test-Driven Development (TDD)", "philosophy of", "YAGNI")))
 ((("YAGNI (You ain’t gonna need it!)")))
-Once you start thinking about design, it can be hard to stop. All sorts of
-other thoughts are occurring to us--we might want to give each list
-a name or title, we might want to recognise users using usernames and
-passwords, we might want to add a longer notes field as well as short
-descriptions to our list, we might want to store some kind of ordering, and so
-on.  But we obey another tenet of the agile gospel:  "YAGNI" (pronounced
-yag-knee), which stands for "You ain't gonna need it!"  As software
-developers, we have fun creating things, and sometimes it's hard to resist
-the urge to build things just because an idea occurred to us and we 'might'
-need it.  The trouble is that more often than not, no matter how cool the idea
-was, you 'won't' end up using it. Instead you have a load of unused code,
-adding to the complexity of your application. YAGNI is the mantra we use to
-resist our overenthusiastic creative urges.
+Once you start thinking about design, it can be hard to stop.
+All sorts of other thoughts are occurring to us--we might want to give each list a name or title,
+we might want to recognise users using usernames and passwords,
+we might want to add a longer notes field as well as short descriptions to our list,
+we might want to store some kind of ordering, and so on.
+But we obey another tenet of the agile gospel:  "YAGNI" (pronounced yag-knee),
+which stands for "You ain't gonna need it!"
+As software developers, we have fun creating things,
+and sometimes it's hard to resist the urge to build things
+just because an idea occurred to us and we 'might' need it.
+The trouble is that more often than not, no matter how cool the idea was,
+you 'won't' end up using it.
+Instead you have a load of unused code, adding to the complexity of your application.
+YAGNI is the mantra we use to resist our overenthusiastic creative urges.
 
 
 REST (ish)
@@ -113,7 +113,7 @@ How should the user interact with ++List++s and their ++Item++s using a web brow
 Representational State Transfer (REST) is an approach to web design that's
 usually used to guide the design of web-based APIs. When designing a
 user-facing site, it's not possible to stick 'strictly' to the REST rules,
-but they still provide some useful inspiration (skip ahead to 
+but they still provide some useful inspiration (skip ahead to
 <<appendix_rest_api>> if you want to see a real REST API).
 
 REST suggests that we have a URL structure that matches our data structure,
@@ -160,11 +160,10 @@ In summary, our scratchpad for this chapter looks something like this:
 *****
 
 
+
 Implementing the New Design Incrementally Using TDD
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-
-
 ((("Test-Driven Development (TDD)", "overall process of")))
 ((("multiple lists testing", "incremental design implementation")))
 How do we use TDD to implement the new design? Let's take another look at
@@ -175,7 +174,7 @@ At the top level, we're going to use a combination of adding new functionality
 application--that is, rewriting some of the existing implementation so that it
 delivers the same functionality to the user but using aspects of our new
 design. We'll be able to use the existing functional test to verify we don't
-break what already works, and the new functional test to drive the new 
+break what already works, and the new functional test to drive the new
 features.
 
 At the unit test level, we'll be adding new tests or modifying existing ones to
@@ -214,7 +213,7 @@ def test_can_start_a_list_for_one_user(self):
     self.wait_for_row_in_list_table('1: Buy peacock feathers')
 
     # Satisfied, she goes back to sleep
-    
+
 
 def test_multiple_users_can_start_lists_at_different_urls(self):
     # Edith starts a new to-do list
@@ -291,8 +290,8 @@ using the convention of double-hashes (`##`) to indicate
     User Story. They're a message to our future selves, which might otherwise
     be wondering why the heck we're quitting the browser and starting a new
     one...
-    
-    
+
+
 
 Other than that, the new test is fairly self-explanatory. Let's see how we do
 when we run our FTs:
@@ -661,7 +660,7 @@ Green? Refactor
 
 
 ((("multiple lists testing", "refactoring")))((("refactoring")))((("Red/Green/Refactor")))Time
-for a little tidying up.  
+for a little tidying up.
 
 In the 'Red/Green/Refactor' dance, we've arrived at green, so we should see
 what needs a refactor.  We now have two views, one for the home page, and one
@@ -685,7 +684,7 @@ class ItemModelTest(TestCase):
 
 ----
 
-We can definitely delete the `test_displays_all_list_items` method from 
+We can definitely delete the `test_displays_all_list_items` method from
 `HomePageTest`; it's no longer needed.  If you run *`manage.py test lists`*
 now, it should say it ran 6 tests instead of 7:
 
@@ -874,7 +873,7 @@ are we with our own to-do list?
 
 We've 'sort of' made progress on the second item, even if there's still only
 one list in the world. The first item is a bit scary.  Can we do something
-about items 3 or 4?  
+about items 3 or 4?
 
 Let's have a new URL for adding new list items.  If nothing else, it'll
 simplify the home page view.
@@ -942,7 +941,7 @@ code was 404 (expected 302)
 ----
 
 The first failure tells us we're not saving a new item to the database, and the
-second says that, instead of returning a 302 redirect, our view is returning 
+second says that, instead of returning a 302 redirect, our view is returning
 a 404. That's because we haven't built a URL for '/lists/new', so the
 `client.post` is just getting a "not found" response.
 
@@ -1091,19 +1090,22 @@ Oops:
 ----
 ERROR: test_can_start_a_list_for_one_user
 [...]
-  File "...python-tdd-book/functional_tests/tests.py", line 57, in
+  File "...python-tdd-book/functional_tests/tests.py", line 58, in
 test_can_start_a_list_for_one_user
     self.wait_for_row_in_list_table('1: Buy peacock feathers')
-  File "...python-tdd-book/functional_tests/tests.py", line 23, in
+  File "...python-tdd-book/functional_tests/tests.py", line 24, in
 wait_for_row_in_list_table
     table = self.browser.find_element(By.ID, 'id_list_table')
+            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+[...]
 selenium.common.exceptions.NoSuchElementException: Message: Unable to locate
 element: [id="id_list_table"]
 
+
 FAIL: test_multiple_users_can_start_lists_at_different_urls (functional_tests.t
 ests.NewVisitorTest.test_multiple_users_can_start_lists_at_different_urls)
 [...]
-  File "...python-tdd-book/functional_tests/tests.py", line 79, in
+  File "...python-tdd-book/functional_tests/tests.py", line 80, in
 test_multiple_users_can_start_lists_at_different_urls
     self.wait_for_row_in_list_table('1: Buy peacock feathers')
 selenium.common.exceptions.NoSuchElementException: Message: Unable to locate
@@ -1184,16 +1186,16 @@ present the changes in the form of a diff:
  from django.test import TestCase
 -from lists.models import Item
 +from lists.models import Item, List
- 
- 
+
+
  class HomePageTest(TestCase):
 @@ -44,22 +44,32 @@ class ListViewTest(TestCase):
- 
- 
- 
+
+
+
 -class ItemModelTest(TestCase):
 +class ListAndItemModelsTest(TestCase):
- 
+
      def test_saving_and_retrieving_items(self):
 +        list_ = List()
 +        list_.save()
@@ -1202,18 +1204,18 @@ present the changes in the form of a diff:
          first_item.text = 'The first (ever) list item'
 +        first_item.list = list_
          first_item.save()
- 
+
          second_item = Item()
          second_item.text = 'Item the second'
 +        second_item.list = list_
          second_item.save()
- 
+
 +        saved_list = List.objects.first()
 +        self.assertEqual(saved_list, list_)
 +
          saved_items = Item.objects.all()
          self.assertEqual(saved_items.count(), 2)
- 
+
          first_saved_item = saved_items[0]
          second_saved_item = saved_items[1]
          self.assertEqual(first_saved_item.text, 'The first (ever) list item')
@@ -1236,7 +1238,7 @@ NOTE: I'm using the variable name `list_` to avoid "shadowing" the Python
     built-in `list` function.  It's ugly, but all the other options I tried
     were equally ugly or worse (`my_list`, `the_list`, `list1`, `listey`...).
 
-Time for another unit-test/code cycle.   
+Time for another unit-test/code cycle.
 
 For the first couple of iterations, rather than explicitly showing you what
 code to enter in between every test run, I'm only going to show you the
@@ -1379,7 +1381,7 @@ WARNING: Deleting migrations is dangerous.  We do need to do it now and again,
     Django will be confused about what state it's in, and how to apply future
     migrations. You should only do it when you're sure the migration hasn't
     been used.  A good rule of thumb is that you should never delete or modify
-    a migration that's already been committed to your VCS. 
+    a migration that's already been committed to your VCS.
 
 
 
@@ -1406,13 +1408,13 @@ Ran 6 tests in 0.021s
 FAILED (errors=3)
 ----
 
-Oh dear!  
+Oh dear!
 
 There is some good news. Although it's hard to see, our model tests are
 passing.  But three of our view tests are failing nastily.
 
 The reason is because of the new relationship we've introduced between
-++Item++s and ++List++s, which requires each item to have a parent list, which 
+++Item++s and ++List++s, which requires each item to have a parent list, which
 our old tests and code aren't prepared for.
 
 Still, this is exactly why we have tests! Let's get them working again.  The
@@ -1563,11 +1565,11 @@ class ListViewTest(TestCase):
 
 
 NOTE: A couple more of those lovely f-strings in this listing!  If they're
-    still a bit of a mystery, take a look at the 
+    still a bit of a mystery, take a look at the
 https://docs.python.org/3/reference/lexical_analysis.html#f-strings[docs]
     (although if your formal CS education is as bad as mine, you'll probably
     skip the formal grammar).
-    
+
 
 Running the unit tests gives an expected 404, and another related error:
 
@@ -1760,7 +1762,7 @@ FAIL: test_can_start_a_list_for_one_user
 (functional_tests.tests.NewVisitorTest)
  ---------------------------------------------------------------------
 Traceback (most recent call last):
-  File "...python-tdd-book/functional_tests/tests.py", line 67, in
+  File "...python-tdd-book/functional_tests/tests.py", line 68, in
 test_can_start_a_list_for_one_user
     self.wait_for_row_in_list_table('2: Use peacock feathers to make a fly')
 [...]
@@ -2139,7 +2141,7 @@ But we can fix it in 'list.html', as well as adjusting the form's POST action:
 <1> There's our new form action.
 
 <2> `.item_set` is ((("reverse lookups")))called
-a 
+a
     https://docs.djangoproject.com/en/1.11/topics/db/queries/#following-relationships-backward[reverse lookup].
     It's one of Django's incredibly useful bits of ORM that lets you look up an
     object's related items from a different table...
@@ -2256,7 +2258,7 @@ urlpatterns = [
 ----
 ====
 
-Rerun the unit tests to check that everything worked.  
+Rerun the unit tests to check that everything worked.
 
 
 When I did it, I couldn't quite believe I did it correctly on the first go. It
@@ -2298,9 +2300,9 @@ natural urge is often to dive in and fix everything at once...but if
     loads of changes to our code and nothing working.  The Testing Goat
     encourages us to take one step at a time, and go from working state to
     working state.
-    
-    
-    
+
+
+
 
 
 Split work out into small, achievable tasks::
@@ -2309,11 +2311,11 @@ this means starting with "boring" work rather than diving
     straight in with the fun stuff, but you'll have to trust that YOLO-you
     in the parallel universe is probably having a bad time, having broken
     everything, and struggling to get the app working again.
-    
+
 
 YAGNI::
     ((("Test-Driven Development (TDD)", "philosophy of", "YAGNI")))((("YAGNI (You ain&#x2019;t gonna need it!)")))You
-ain't gonna need it!  Avoid the temptation to write code that you 
+ain't gonna need it!  Avoid the temptation to write code that you
     think 'might' be useful, just because it suggests itself at the time.
     Chances are, you won't use it, or you won't have anticipated your
     future requirements correctly.  See <<chapter_outside_in>> for one