Docs.

6 files changed, 78 insertions, 17 deletions

diff --git a/docs/designdefense.rst b/docs/designdefense.rst
index ea6104618..7260ec1ce 100644
--- a/docs/designdefense.rst
+++ b/docs/designdefense.rst
@@ -630,7 +630,7 @@ I'll argue that URL dispatch is ultimately useful, even if you want to
 use traversal as well.  You can actually *combine* URL dispatch and
 traversal in :mod:`repoze.bfg` (see :ref:`hybrid_chapter`).  One
 example of such a usage: if you want to emulate something like Zope
-2's "Zope Management Interface" UI on top of your model graph (or any
+2's "Zope Management Interface" UI on top of your object graph (or any
 administrative interface), you can register a route like ``<route
 name="manage" path="manage/*traverse"/>`` and then associate
 "management" views in your code by using the ``route_name`` argument
@@ -749,11 +749,11 @@ have no equivalent core feature.
 We consider this an important feature for a particular class of
 applications (CMS-style applications, which the authors are often
 commissioned to write) that usually use :term:`traversal` against a
-persistent model graph.  The model graph contains security
+persistent object graph.  The object graph contains security
 declarations as :term:`ACL` objects.
 
 Having context-sensitive declarative security for individual objects
-in the model graph is simply required for this class of application.
+in the object graph is simply required for this class of application.
 Other frameworks save for Zope just do not have this feature.  This is
 the one of the primary reasons that :mod:`repoze.bfg` was actually
 written.
diff --git a/docs/narr/models.rst b/docs/narr/models.rst
index 535aa6ac3..e1d2fd635 100644
--- a/docs/narr/models.rst
+++ b/docs/narr/models.rst
@@ -191,9 +191,9 @@ In order for :mod:`repoze.bfg` location, security, URL-generation, and
 traversal functions (such as the functions exposed in
 :ref:`location_module`, :ref:`traversal_module`, and :ref:`url_module`
 as well as certain functions in :ref:`security_module` ) to work
-properly against a instances in a model graph, all nodes in the graph
-must be "location-aware".  This means they must have two attributes:
-``__parent__`` and ``__name__``.
+properly against a instances in an object graph, all nodes in the
+graph must be "location-aware".  This means they must have two
+attributes: ``__parent__`` and ``__name__``.
 
 The ``__parent__`` attribute should be a reference to the node's
 parent model instance in the graph.  The ``__name__`` attribute should
@@ -238,10 +238,10 @@ more information about how a model instance becomes the context.
 
 The APIs provided by :ref:`traversal_module` are used against model
 instances.  These functions can be used to find the "path" of a model,
-find the URL of a model, the root model in a model graph, and so on.
+find the URL of a model, the root model in an object graph, and so on.
 
 The APIs provided by :ref:`location_module` are used against model
-instances.  These can be used to walk down a model graph, or
+instances.  These can be used to walk down an object graph, or
 conveniently locate one object "inside" another.
 
 Some APIs in :ref:`security_module` accept a model object as a
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 18e63b474..81e570e36 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -697,7 +697,7 @@ behavior.
 
 #. Line 6 is a "root factory" function that will be called by the
    :mod:`repoze.bfg` *Router* for each request when it wants to find
-   the root of the model graph.  Conventionally this is called
+   the root of the object graph.  Conventionally this is called
    ``get_root``.
 
 In a "real" application, the root object would not be such a simple
diff --git a/docs/narr/unittesting.rst b/docs/narr/unittesting.rst
index 2af2b7558..cc8ab6e32 100644
--- a/docs/narr/unittesting.rst
+++ b/docs/narr/unittesting.rst
@@ -3,11 +3,53 @@
 Unit and Integration Testing
 ============================
 
-The suggested mechanism for unit testing :mod:`repoze.bfg`
-applications is the Python ``unittest`` module.  :mod:`repoze.bfg`
-provides a number of facilities that make unit tests easier to write.
-The facilities become particularly useful when your code calls into
-:mod:`repoze.bfg` -related framework functions.
+*Unit testing* is the act of testing a "unit" in your application.  In
+this context, a "unit" is often a function or a method of a class
+instance.  The unit is also referred to as a "unit under test".  The
+goal of a single unit test is to test **only** some permutation of the
+"unit under test".  If you write a unit test that aims to verify the
+result of a particular codepath through a Python function, you need
+only be concerned about testing the code that *lives in the function
+body itself*.  If the function accepts a parameter that represents a
+complex application "domain object" (such a a model, a database
+connection, or an SMTP server), the argument provided to this function
+during a unit test *need not be* and likely *should not be* a "real"
+implementation object.  For example, although a particular function
+implementation may accept an argument that represents an SMTP server
+object, and the function may call a method of this object when the
+system is operating normally that would result in an email being sent,
+a unit test of this codepath of the function does *not* need to test
+that an email is actually sent.  It just needs to make sure that the
+function calls the method of the object provided as an argument that
+*would* send an email if the argument happened to be the "real"
+implementation of an SMTP server object.
+
+An *integration test*, on the other hand, is a different form of
+testing in which the interaction between two or more "units" is
+explicitly tested.  Integration tests verify that the components of
+your application work together.  You *might* make sure that an email
+was actually sent in an integration test.
+
+It is often considered best practice to write both types of tests for
+any given codebase.  Unit testing often provides the opportunity to
+obtain better "coverage": it's usually possible to supply a unit under
+test with arguments and/or an environment which causes *all* of its
+potential codepaths to be executed.  This is usually not as easy to do
+with a set of integration tests, but integration testing provides a
+measure of assurance that your "units" work together, as they will be
+expected to when your application is run in production.
+
+The suggested mechanism for unit and integration testing of a
+:mod:`repoze.bfg` application is the Python ``unittest`` module.
+Although this module is named ``unittest``, it is actually capable of
+driving both unit and integration tests.  A good ``unittest`` tutorial
+is available within `Dive Into Python
+<http://diveintopython.org/unit_testing/index.html>`_ by Mark Pilgrim.
+
+:mod:`repoze.bfg` provides a number of facilities that make unit and
+integration tests easier to write.  The facilities become particularly
+useful when your code calls into :mod:`repoze.bfg` -related framework
+functions.
 
 .. _test_setup_and_teardown:
 
@@ -19,7 +61,8 @@ structure to hold on to two items: the current :term:`request` and the
 current :term:`application registry`.  These data structures are
 available via the ``repoze.bfg.threadlocal.get_current_request`` and
 ``repoze.bfg.threadlocal.get_current_registry`` functions,
-respectively.
+respectively.  See :ref:`threadlocals_chapter` for information about
+these functions and the data structures they return.
 
 If your code uses these ``get_current_*`` functions or calls
 :mod:`repoze.bfg` code which uses the ``get_current_*`` functions, you
@@ -27,6 +70,24 @@ will need to use the ``repoze.bfg.testing.setUp`` and
 ``repoze.bfg.testing.tearDown`` functions within the ``setUp`` and
 ``tearDown`` methods of your unit tests, respectively.
 
+The ``repoze.bfg.testing.setUp`` and ``repoze.bfg.testing.tearDown``
+functions allow you to supply a unit test with an environment that has
+a default registry and a default request for the duration of a single
+test.  Here's an example of using both:
+
+.. code-block:: python
+   :linenos:
+
+   import unittest
+   from repoze.bfg import testing
+
+   class MyTest(unittest.TestCase):
+       def setUp(self):
+           testing.setUp()
+
+       def tearDown(self):
+           testing.tearDown()
+
 If you don't *know* whether you're calling code that uses these
 functions, a rule of thumb applies: just always use the
 ``repoze.bfg.testing.setUp`` and ``repoze.bfg.testing.tearDown``
diff --git a/docs/narr/vhosting.rst b/docs/narr/vhosting.rst
index 7394f2173..ee2d2be4b 100644
--- a/docs/narr/vhosting.rst
+++ b/docs/narr/vhosting.rst
@@ -70,7 +70,7 @@ Virtual Root Support
 applications.  These are explained below.
 
 Virtual root support is useful when you'd like to host some model in a
-:mod:`repoze.bfg` model graph as an application under a URL pathname
+:mod:`repoze.bfg` object graph as an application under a URL pathname
 that does not include the model path itself.  For example, you might
 want to serve the object at the traversal path ``/cms`` as an
 application reachable via ``http://example.com/`` (as opposed to
diff --git a/docs/tutorials/bfgwiki/basiclayout.rst b/docs/tutorials/bfgwiki/basiclayout.rst
index f8943eeab..d373624de 100644
--- a/docs/tutorials/bfgwiki/basiclayout.rst
+++ b/docs/tutorials/bfgwiki/basiclayout.rst
@@ -57,7 +57,7 @@ Content Models with ``models.py``
 ---------------------------------
 
 :mod:`repoze.bfg` often uses the word *model* when talking about
-content resources arranged in a hierarchical *model graph*.  The
+content resources arranged in a hierarchical *object graph*.  The
 ``models.py`` file is where the ``bfg_zodb`` Paster template put the
 classes that implement our models.