1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
|
\section{Patching Cheetah}
\label{patching}
How to commit changes to CVS or submit patches, how to run the test suite.
Describe distutils and how the regression tests work.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{File Requirements}
\label{patching.fileRequirements}
The code{Template} class contains not only the Cheetah infrastructure, but also
some convenience methods useful in all templates. More methods may be added if
it's generally agreed among Cheetah developers that the method is sufficiently
useful to all types of templates, or at least to all types of HTML-output
templates. If a method is too long to fit into \code{Template} -- especially
if it has helper methods -- put it in a mixin class under \code{Cheetah.Utils}
and inherit it.
Routines for a specific problem domain should be put under
\code{Cheetah.Tools}, so that it doesn't clutter the namespace unless the user
asks for it.
Remember: \code{Cheetah.Utils} is for objects required by any part of Cheetah's
core. \code{Cheetah.Tools} is for completely optional objects. It should
always be possible to delete \code{Cheetah.Tools} without breaking Cheetah's
core services.
If a core method needs to look up an attribute defined under
\code{Cheetah.Tools}, it should use \code{hasattr()} and gracefully provide a
default if the attribute does not exist (meaning the user has not imported that
subsystem).
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Testing Changes and Building Regression Tests}
\label{patching.testing}
Cheetah ships with a regression test suite. To run the built-in tests,
execute at the shell prompt:
\begin{verbatim}
cheetah test
\end{verbatim}
Before checking any changes in, run the tests and verify they all pass. That
way, users can check out the CVS version of Cheetah at any time with a fairly
high confidence that it will work. If you fix a bug or add a feature, please
take the time to add a test that exploits the bug/feature. This will help in
the future, to prevent somebody else from breaking it again without realizing
it. Users can also run the test suite to verify all the features work on their
particular platform and computer.
The general procedure for modifying Cheetah is as follows:
\begin{enumerate}
\item Write a simple Python program that exploits the bug/feature you're
working on. You can either write a regression test (see below), or a
separate program that writes the template output to one file and put the
expected output in another file; then you can run \code{diff} on the two
outputs. (\code{diff} is a utility included on all Unix-like systems. It
shows the differences between two files line by line. A precompiled
Windows version is at
\url{http://gnuwin32.sourceforge.net/packages/diffutils.htm}, and MacOS
sources at \url{http://perso.wanadoo.fr/gilles.depeyrot/DevTools\_en.html}.)
\item Make the change in your Cheetah CVS sandbox or in your installed
version of Cheetah. If you make it in the sandbox, you'll have to run
\code{python setup.py install} before testing it. If you make it in the
installed version, do {\em not} run the installer or it will overwrite your
changes!
\item Run \code{cheetah test} to verify you didn't break anything. Then run
your little test program.
\item Repeat steps 2-3 until everything is correct.
\item Turn your little program into a regression test as described below.
\item When \code{cheetah test} runs cleanly with your regression test
included, update the \code{CHANGES} file and check in your changes. If you
made the changes in your installed copy of Cheetah, you'll have to copy
them back into the CVS sandbox first. If you added any files that must be
distributed, {\em be sure to} \code{cvs add} them before committing.
Otherwise Cheetah will run fine on your computer but fail on anybody
else's, and the test suite can't check for this.
\item Announce the change on the cheetahtemplate-discuss list and provide a
tutorial if necessary. The documentation maintainer will update the
Users' Guide and Developers' Guide based on this message and on the
changelog.
\end{enumerate}
If you add a directory to Cheetah, you have to mention it in \code{setup.py} or
it won't be installed.
The tests are in the \code{Cheetah.Tests} package, aka the \code{src/Tests/}
directory of your CVS sandbox. Most of the tests are in
\code{SyntaxAndOutput.py}. You can either run all the tests or choose which
to run:
\begin{description}
\item{\code{python Test.py}}
Run all the tests. (Equivalent to \code{cheetah test}.)
\item{\code{python SyntaxAndOutput.py}}
Run only the tests in that module.
\item{\code{python SyntaxAndOutput.py CGI}}
Run only the tests in the class \code{CGI} inside the module. The class
must be a direct or indirect subclass of
\code{unittest\_local\_copy.TestCase}.
\item{\code{python SyntaxAndOutput.py CGI Indenter}}
Run the tests in classes \code{CGI} and \code{Indenter}.
\item{\code{python SyntaxAndOutput.py CGI.test1}}
Run only test \code{test1}, which is a method in the \code{CGI} class.
\item{etc...}
\end{description}
To make a SyntaxAndOutput test, first see if your test logically fits into one
of the existing classes. If so, simply add a method; e.g., \code{test16}.
The method should not require any arguments except \code{self}, and should
call \code{.verify(source, expectedOutput)}, where the two arguments are
a template definition string and a control string. The tester will complain
if the template output does not match the control string. You have a wide
variety of placeholder variables to choose from, anything that's included in
the \code{defaultTestNameSpace} global dictionary. If that's not enough, add
items to the dictionary, but please keep it from being cluttered with wordy
esoteric items for a single test).
If your test logically belongs in a separate class, create a subclass of
\code{OutputTest}. You do not need to do anything else; the test suite will
automatically find your class in the module. Having a separate class allows
you to define state variables needed by your tests (see the \code{CGI} class)
or override \code{.searchList()} (see the \code{Indenter} class) to provide
your own searchList.
To modify another test module or create your own test module, you'll have to
study the existing modules, the \code{unittest\_local\_copy} source, and the
\code{unittest} documentation in the Python Library Reference. Note that we
are using a hacked version of \code{unittest} to make a more convenient test
structure for Cheetah. The differences between \code{unittest\_local\_copy}
and Python's standard \code{unittest} are documented at the top of the module.
% Local Variables:
% TeX-master: "devel_guide"
% End:
|
