[Zope3-checkins] SVN: Zope3/trunk/ - documentation updates
Christian Theune
ct at gocept.com
Mon Apr 16 03:35:34 EDT 2007
Log message for revision 74165:
- documentation updates
- restification
Changed:
U Zope3/trunk/README.txt
U Zope3/trunk/doc/DEBUG.txt
U Zope3/trunk/doc/ENVIRONMENT.txt
U Zope3/trunk/doc/FAQ.txt
U Zope3/trunk/doc/FTEST.txt
U Zope3/trunk/doc/INSTALL.txt
U Zope3/trunk/doc/LOGGING.txt
U Zope3/trunk/doc/ROADMAP.txt
U Zope3/trunk/doc/UNITTEST.txt
-=-
Modified: Zope3/trunk/README.txt
===================================================================
--- Zope3/trunk/README.txt 2007-04-16 07:07:24 UTC (rev 74164)
+++ Zope3/trunk/README.txt 2007-04-16 07:35:34 UTC (rev 74165)
@@ -1,47 +1,49 @@
-===========================
-Welcome to the Zope3 source
-===========================
+============================
+Welcome to the Zope 3 source
+============================
-This file provides some basic hints for people developing Zope3 software.
-There is more developer info in the Zope 3 Wiki:
+This file provides some basic hints for people developing Zope 3 software.
+There is more developer info in the Zope 3 Wiki::
- http://dev.zope.org/Zope3/Zope3DeveloperInfo
+ http://wiki.zope.org/Zope3/Zope3DeveloperInfo
For information about the current release, see ``doc/CHANGES.txt``.
-Zope 3 is now a stable platform on which production systems can and are built.
+Zope 3 is a stable platform on which production systems can and are built.
Building and running tests
---------------------------
+==========================
See ``INSTALL.txt`` which Python version is required for Zope 3.
In the top-level ``Zope3`` directory, you should find a script called
-setup.py. Run it to build the extension modules needed by Zope. Example::
+``setup.py``. Run it to build the extension modules needed by Zope. Example::
- # cd Zope3
- # python setup.py -q build_ext -i install_data --install-dir .
+ $ cd Zope3
+ $ python setup.py -q build_ext -i install_data --install-dir .
-On a unix variant, you can just type: ``make``
+On a Unix variant, you can just type::
+ $ make
+
On Windows, if you downloaded the binary distribution, this has already been
done for you (since the compiler we use on Windows isn't free).
-Zope 3 includes unit tests based on the Python unittest module. If you check
-in changes, you should verify that all the tests succeed before you commit
-changes.
+Zope 3 includes unit tests based on the Python ``unittest`` module. If you
+check in changes, you *must* verify that all the tests succeed before you
+commit changes.
To run all the tests, use the script test.py::
- # python test.py -v
+ $ python test.py -v
Use ``test.py -h`` for usage. The test script can run selected tests, stop
after the first error, run the tests in a loop, etc.
Starting Zope 3
----------------
+===============
Before running Zope, you need to create one or more bootstrap users. Copy the
file ``sample_principals.zcml`` to ``principals.zcml``, and edit the result to
@@ -49,58 +51,58 @@
To run Zope just run the ``z3.py`` script::
- # python z3.py
+ $ python z3.py
Or, if you use make on Unix, you can run::
- # bin/runzope
+ $ bin/zopectl fg
This will run Zope on port 8080. Visit the url::
- http://localhost:8080/manage
+ http://localhost:8080/manage
-This goes to the Zope 3 default management interface. Note that
-this release of Zope 3 requires recent versions of Mozilla or IE. Note that
-other modern browsers, such as Konqueror and Safari, also mostly work well.
+This goes to the Zope 3 default management interface. Note that this release
+of Zope 3 requires recent versions of Mozilla or IE. Note that other modern
+browsers, such as Konqueror and Safari, also mostly work well.
-If you insist on using an older browser (or a text-based browser)
-you can use the basic Zope 3 skin by putting ``++skin++Basic`` after
-the server part of the URL::
+If you insist on using an older browser (or a text-based browser) you can use
+the basic Zope 3 skin by putting ``++skin++Basic`` after the server part of
+the URL::
- http://localhost:8080/++skin++Basic/manage
+ http://localhost:8080/++skin++Basic/manage
See ``doc/INSTALL.txt`` for more information.
-Finding out how to develop new content types
---------------------------------------------
+Finding out how to develop applications
+=======================================
There are several documentation sources out there. As of this writing two
books have been published and much online documentation is available:
- - Zope 3 comes with an extensive API documentation tool, which also compiles
- many of the package-specific README files. Once you start up Zope, simply
- go to:
+- Zope 3 comes with an extensive API documentation tool, which also compiles
+ many of the package-specific README files. Once you start up Zope, simply go
+ to::
- http://localhost:8080/++apidoc++
+ http://localhost:8080/++apidoc++
- - `Zope 3 Developer's Handbook`:
+- `Zope 3 Developer's Handbook`:
* On Paper: http://www.samspublishing.com/title/0672326175
* Online: http://dev.zope.org/Zope3/Zope3Book
- - `Web Component Development with Zope 3`:
+- `Web Component Development with Zope 3`:
* On Paper: http://www.springeronline.com/sgw/cda/frontpage/0,11855,1-102-22-35029949-0,00.html
* Online: http://www.worldcookery.com
- - The developers tutorial at:
+- The developers tutorial at:
http://dev.zope.org/Zope3/ProgrammerTutorial
- - Ask questions on the mailing lists and chat channels:
+- Ask questions on the mailing lists and chat channels:
* Zope 3 Development: ``http://lists.zope.org/mailman/listinfo/zope3-dev``
@@ -108,12 +110,12 @@
* IRC channel `#zope3-dev` on irc.freenode.net
- - To keep up with the latest changes, the commits mailing list
- ``http://lists.zope.org/mailman/listinfo/zope3-checkins``
+- To keep up with the latest changes, the commits mailing list
+ ``http://lists.zope.org/mailman/listinfo/zope3-checkins``
Acknowledgements
-----------------
+================
Zope 3 is a Zope Community effort. There are many Zope 3 contributors without
whom there wouldn't be a Zope 3.
Modified: Zope3/trunk/doc/DEBUG.txt
===================================================================
--- Zope3/trunk/doc/DEBUG.txt 2007-04-16 07:07:24 UTC (rev 74164)
+++ Zope3/trunk/doc/DEBUG.txt 2007-04-16 07:35:34 UTC (rev 74165)
@@ -1,3 +1,4 @@
+=======================
Using the Zope Debugger
=======================
@@ -2,53 +3,53 @@
Introduction
-------------
-
-Zope3 includes a mechanism to debug an object publishing request,
-similar to the `Zope 2 debug mechanism`_
+============
+Zope 3 includes a mechanism to debug an object publishing request, similar to
+the `Zope 2 debug mechanism`_
+
.. _Zope 2 debug mechanism: http://www.zope.org/Members/mcdonc/HowTos/UsingTheZopeDebugger
Setting up the environment
---------------------------
+==========================
-Setup your PYTHONPATH environment variable to include src. ie (unix
-bash syntax):
+Setup your PYTHONPATH environment variable to include ``src/``. ie (unix
+bash syntax)::
- cd Zope3
- export PYTHONPATH=$PWD/src:$PYTHONPATH
-
+ $ cd Zope3
+ $ export PYTHONPATH=$PWD/src:$PYTHONPATH
+
To start interacting with the debugger you need to initialize the zope
-application:
+application::
- $ python2.4
- >>> from zope.app.debug import Debugger
- >>> debugger = Debugger()
+ $ python2.4
+ >>> from zope.app.debug import Debugger
+ >>> debugger = Debugger()
-Note that you can pass a database file name and a site ZCML file to
-the debugger:
+Note that you can pass a database file name and a site ZCML file to the
+debugger::
- >>> Debugger('path/to/zodb/', 'path/to/site.zcml')
-
+ >>> Debugger('path/to/zodb/', 'path/to/site.zcml')
+
But you can generally let the debugger figure out where they are.
-XXX In the future, the debugger should have it's own ZConfig file.
+(XXX In the future, the debugger should have it's own ZConfig file.)
Alternatively, you can also use the ``zopectl`` script to initiate the
-debugger. It will start up the Zope 3 instance without the servers
-and drop into a regular Python prompt, with the Debugger instance
-bound to the ``debugger`` variable:
+debugger. It will start up the Zope 3 instance without the servers and drop
+into a regular Python prompt, with the Debugger instance bound to the
+``debugger`` variable::
- $ bin/zopectl debug
- >>> debugger
- <zope.app.debug.debug.Debugger object at 0x660350>
+ $ bin/zopectl debug
+ >>> debugger
+ <zope.app.debug.debug.Debugger object at 0x660350>
-For people with Zope 2 experience, the debugger is also available
-under the name ``app``:
+For people with Zope 2 experience, the debugger is also available under the
+name ``app``::
- >>> app
- <zope.app.debug.debug.Debugger object at 0x660350>
+ >>> app
+ <zope.app.debug.debug.Debugger object at 0x660350>
Using the Debugger
-------------------
+==================
@@ -58,35 +59,34 @@
testing purposes.
Publish
-~~~~~~~
+-------
The ``publish`` method executes a request as the publisher would and
-prints the response headers and body:
+prints the response headers and body::
- >>> debugger.publish(path='/folder/content_object')
+ >>> debugger.publish(path='/folder/content_object')
Run
-~~~
+---
The ``run`` method executes a request with the publisher's normal
error handling disabled and without outputting anything. This is
-useful for use with Python's post-mortem.
+useful for use with Python's post-mortem::
- >>> debugger.run(path='/folder/content_object')
- # an exception is raised
- >>> import pdb; pdb.pm()
- # enters the python post-mortem debugger
+ >>> debugger.run(path='/folder/content_object')
+ # an exception is raised
+ >>> import pdb; pdb.pm()
+ # enters the python post-mortem debugger
Debug
-~~~~~
+-----
-The 'debug' method starts up the publisher in the python debugger,
-with an extra convenience break point, setup just before the published
-object call:
+The ``debug`` method starts up the publisher in the python debugger, with an
+extra convenience break point, setup just before the published object call::
- >>> debugger.debug(path='/folder/content_object')
- * Type c<cr> to jump to published object call.
- pdb>
+ >>> debugger.debug(path='/folder/content_object')
+ * Type c<cr> to jump to published object call.
+ pdb>
Arguments: All of the debugger object's debug methods take optional
arguments, the more common/useful ones...
@@ -98,18 +98,17 @@
Accessing objects (without the debugger)
-----------------------------------------
+========================================
-You can use the application object to open a database connection to
-access your objects. If the application object is called, it opens a
-database connection and fetches the root object:
+You can use the application object to open a database connection to access
+your objects. If the application object is called, it opens a database
+connection and fetches the root object::
- root = debugger.root()
+ >>> root = debugger.root()
-For example, to list the objects in the root folder:
+For example, to list the objects in the root folder::
- print list(root)
+ >>> print list(root)
-Also note that, after initializing the application, by creating the
-root object, you can access any global services setup during
-initialization.
+Also note that, after initializing the application, by creating the root
+object, you can access any global services setup during initialization.
Modified: Zope3/trunk/doc/ENVIRONMENT.txt
===================================================================
--- Zope3/trunk/doc/ENVIRONMENT.txt 2007-04-16 07:07:24 UTC (rev 74164)
+++ Zope3/trunk/doc/ENVIRONMENT.txt 2007-04-16 07:35:34 UTC (rev 74165)
@@ -1,21 +1,20 @@
-Usage of environment variables:
+==============================
+Usage of environment variables
+==============================
- - The test suite uses the LOGGING variable to determine the PEP 282
- logging level. This should be a decimal number with the following
- meaning: 10 DEBUG, 20 INFO, 30 WARN, 40 ERROR, 50 CRITICAL
- (default).
+- The test suite uses the LOGGING variable to determine the PEP 282 logging
+ level. This should be a decimal number with the following meaning: 10
+ DEBUG, 20 INFO, 30 WARN, 40 ERROR, 50 CRITICAL (default).
- - Some ZEO code still uses environment variables, in particular
- ZEO_CACHE_TRACE, ZEO_CLIENT, INSTANCE_HOME, ZEO_SERVER_PID.
+- Some ZEO code still uses environment variables, in particular
+ ZEO_CACHE_TRACE, ZEO_CLIENT, INSTANCE_HOME, ZEO_SERVER_PID.
- - ZOPE_WATCH_CHECKERS used by src/zope/security/checker.py.
+- ZOPE_WATCH_CHECKERS used by src/zope/security/checker.py.
- - ZOPE_SERVER_SIMULT_MODE used by src/zope/server/serverchannelbase.py.
+- ZOPE_SERVER_SIMULT_MODE used by src/zope/server/serverchannelbase.py.
- - ZOPE_SERVER_DEBUG used by
- src/zope/server/linereceiver/lineserverchannel.py.
+- ZOPE_SERVER_DEBUG used by src/zope/server/linereceiver/lineserverchannel.py.
- - NEW_ZOPE_EXCEPTION_FORMATTER used by src/zope/testing/.
+- NEW_ZOPE_EXCEPTION_FORMATTER used by src/zope/testing/.
- - PYUNIT_EDITOR, EDITOR, EDITOR_REMOTE used by
- utilities/unittestgui.py.
+- PYUNIT_EDITOR, EDITOR, EDITOR_REMOTE used by utilities/unittestgui.py.
Modified: Zope3/trunk/doc/FAQ.txt
===================================================================
--- Zope3/trunk/doc/FAQ.txt 2007-04-16 07:07:24 UTC (rev 74164)
+++ Zope3/trunk/doc/FAQ.txt 2007-04-16 07:35:34 UTC (rev 74165)
@@ -1,4 +1,5 @@
+============================================
Zope Installation Frequently Asked Questions
---------------------------------------------
+============================================
- See http://dev.zope.org/Zope3/FAQ
\ No newline at end of file
+See http://dev.zope.org/Zope3/FAQ
Modified: Zope3/trunk/doc/FTEST.txt
===================================================================
--- Zope3/trunk/doc/FTEST.txt 2007-04-16 07:07:24 UTC (rev 74164)
+++ Zope3/trunk/doc/FTEST.txt 2007-04-16 07:35:34 UTC (rev 74165)
@@ -1,81 +1,72 @@
+=========================
Zope 3 Functional Testing
+=========================
- How to run Zope 3 functional tests
+How to run Zope 3 functional tests
- In the top-level directory, run "python test.py -f". If you've read
- UNITTEST.txt you'll notice that the same script is used, but with an
- additional argument '-f'. That's because in Zope 3 functional tests are
- just a special case of unit tests. The rest of test.py options work as
- well, for example you can use "python test.py -fpv" to get a nice progress
- indicator. For information about all options run "python test.py -h".
+In the top-level directory, run "python test.py -f". If you've read
+UNITTEST.txt you'll notice that the same script is used, but with an
+additional argument '-f'. That's because in Zope 3 functional tests are just
+a special case of unit tests. The rest of test.py options work as well, for
+example you can use "python test.py -fpv" to get a nice progress indicator.
+For information about all options run "python test.py -h".
- If your Zope 3 doesn't yet have a products.zcml, create one by
- copying products.zcml.in to products.zcml.
+Zope Functional Testing
+=======================
- Zope Functional Testing
+Functional tests use special ``test layers`` that set up more environment than
+normal unit tests do. E.g. the parse nearly all ZCML configuration files and
+create a virtual in-memory storage before running the tests. Any changes made
+to the storage will be discarded at the end of the test.
- Functional tests live in directories called "ftests" all over the source
- tree. They use the same PyUnit framework as unit tests, and I recommend
- reading UNITTEST.txt and familiarizing with unit tests before moving on to
- functional tests.
+Note: We recommend reading UNITTEST.txt and familiarize yourself with unit tests
+before moving on to functional tests.
- Functional tests differ from unit tests in that nearly all ZCML configuration
- files are parsed and a virtual in-memory storage is created before running
- them. Any changes made to the storage will be discarded at the end of the
- test.
- What Functional Tests Are
+What Functional Tests Are
+=========================
- Functional tests are meant to test more than just a single unit of code.
- While unit tests make sure that all components work as designed, functional
- tests ensure that those components are connected correctly, and that the
- system works as a whole.
+Functional tests are meant to test more than just a single unit of code.
+While unit tests make sure that all components work as designed, functional
+tests ensure that those components are connected correctly, and that the
+system works as a whole.
- Writing Functional Tests
+Writing Functional Tests
+========================
- Functional tests in Zope 3 use the same conventions as unit tests, but with
- the following differences:
+Functional tests in Zope 3 use the same conventions as unit tests, but with
+the following differences:
- - Functional test modules live in directories called 'ftests'.
+- Functional test suites live in a special ``functional test layer``.
- - Functional test cases inherit from
- zope.testing.functional.FunctionalTestCase or
- zope.testing.functional.BrowserTestCase instead of unittest.TestCase.
+- All global services, components etc. defined in assorted configure.zcml are
+ available during test run time.
- - All global services, components etc. defined in assorted configure.zcml
- are available during test run time.
+- A volatile in-memory storage with an empty root folder and all essential
+ services is available and is automatically cleaned after every test. The
+ test code can access and modify the root folder by calling
+ self.getRootFolder().
- - A volatile in-memory storage with an empty root folder and all essential
- services is available and is automatically cleaned after every test.
- The test code can access and modify the root folder by calling
- self.getRootFolder().
+- Browser requests can be emulated by leveraging the test browser. See the
+ documentation in ``src/zope/testbrowser/`` for detailed information. Here
+ are a couple of simple examples::
- - Browser requests can be emulated by inheriting from BrowserTestCase and
- calling self.publish(). See the docstring in
- src/zope/app/tests/functional.py for detailed information. Here are a
- couple of simple examples::
+ >>> from zope.testbrowser.testing import Browser
+ >>> browser = Browser()
+ >>> browser.open("http://localhost/")
+ >>> print browser.contents
+ <html>
+ ...
+ >>> browser.getLink('[contents]').click()
- response = self.publish('/folder/object')
- self.assertEquals(response.getStatus(), 200)
- self.assert_(response.getBody().find("some text") != -1)
+- If you want to make changes made directly through access to
+ self.getRootFolder() available to a test browser request, make sure to
+ commit the transaction. Here's how you do it::
- response = self.publish(
- '/something/action.html',
- basic='username:password',
- form={'id': u'foo', 'UPDATE_SUBMIT': u'Submit'})
- self.assertEquals(response.getStatus(), 302)
- self.assertEquals(response.getHeader('Location'),
- 'http://localhost/something.html')
+ >>> import transaction
+ >>> transaction.commit()
- - If you want to make changes made directly through access to
- self.getRootFolder() available to an emulated request, make sure to commit
- the transaction. Here's how you do it::
-
- import transaction
- transaction.commit()
-
- - Functional tests should not change any global registries. In particular,
- functional unit test cases should not inherit from
- zope.testing.cleanup.CleanUp or any of the PlacelessSetup classes that
- inherit from CleanUp.
-
+- Functional tests should not change any global registries. In particular,
+ functional unit test cases should not inherit from
+ zope.testing.cleanup.CleanUp or any of the PlacelessSetup classes that
+ inherit from CleanUp.
Modified: Zope3/trunk/doc/INSTALL.txt
===================================================================
--- Zope3/trunk/doc/INSTALL.txt 2007-04-16 07:07:24 UTC (rev 74164)
+++ Zope3/trunk/doc/INSTALL.txt 2007-04-16 07:35:34 UTC (rev 74165)
@@ -1,114 +1,106 @@
+========================================
Building and installing Zope from source
-----------------------------------------
+========================================
- This document describes building and installing Zope3 on Unix.
- We will provide Windows instructions in later releases. We
- will also provide binary releases for some platforms.
+This document describes building and installing Zope 3 on Unix. We will
+provide Windows instructions in later releases. We will also provide binary
+releases for some platforms.
Important notes
+===============
- ZOPE 3 REQUIRES PYTHON 2.4.1!
+ZOPE 3 REQUIRES PYTHON 2.4.4!
Quick Start
+===========
- The following commands should get you up and running with the
- development version of Zope3 on Unix:
+The following commands should get you up and running with the development
+version of Zope 3 on Unix:
- * If you have not yet checked out the Subversion tree, do so::
+* If you have not yet checked out the Subversion tree, do so::
- svn co svn://svn.zope.org/repos/main/Zope3/trunk/ Zope3
+ $ svn co svn://svn.zope.org/repos/main/Zope3/trunk/ Zope3
+ $ cd Zope3
+ $ make
- * cd Zope3
+* Copy sample_principals.zcml to principals.zcml, and edit the entries in your
+ new principals.zcml. At the very least, change the passwords!
- * python setup.py build_ext -i
+* Run the server::
+
+ $ bin/zopectl fg
- (On Unix, typing "make" will do the same thing.)
+You should shortly see logging messages indicating Zope 3 is listening on port
+8080. At that point you can connect to Zope 3 by directing your browser to::
- * Copy sample_principals.zcml to principals.zcml, and edit the
- entries in your new principals.zcml. At the very least, change
- the passwords!
+ http://localhost:8080/manage
- * python z3.py
+This will access the Zope 3 default management interface. Note that this
+release of Zope 3 requires recent versions of Mozilla or IE.
- (On Unix, typing "make run" will do the same thing.)
+If you insist on using an older browser (or a text-based browser) you can use
+the basic Zope 3 skin by putting '++skin++Basic' after the server part of the
+URL::
- You should shortly see logging messages indicating Zope3 is listening on
- port 8080. At that point you can connect to Zope3 by directing
- your browser to::
-
- http://yourhost:8080/manage
-
- where yourhost is the name or address of the machine running Zope 3.
-
- This will access the Zope 3 default management interface. Note that
- this release of Zope 3 requires recent versions of Mozilla or IE.
-
- If you insist on using an older browser (or a text-based browser)
- you can use the basic Zope 3 skin by putting '++skin++Basic' after
- the server part of the URL::
-
http://localhost:8080/++skin++Basic/manage
- You will be prompted for a user name and password. Use the user name
- and password you entered into your principals.zcml file.
+You will be prompted for a user name and password. Use the user name and
+password you entered into your ``principals.zcml`` file.
- Now you're off and running!
+Now you're off and running!
Resources
+=========
- If you haven't used Zope3 before, you should head to the Zope web
- site and read some documentation. The Zope 3 Python Programmers
- Tutorial is a good place to start. You can access it on the Zope
- site at::
+If you haven't used Zope 3 before, you should head to the Zope web site and
+read some documentation. The Zope 3 Python Programmers Tutorial is a good
+place to start. You can access it on the Zope site at::
http://dev.zope.org/Zope3/ProgrammerTutorial
- You will also find some additional documentation in the 'doc'
- directory of the Zope3 tree, where this file lives. All other
- existing Zope3 documentation is linked from somewhere in the Zope
- project Wiki::
+You will also find some additional documentation in the 'doc' directory of the
+Zope 3 tree, where this file lives. All other existing Zope 3 documentation
+is linked from somewhere in the Zope project Wiki::
- http://dev.zope.org/Zope3/ComponentArchitecture
+ http://wiki.zope.org/Zope3
- You may also want to subscribe to the Zope3-dev mailing list::
+You may also want to subscribe to the Zope3-dev mailing list::
http://lists.zope.org/mailman/listinfo/zope3-dev
- Have fun!
+Have fun!
Random Details
+==============
- * There are some Python scripts in the top-level directory that
- will help you track changes during the development process.
- Specifically, 'setup.py' helps you build the extension modules,
- and 'test.py' will run all of the unit tests (see UNITTEST.txt
- in the doc directory for more information on unit tests).
+* There are some Python scripts in the top-level directory that will help you
+ track changes during the development process. Specifically, 'setup.py'
+ helps you build the extension modules, and 'test.py' will run all of the
+ unit tests (see UNITTEST.txt in the doc directory for more information on
+ unit tests).
- * You should be using Python 2.4.1 or later to run anything
- related to Zope3.
+* You should be using Python 2.4.4 or later to run anything related to Zope 3.
- * The Python you run Zope with *must* have threads compiled in.
- This is typically the case for a vanilla build on platforms that
- support thread, but be sure this wasn't disabled if you use a
- custom build. (If the Python statement "import thread" raises
- an exception, your Python interpreter does not support threads.)
- Warning: Zope will not run with a Python version that uses
- libpth. You *must* use libpthread.
+* The Python you run Zope with *must* have threads compiled in. This is
+ typically the case for a vanilla build on platforms that support thread, but
+ be sure this wasn't disabled if you use a custom build. (If the Python
+ statement "import thread" raises an exception, your Python interpreter does
+ not support threads.) Warning: Zope will not run with a Python version that
+ uses libpth. You *must* use libpthread.
- * To build Python extensions you need to have Python configuration
- information available. If your Python comes from an RPM you may
- need the python-devel package installed too. If you built Python
- from source all the configuration information should already be
- there.
+* To build Python extensions you need to have Python configuration information
+ available. If your Python comes from an RPM you may need the python-devel
+ package installed too. If you built Python from source all the configuration
+ information should already be there.
- * If you just want to use Zope components it's not necessary to
- build Zope but it's a good idea since it will compile Python C
- extensions for you.
+* If you just want to use Zope components it's not necessary to build Zope but
+ it's a good idea since it will compile Python C extensions for you.
Troubleshooting
+===============
- * We've seen segfaults when running the test suite. This was
- invariably caused by having parts of Zope 2 or ZODB 3 (which
- goes with Zope 2) installed in site-packages or elsewhere on
- Python's module search path (sys.path). So make sure you have
- no parts of Zope 2 or ZODB 3 on sys.path when running Zope 3!
+* We've seen segfaults when running the test suite. This was invariably
+ caused by having parts of Zope 2 or ZODB 3 (which goes with Zope 2)
+ installed in site-packages or elsewhere on Python's module search path
+ (sys.path). So make sure you have no parts of Zope 2 or ZODB 3 on sys.path
+ when running Zope 3!
Modified: Zope3/trunk/doc/LOGGING.txt
===================================================================
--- Zope3/trunk/doc/LOGGING.txt 2007-04-16 07:07:24 UTC (rev 74164)
+++ Zope3/trunk/doc/LOGGING.txt 2007-04-16 07:35:34 UTC (rev 74165)
@@ -1,145 +1,142 @@
+==============
Zope 3 Logging
+==============
- Logging is done through the logging package (PEP 282-based logging).
- It is fairly easy to use and to configure.
+Logging is done through the logging package (PEP 282-based logging). It is
+fairly easy to use and to configure.
+Configuring the logging package for z3.py
+=========================================
- Configuring the logging package for z3.py
+XXX This is out of date; see zope.conf.in for an example of the current way of
+configuring logging.
- XXX This is out of date; see zope.conf.in for an example of the
- current way of configuring logging.
+The log file used by z3.py can be configured in the zserver.zcml file with
+this directive::
- The log file used by z3.py can be configured in the zserver.zcml
- file with this directive::
-
<startup:useLog file="..." level="...">
- The file argument should give the filename where you want the log to
- go. If the filename is STDERR or STDOUT, logging goes to the
- process's standard error or standard output stream, respectively.
+The file argument should give the filename where you want the log to go. If
+the filename is STDERR or STDOUT, logging goes to the process's standard error
+or standard output stream, respectively.
- The level argument should give the logging severity level; anything
- below this level is not logged. The supported levels are, in
- increasing severity: DEBUG, INFO, WARN, ERROR, CRITICAL.
+The level argument should give the logging severity level; anything below this
+level is not logged. The supported levels are, in increasing severity: DEBUG,
+INFO, WARN, ERROR, CRITICAL.
- Configuring the logging package for running unit tests
+Configuring the logging package for running unit tests
+======================================================
- When running unit tests, logging is configured through the file
- log.ini in the current directory, if it exists. This file should be
- self-explanatory, and provides full access to the logging package's
- advanced features. If log.ini is not found, critical messages are
- logged to the process's standard error stream, and other messages
- are not logged.
+When running unit tests, logging is configured through the file log.ini in the
+current directory, if it exists. This file should be self-explanatory, and
+provides full access to the logging package's advanced features. If log.ini
+is not found, critical messages are logged to the process's standard error
+stream, and other messages are not logged.
- test.py also understands the LOGGING environment variable, which can
- be used to specify an integer logging level. So a simple way to run
- the tests with all logging going to standard error is to set LOGGING
- to 0, e.g.:
+test.py also understands the LOGGING environment variable, which can be used
+to specify an integer logging level. So a simple way to run the tests with
+all logging going to standard error is to set LOGGING to 0, e.g.::
- export LOGGING=0
- python test.py
+ $ export LOGGING=0
+ $ python test.py
- Using the logging package
+Using the logging package
+=========================
- There are two ways of using the logging package. You can use
- functions defined in the logging package directly, or you can use
- methods on a logger object. In either case you need a simple import
- statement::
+There are two ways of using the logging package. You can use functions
+defined in the logging package directly, or you can use methods on a logger
+object. In either case you need a simple import statement::
- import logging
+ >>> import logging
+Using the logging functions
+---------------------------
- Using the logging functions
+To use the logging functions defined by the package directly, use one of the
+functions debug(), info(), warn(), error() or critical() from the package.
+Each of these takes a message argument. The message may be a standard Python
+format string, and then the following arguments are the format arguments.
+This allows you to write, for example::
- To use the logging functions defined by the package directly, use
- one of the functions debug(), info(), warn(), error() or critical()
- from the package. Each of these takes a message argument. The
- message may be a standard Python format string, and then the
- following arguments are the format arguments. This allows you to
- write, for example::
+ >>> logging.warn("Cannot open file %r: %s", filename, err)
- logging.warn("Cannot open file %r: %s", filename, err)
+instead of::
- instead of::
+ >>> logging.warn("Cannot open file %r: %s" % (filename, err))
- logging.warn("Cannot open file %r: %s" % (filename, err))
+Apart from slight savings in typing, the advantage of the former is that if
+warnings are not logged, the string formatting operation is not carried out,
+saving some time.
- Apart from slight savings in typing, the advantage of the former is
- that if warnings are not logged, the string formatting operation is
- not carried out, saving some time.
+It is also possible to log a traceback. This is done by adding a keyword
+argument exc_info=True. For example::
- It is also possible to log a traceback. This is done by adding a
- keyword argument exc_info=True. For example::
+ >>> try:
+ ... ...something...
+ ... except:
+ ... logging.error("Unexpected problem", exc_info=True)
- try:
- ...something...
- except:
- logging.error("Unexpected problem", exc_info=True)
+The logging package will call sys.exc_info() and use the traceback module to
+format the traceback. When the message is not logged, this is skipped. In
+fact, there's a shorthand for this particular case (logging a traceback at the
+error level)::
- The logging package will call sys.exc_info() and use the traceback
- module to format the traceback. When the message is not logged,
- this is skipped. In fact, there's a shorthand for this particular
- case (logging a traceback at the error level)::
+ >>> try:
+ ... ...something...
+ ... except:
+ ... logging.exception("Unexpected problem")
- try:
- ...something...
- except:
- logging.exception("Unexpected problem")
+Finally, there is a generic log function; it has a first argument specifying a
+logging severity level, followed by the standard arguments of all the above
+functions::
- Finally, there is a generic log function; it has a first argument
- specifying a logging severity level, followed by the standard
- arguments of all the above functions::
+ >>> logging.log(level, message, ..., exc_info=...)
- logging.log(level, message, ..., exc_info=...)
+The predefined logging levels are available as symbolic constants:
+logging.DEBUG, logging.INFO, logging.WARN, logging.ERROR, and
+logging.CRITICAL. (There's no logging.EXCEPTION level, because exception() is
+not a separate logging level; it's a shorthand for passing exc_info=True to
+the error() method.)
- The predefined logging levels are available as symbolic constants:
- logging.DEBUG, logging.INFO, logging.WARN, logging.ERROR, and
- logging.CRITICAL. (There's no logging.EXCEPTION level, because
- exception() is not a separate logging level; it's a shorthand for
- passing exc_info=True to the error() method.)
+Using a logger object
+---------------------
- Using a logger object
+Often you'd like all log messages coming out of a particular class or module
+to be "tagged" with a label identifying that class or module, regardless of
+the logging severity of the message. In some cases, you'd like that label to
+convey additional run-time information, such as a storage or thread name.
- Often you'd like all log messages coming out of a particular class
- or module to be "tagged" with a label identifying that class or
- module, regardless of the logging severity of the message. In some
- cases, you'd like that label to convey additional run-time
- information, such as a storage or thread name.
+Rather than prefixing all log messages with an identifying string, you can
+create a logger object that does this for you. Logger objects have methods
+debug(), info(), etc., corresponding to the logging functions described in the
+previous section, and with exactly the same signature; these are what you use
+to log a message using a logger object, for example::
- Rather than prefixing all log messages with an identifying string,
- you can create a logger object that does this for you. Logger
- objects have methods debug(), info(), etc., corresponding to the
- logging functions described in the previous section, and with
- exactly the same signature; these are what you use to log a message
- using a logger object, for example::
+ >>> logger.warn("Oil temperature: %g", temp)
- logger.warn("Oil temperature: %g", temp)
+To create a logger object, use the getLogger() function::
- To create a logger object, use the getLogger() function::
+ >>> foo_bar_logger = logging.getLogger("foo.bar")
- foo_bar_logger = logging.getLogger("foo.bar")
+The string argument to getLogger() is interpreted as a sequence of names
+separated by dots; this creates a hierarchy that can be used for additional
+filtering or handling. Normally, however, a logger object inherits all its
+properties (except for its name) from its parent logger object. For the
+foo_bar_logger above, the parent would be the logger object returned by this
+call::
- The string argument to getLogger() is interpreted as a sequence of
- names separated by dots; this creates a hierarchy that can be used
- for additional filtering or handling. Normally, however, a logger
- object inherits all its properties (except for its name) from its
- parent logger object. For the foo_bar_logger above, the parent
- would be the logger object returned by this call::
+ >>> foo_logger = logging.getLogger("foo")
- foo_logger = logging.getLogger("foo")
+Its parent in turn is the root logger; the logging functions described in the
+previous section correspond to methods of the root logger object. By
+configuring the root logger you can configure all loggers in the hierarchy,
+unless some configuration is overridden at a lower level. This an advanced
+feature of the logging module that we won't discuss further here.
- Its parent in turn is the root logger; the logging functions
- described in the previous section correspond to methods of the root
- logger object. By configuring the root logger you can configure all
- loggers in the hierarchy, unless some configuration is overridden at
- a lower level. This an advanced feature of the logging module that
- we won't discuss further here.
-
- Logger objects are lightweight and cached by the logging module;
- subsequent calls to logging.getLogger() with the same logger name
- will return the same logger object. However, there is no way to
- delete logger objects, so it's not a good idea to make up arbitrary
- logger names dynamically.
+Logger objects are lightweight and cached by the logging module; subsequent
+calls to logging.getLogger() with the same logger name will return the same
+logger object. However, there is no way to delete logger objects, so it's not
+a good idea to make up arbitrary logger names dynamically.
Modified: Zope3/trunk/doc/ROADMAP.txt
===================================================================
--- Zope3/trunk/doc/ROADMAP.txt 2007-04-16 07:07:24 UTC (rev 74164)
+++ Zope3/trunk/doc/ROADMAP.txt 2007-04-16 07:35:34 UTC (rev 74165)
@@ -1,26 +1,14 @@
Zope 3 Road Map
===============
-The Zope 3 release road map is pretty much dictated by the time-based
-release cycle. There will be new major releases of Zope every six
-months (in June and December).
+The Zope 3 release road map is pretty much dictated by the time-based release
+cycle. There will be new major releases of Zope every six months (in May and
+November).
-For a list of planned features please check TODOLATER.txt
+We are managing our bugs, todos and road map using Launchpad.
+Check out::
-Zope 3.2
---------
+ https://launchpad.net/zope3
-* Zope 3.2 alpha 1: mid-October, 2005
-
-* Zope 3.2 beta 1: first week in November, 2005
-
-* Zope 3.2 rc 1: mid-December, 2005
-
-* Zope 3.2 final: last week of December, 2005
-
-
-Zope 3.3
---------
-
-The release cycle will start in May, 2006
+for upcoming features and releases.
Modified: Zope3/trunk/doc/UNITTEST.txt
===================================================================
--- Zope3/trunk/doc/UNITTEST.txt 2007-04-16 07:07:24 UTC (rev 74164)
+++ Zope3/trunk/doc/UNITTEST.txt 2007-04-16 07:35:34 UTC (rev 74165)
@@ -1,240 +1,232 @@
+===================
Zope 3 Unit Testing
+===================
- How to run Zope 3 unit tests
+How to run Zope 3 unit tests
+============================
- In the top level directory, run "python test.py". This runs all unit
- tests silently (unless errors occur). It is possible to run the
- tests more verbosely or to be more selective about which tests to
- run. There are also other options. For information about all this,
- run "python test.py -h" which prints an extensive usage message.
+In the top level directory, run::
- Zope Testing
+ $ python test.py
- If you encounter a directory named "tests" in a package within
- within the Zope source code, it most likely indicates that the
- directory contains test code used to ensure that the code owned by
- the package works as it was designed. Many of the test scripts
- contained within Zope "tests" directories will be scripts which
- contain "unit tests".
+This runs all unit tests silently (unless errors occur). It is possible to
+run the tests more verbosely or to be more selective about which tests to run.
+There are also other options. For information about all this, run "python
+test.py -h" which prints an extensive usage message.
- What Unit Tests Are
+Zope Testing
+============
- A "unit" may be defined as a piece of code with a single intended
- purpose. A "unit test" is defined as a piece of code which exists
- to codify the intended behavior of a unit and to compare its
- intended behavior against its actual behavior.
+If you encounter a directory named "tests" in a package within within the Zope
+source code, it most likely indicates that the directory contains test code
+used to ensure that the code owned by the package works as it was designed.
- Unit tests are a way for developers and quality assurance engineers
- to quickly ascertain whether independent units of code are working as
- expected. Unit tests are generally written at the same time as the
- code they are intended to test. A unit testing framework allows a
- collection of unit tests to be run without human intervention,
- producing a minimum of output if all the tests in the collection are
- successful.
- What Unit Tests Are Not
+What Unit Tests Are
+===================
- It's very useful to define unit tests in terms of what they are
- not. From the "Extreme Programming Enthusiast" website
- (http://c2.com/cgi/wiki?UnitTestsDefined)::
+A "unit" may be defined as a piece of code with a single intended purpose. A
+"unit test" is defined as a piece of code which exists to codify the intended
+behavior of a unit and to compare its intended behavior against its actual
+behavior.
- Unit tests are not:
+Unit tests are a way for developers and quality assurance engineers to quickly
+ascertain whether independent units of code are working as expected. Unit
+tests are generally written at the same time as the code they are intended to
+test. A unit testing framework allows a collection of unit tests to be run
+without human intervention, producing a minimum of output if all the tests in
+the collection are successful.
- - Manually operated.
+What Unit Tests Are Not
+=======================
- - Automated screen-driver tests that simulate user input (these
- are "functional tests").
+It's very useful to define unit tests in terms of what they are not. From the
+"Extreme Programming Enthusiast" website
+(http://c2.com/cgi/wiki?UnitTestsDefined)::
- - Interactive. They run "no questions asked."
+Unit tests are not:
- - Coupled. They run without dependencies except those native to
- the thing being tested.
+- Manually operated.
- - Complicated. Unit test code is typically straightforward
- procedural code that simulates an event.
+- Automated screen-driver tests that simulate user input (these are
+ "functional tests").
- Unit Testing Frameworks
+- Interactive. They run "no questions asked."
- A unit testing framework is generally employed to collect related
- unit tests together in order to make it easier to run them as a
- group. When used with a unit testing framework, unit tests live
- outside of the modules of code they're intended to test.
+- Coupled. They run without dependencies except those native to the thing
+ being tested.
- How Unit Tests Help In The Development Process
+- Complicated. Unit test code is typically straightforward procedural code
+ that simulates an event.
- Unit tests should be written at the same time the code they test is
- written. A short, healthy cycle of "code/write test/run
- test/repeat" can help a developer code more quickly by reducing
- "backtracking" effort and by helping the developer focus on the
- actual problem at hand. Additionally, the unit tests generated at
- initial development time can serve as later assurance that
- maintenance and refactoring performed on code does not break any of
- its intended functionality or behavior. The results of unit tests
- may additionally be used as a metric by quality assurance personnel
- along with the results of other tests to gauge code quality before
- before it is "shipped."
+Unit Testing Frameworks
+=======================
- Basic Unit Testing Philosophies
+A unit testing framework is generally employed to collect related unit tests
+together in order to make it easier to run them as a group. When used with a
+unit testing framework, unit tests live outside of the modules of code they're
+intended to test.
- Write unit tests at the same time that you write the code.
- Nothing's worse than being faced with the prospect of writing tests
- against a huge chunk of existing code because you "have to."
- Writing unit tests post-facto can be boring and also robs you of the
- main benefits that unit testing can provide. Writing unit tests at
- the same time you write the code helps you focus on the task at
- hand. Writing unit tests in conjunction with code can be fun and
- satisfying, and can help you improve the quality of your code while
- its goals are fresh in your mind. Used properly, unit testing may
- also help you write code faster, because you will need to
- "backtrack" less. Some "Extreme Programming" enthusiasts posit that
- you should write a test before you write its associated code, and
- then develop the code until it passes the test.
+How Unit Tests Help In The Development Process
+==============================================
- Unit tests should be developed against as small and specific a
- subset of a system's or subsystem's functionality as possible. For
- instance, a one unit test may test that a unique id generator
- produces ids of a specific length, while another unit test in the
- same group may ensure that a thousand ids from the same unique id
- generator do not contain the same value. Writing a single unit test
- which tests a broad swath of a system's capabilities is
- counterproductive, because it does not allow for a fine enough
- granularity when attempting to figure out "what went wrong,"
- requiring the developer to "backtrack". Unit testing is capable of
- helping to help reduce backtracking, but only if used properly.
+Unit tests should be written at the same time the code they test is written.
+A short, healthy cycle of "code/write test/run test/repeat" can help a
+developer code more quickly by reducing "backtracking" effort and by helping
+the developer focus on the actual problem at hand. Additionally, the unit
+tests generated at initial development time can serve as later assurance that
+maintenance and refactoring performed on code does not break any of its
+intended functionality or behavior. The results of unit tests may
+additionally be used as a metric by quality assurance personnel along with the
+results of other tests to gauge code quality before before it is "shipped."
- A unit test does not produce any output unless it fails. If a unit
- test fails, it should print something useful, but short. A unit
- test should never fill the screen with output or otherwise produce
- output that needs to be manually examined for "clues". This is the
- realm of other testing methodologies. If unit tests are written at
- sufficiently granular level, it is often enough just to know the
- name of the unit test that failed.
+Basic Unit Testing Philosophies
+===============================
- "It is better to have tried to test and failed than to not have
- tried to test at all" aka "test the riskiest things first." If the
- prospect of writing a series of unit tests for an existing system
- seems daunting, it's important to remember that no matter how many
- unit tests you write, you cannot prove that your software does not
- have bugs. Therefore, you cannot possibly test every case while
- developing. You should plan to write tests against code based on
- the risks involved in not testing that code. Don't feel that you
- need to write a test case for every "corner case" (although do try
- to hit the riskiest ones). In the worst case, it's better to have a
- test module with one lonely unit test in it than none at all.
+Write unit tests at the same time that you write the code. Nothing's worse
+than being faced with the prospect of writing tests against a huge chunk of
+existing code because you "have to." Writing unit tests post-facto can be
+boring and also robs you of the main benefits that unit testing can provide.
+Writing unit tests at the same time you write the code helps you focus on the
+task at hand. Writing unit tests in conjunction with code can be fun and
+satisfying, and can help you improve the quality of your code while its goals
+are fresh in your mind. Used properly, unit testing may also help you write
+code faster, because you will need to "backtrack" less. Some "Extreme
+Programming" enthusiasts posit that you should write a test before you write
+its associated code, and then develop the code until it passes the test.
- "Test fixtures" are employed by unit tests. Test fixtures are bits
- of state and environment that allow the unit test to perform its job
- properly. An example of a test fixture might be a file, an instance
- of a class, or a row in a database table. Any part of the
- environment needed by a unit test besides the unit testing framework
- itself is considered a test fixture.
+Unit tests should be developed against as small and specific a subset of a
+system's or subsystem's functionality as possible. For instance, a one unit
+test may test that a unique id generator produces ids of a specific length,
+while another unit test in the same group may ensure that a thousand ids from
+the same unique id generator do not contain the same value. Writing a single
+unit test which tests a broad swath of a system's capabilities is
+counterproductive, because it does not allow for a fine enough granularity
+when attempting to figure out "what went wrong," requiring the developer to
+"backtrack". Unit testing is capable of helping to help reduce backtracking,
+but only if used properly.
- In general, the common fixtures required by individual tests in a
- testing group should be more or less identical. If the fixtures
- needed by a single test are radically different than the fixtures
- required by the rest of the tests, or if the test does not require
- the fixtures provided to the other tests, it probably belongs in
- another (or its own) group of tests.
+A unit test does not produce any output unless it fails. If a unit test
+fails, it should print something useful, but short. A unit test should never
+fill the screen with output or otherwise produce output that needs to be
+manually examined for "clues". This is the realm of other testing
+methodologies. If unit tests are written at sufficiently granular level, it
+is often enough just to know the name of the unit test that failed.
- When a unit test in a group modifies the state of a test fixture,
- the test fixture should be restored to a known state before the next
- unit test in the group is run. Often, this means "rolling back"
- changes to a transactional database or restoring the state of a
- string so the next unit test can inherit a known state of the same
- fixtures. The unit testing framework has capabilities which allow
- you to automate most of this work by providing a "set up" method
- which gets called before each test is run and a "tear down" method
- that gets called after a test is finished.
+"It is better to have tried to test and failed than to not have tried to test
+at all" aka "test the riskiest things first." If the prospect of writing a
+series of unit tests for an existing system seems daunting, it's important to
+remember that no matter how many unit tests you write, you cannot prove that
+your software does not have bugs. Therefore, you cannot possibly test every
+case while developing. You should plan to write tests against code based on
+the risks involved in not testing that code. Don't feel that you need to
+write a test case for every "corner case" (although do try to hit the riskiest
+ones). In the worst case, it's better to have a test module with one lonely
+unit test in it than none at all.
- Unit tests should play nicely with the unit testing framework they
- employ. Unit tests should not call "sys.exit()" or do similar
- things which effect their ability to be run as part of a group of
- tests. The testing framework attempts to deal with misbehaved unit
- tests, but it's better just to make them behave nicely in the first
- place.
+"Test fixtures" are employed by unit tests. Test fixtures are bits of state
+and environment that allow the unit test to perform its job properly. An
+example of a test fixture might be a file, an instance of a class, or a row in
+a database table. Any part of the environment needed by a unit test besides
+the unit testing framework itself is considered a test fixture.
- Unit tests should "grow" with the code that they're intended to
- test. For example, if a group of unit tests is intended to verify
- the behavior of all of the routines within a module, additional unit
- tests should be added to the test group when new functionality is
- added to that module.
+In general, the common fixtures required by individual tests in a testing
+group should be more or less identical. If the fixtures needed by a single
+test are radically different than the fixtures required by the rest of the
+tests, or if the test does not require the fixtures provided to the other
+tests, it probably belongs in another (or its own) group of tests.
- Writing Unit Tests For The Zope Core
+When a unit test in a group modifies the state of a test fixture, the test
+fixture should be restored to a known state before the next unit test in the
+group is run. Often, this means "rolling back" changes to a transactional
+database or restoring the state of a string so the next unit test can inherit
+a known state of the same fixtures. The unit testing framework has
+capabilities which allow you to automate most of this work by providing a "set
+up" method which gets called before each test is run and a "tear down" method
+that gets called after a test is finished.
- If you're not writing core code, you probably don't need to listen to
- any more of this. :-) The rules for writing tests for Zope core
- code are simple:
+Unit tests should play nicely with the unit testing framework they employ.
+Unit tests should not call "sys.exit()" or do similar things which effect
+their ability to be run as part of a group of tests. The testing framework
+attempts to deal with misbehaved unit tests, but it's better just to make them
+behave nicely in the first place.
- - The testing code should make use of the standard Python unittest
- module. See the Python docs for usage information.
+Unit tests should "grow" with the code that they're intended to test. For
+example, if a group of unit tests is intended to verify the behavior of all of
+the routines within a module, additional unit tests should be added to the
+test group when new functionality is added to that module.
- - Tests must be placed in a "tests" subdirectory of the package or
- directory in which the core code you're testing lives.
+Writing Unit Tests For The Zope Core
+====================================
- - Test modules should be named something which represents the
- functionality they test, and should begin with the prefix "test."
- E.g., a test module for BTree should be named testBTree.py.
+If you're not writing core code, you probably don't need to listen to any more
+of this. :-) The rules for writing tests for Zope core code are simple:
- - An individual test module should take no longer than 60 seconds
- to complete.
+- The testing code should make use of the standard Python unittest module.
+ See the Python docs for usage information.
- more information available at http://dev.zope.org/Zope3/WritingUnitTests
+- Tests must be placed in a "tests" subdirectory of the package or directory
+ in which the core code you're testing lives.
- Writing Unit Tests For Applications Based On Zope
+- Test modules should be named something which represents the functionality
+ they test, and should begin with the prefix "test." E.g., a test module for
+ BTree should be named testBTree.py.
- Zope uses the standard Python unittest module. See the Python docs
- for usage information. You should establish your own conventions
- for naming and placement of test modules.
+- An individual test module should take no longer than 60 seconds to complete.
- Writing unit tests against applications based on Zope can be
- difficult. Zope is a collection of related modules, some with
- non-trivial interdependencies. Running its code successfully also
- in some cases depends on state provided only in the context of a web
- request, so calling Zope methods directly may not work as you
- expect. If you're not intimately familiar with Zope, implementing
- unit tests can be frustrating. For example, for the common case,
- before you are able to write code which tests a Zope SQL Method, you
- must establish a test fixture which represents your entire Zope
- site.
+More information is available at::
- Luckily, some tools are at your disposal to make writing unit tests
- against Zope components and applications easier by making the
- creation of these fixtures easier.
+ http://dev.zope.org/Zope3/WritingUnitTests
- Surprisingly, one of the most effective tools for facilitating unit
- testing is ZEO (http://www.zope.org/Products/ZEO). ZEO is an
- open-source clustering solution for Zope which makes it possible to
- front-end a single "storage server" which manages a Zope object
- database with multiple Zope clients that run a "client storage".
- The reason ZEO is interesting for unit testing is mostly an
- unintended side-effect of how it works as compared to Zope without
- ZEO. Zope without ZEO commonly uses a "FileStorage" to hold its
- object database. When Zope is started with a FileStorage, the
- FileStorage code processes an "index" file. This takes time. Zope
- using a ClientStorage as with ZEO does not process an index file,
- making startup faster. Fast startup of Zope is critical to
- effective unit testing. It is recommended that you implement ZEO if
- you're heavy in to unit testing, as it really speeds things up.
- It's not strictly required, however.
+Writing Unit Tests For Applications Based On Zope
+=================================================
- Administrivia
+Zope uses the standard Python unittest module. See the Python docs for usage
+information. You should establish your own conventions for naming and
+placement of test modules.
- Unit test scripts found in the Zope source code is based on
- the PyUnit unit testing framework, available from
- http://pyunit.sourceforge.net, written by Stephen Purcell (thanks
- Stephen!). PyUnit is based on the JUnit testing framework for Java
- (written by Kent Beck and Erich Gamma), which in turn was based on a
- testing framework designed for Smalltalk (also written by Kent
- Beck).
+Writing unit tests against applications based on Zope can be difficult. Zope
+is a collection of related modules, some with non-trivial interdependencies.
+Running its code successfully also in some cases depends on state provided
+only in the context of a web request, so calling Zope methods directly may not
+work as you expect. If you're not intimately familiar with Zope, implementing
+unit tests can be frustrating. For example, for the common case, before you
+are able to write code which tests a Zope SQL Method, you must establish a
+test fixture which represents your entire Zope site.
- Unit testing is a primary tenet of "Extreme Programming", a software
- development methodology designed to facilitate the rapid production
- of high quality code with a minimum of developmental ceremony. For
- more information on unit tests as they relate to Extreme
- Programming, see http://c2.com/cgi/wiki?UnitTestsDefined. Although
- Digital Creations has not embraced the entire spectrum of Extreme
- Programming methodologies in its software development process, we've
- found unit tests a way to speed development and produce
- higher-quality code.
+Luckily, some tools are at your disposal to make writing unit tests against
+Zope components and applications easier by making the creation of these
+fixtures easier.
+Surprisingly, one of the most effective tools for facilitating unit testing is
+ZEO (http://www.zope.org/Products/ZEO). ZEO is an open-source clustering
+solution for Zope which makes it possible to front-end a single "storage
+server" which manages a Zope object database with multiple Zope clients that
+run a "client storage". The reason ZEO is interesting for unit testing is
+mostly an unintended side-effect of how it works as compared to Zope without
+ZEO. Zope without ZEO commonly uses a "FileStorage" to hold its object
+database. When Zope is started with a FileStorage, the FileStorage code
+processes an "index" file. This takes time. Zope using a ClientStorage as
+with ZEO does not process an index file, making startup faster. Fast startup
+of Zope is critical to effective unit testing. It is recommended that you
+implement ZEO if you're heavy in to unit testing, as it really speeds things
+up. It's not strictly required, however.
+Administrivia
+=============
+
+Unit test scripts found in the Zope source code are based on the PyUnit unit
+testing framework, available from http://pyunit.sourceforge.net, written by
+Stephen Purcell (thanks Stephen!). PyUnit is based on the JUnit testing
+framework for Java (written by Kent Beck and Erich Gamma), which in turn was
+based on a testing framework designed for Smalltalk (also written by Kent
+Beck).
+
+Unit testing is a primary tenet of "Extreme Programming", a software
+development methodology designed to facilitate the rapid production of high
+quality code with a minimum of developmental ceremony. For more information
+on unit tests as they relate to Extreme Programming, see
+http://c2.com/cgi/wiki?UnitTestsDefined. Although Digital Creations has not
+embraced the entire spectrum of Extreme Programming methodologies in its
+software development process, we've found unit tests a way to speed
+development and produce higher-quality code.
More information about the Zope3-Checkins
mailing list