Update cheat sheet appendix

Author: hjwp

appendix_IX_cheat_sheet.asciidoc

@@ -1,43 +1,48 @@
 [[cheat-sheet]]
 [appendix]
-Cheat Sheet
------------
+== Cheat Sheet
 
-By popular demand, this "cheat sheet" is loosely based on the little
-recap/summary boxes from the end of each chapter.  The idea is to provide a few
-reminders, and links to the chapters where you can find out more to jog your
-memory. I hope you find it useful!
+By popular demand, this "cheat sheet" is loosely based on the recap/summary boxes
+from the end of each chapter.
+The idea is to provide a few reminders,
+and links to the chapters where you can find out more to jog your memory.
+I hope you find it useful!
 
 
-Initial Project Setup
-~~~~~~~~~~~~~~~~~~~~~
+=== Initial Project Setup
 
-* ((("cheat sheet", "project setup")))((("Django framework", "set up", "project creation")))Start
-with a 'User Story' and map it to a first 'functional test'.
+((("cheat sheet", "project setup")))
+((("Django framework", "set up", "project creation")))
+* Start with a _User Story_ and map it to a first _functional test_.
 
 * Pick a test framework—`unittest` is fine, and options like `py.test`,
   `nose`, or `Green` can also offer some advantages.
 
 * Run the functional test and see your first 'expected failure'.
 
 * Pick a web framework such as Django, and find out how to run
-  'unit tests' against it.
+  _unit tests_ against it.
 
-* Create your first 'unit test' to address the current FT failure,
+* Create your first _unit test_ to address the current FT failure,
   and see it fail.
 
-* Do  your 'first commit' to a VCS like 'Git'.
+* Do  your _first commit_ to a VCS like _Git_.
 
-Relevant chapters: <<chapter_01>>, <<chapter_02_unittest>>, <<chapter_03_unit_test_first_view>>
+Relevant chapters:
+<<chapter_01>>,
+<<chapter_02_unittest>>,
+<<chapter_03_unit_test_first_view>>.
 
 
-The Basic TDD Workflow
-~~~~~~~~~~~~~~~~~~~~~~
+=== The Basic TDD Workflow: Red/Green/Refactor
 
-* ((("cheat sheet", "TDD workflow")))((("Test-Driven Development (TDD)", "overall process of")))Double-loop TDD (<<Double-Loop-TDD-diagram2>>)
+((("cheat sheet", "TDD workflow")))
+((("Test-Driven Development (TDD)", "overall process of")))
 
 * Red, Green, Refactor
 
+* Double-loop TDD (<<Double-Loop-TDD-diagram2>>)
+
 * Triangulation
 
 * The scratchpad
@@ -54,114 +59,96 @@ The Basic TDD Workflow
 image::images/double-loop-tdd-simpler.png["An inner red/green/refactor loop surrounded by an outer red/green of FTs"]
 
 
-Relevant chapters: <<chapter_04_philosophy_and_refactoring>>, <<chapter_05_post_and_database>>, <<chapter_07_working_incrementally>>
-
+Relevant chapters:
+<<chapter_04_philosophy_and_refactoring>>,
+<<chapter_05_post_and_database>>,
+<<chapter_07_working_incrementally>>.
 
 
-Moving Beyond Dev-Only Testing
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-* ((("cheat sheet", "moving beyond dev-only testing")))Start
-system testing early. Ensure your components work together: web server,
-  static content, database.
+=== Moving Beyond Dev-Only Testing
 
-* Build a staging environment to match your production environment, and run
-  your FT suite against it.
+((("cheat sheet", "moving beyond dev-only testing")))
 
-* Automate your staging and production environments:
+* Start system testing early.
+  Ensure your components work together: web server, static content, database.
 
+* Build a production environment early, and automate deployment to it.
     - PaaS vs. VPS
-    - Fabric
-    - Configuration management (Chef, Puppet, Salt, Ansible)
-    - Vagrant
+    - Docker
+    - Ansible vs Terraform
 
-* Think through deployment pain points: the database, static files, 
+* Think through deployment pain points: the database, static files,
   dependencies, how to customise settings, and so on.
 
 * Build a CI server as soon as possible, so that you don't have to rely
   on self-discipline to see the tests run.
 
-Relevant chapters: <<chapter_11_server_prep>>, <<chapter_25_CI>>
+Relevant chapters:
+<<part2>>,
+<<chapter_25_CI>>.
 
 
-General Testing Best Practices
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=== General Testing Best Practices
 
-* ((("cheat sheet", "testing best practices")))((("testing best practices")))Each
-test should test one thing.
+((("cheat sheet", "testing best practices")))
+((("testing best practices")))
 
-* One test file per application code source file.
+* Each test should test one thing.
 
-* Consider at least a placeholder test for every function and class,
-  no matter how simple.
+* Test behaviour rather than implementation.
 
 * "Don't test constants".
 
-* Try to test behaviour rather than implementation.
+* Try to think beyond the charmed path through the code,
+  and think through edge cases and error cases.
 
-* Try to think beyond the charmed path through the code, and think
-  through edge cases and error cases.
+* Balance the "test desiderata".
 
 
-Relevant chapters: <<chapter_04_philosophy_and_refactoring>>, <<chapter_14_database_layer_validation>>,
-<<chapter_15_simple_form>>
+Relevant chapters:
+<<chapter_04_philosophy_and_refactoring>>,
+<<chapter_14_database_layer_validation>>,
+<<chapter_15_simple_form>>,
+<<chapter_27_hot_lava>>.
 
 
-Selenium/Functional Testing Best Practices
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=== Selenium/Functional Testing Best Practices
 
 * Use explicit rather than implicit waits, and the interaction/wait pattern.
 
 * Avoid duplication of test code--helper methods in a base class and the
   Page pattern are possible solutions.
 
-* Avoid double-testing functionality. If you have a test that covers a 
-  time-consuming process (e.g., login), consider ways of skipping it in 
-  other tests (but be aware of unexpected interactions between seemingly
-  unrelated bits of functionality).
+* Avoid double-testing functionality.
+  If you have a test that covers a time-consuming process (e.g., login),
+  consider ways of skipping it in other tests
+  (but be aware of unexpected interactions between seemingly unrelated bits of functionality).
 
 * Look into BDD tools as another way of structuring your FTs.
 
-Relevant chapters: <<chapter_23_debugging_prod>>, <<chapter_25_CI>>,
-<<chapter_26_page_pattern>>
-
-Outside-In, Test Isolation Versus Integrated Tests, and Mocking
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-((("cheat sheet", "isolated vs. integrated tests")))Remember
-the reasons we write tests in the first place:
+Relevant chapters:
+<<chapter_23_debugging_prod>>,
+<<chapter_25_CI>>,
+<<chapter_26_page_pattern>>.
 
-* To ensure correctness and prevent regressions
-* To help us to write clean, maintainable code
-* To enable a fast, productive workflow
 
-And with those objectives in mind, think of different types of tests,
-and the trade-offs between them:
+=== Outside-In
 
+Default to working outside-in.  Use double-loop TDD to drive your development,
+start at the UI/outside layers, and work your way down to the infrastructure layers.
+This helps ensure that you write only the code you need,
+and flushes out integration issues early.
 
-Functional tests::
-    * Provide the best guarantee that your application really works correctly, from the point of view of the user
-    * But: it's a slower feedback cycle
-    * And they don't necessarily help you write clean code
+Relevant chapter: <<chapter_24_outside_in>>.
 
-Integrated tests (reliant on, for example, the ORM or the Django Test Client)::
-    * Are quick to write
-    * Are easy to understand
-    * Will warn you of any integration issues
-    * But: may not always drive good design (that's up to you!)
-    * And are usually slower than isolated tests
 
-Isolated ("mocky") tests::
-    * Involve the most hard work
-    * Can be harder to read and understand
-    * But: are the best ones for guiding you towards better design
-    * And run the fastest
+=== The Test Pyramid
 
-If you do find yourself writing tests with lots of mocks, and they feel
-painful, remember &#x201c;__listen to your tests__&#x201d;—ugly, mocky tests may be
-trying to tell you that your code could be simplified.
+Be aware that integration tests will get slower and slower over time.
+Find ways to shift the bulk of your testing to unit tests
+as your project grows in size and complexity.
 
-Relevant chapters: <<chapter_24_outside_in>>,
-//<<appendix_purist_unit_tests>>,
+Relevant chapters:
 <<chapter_27_hot_lava>>.