subversion/tests/cmdline/README

   1                       (-*- text -*-)
   2
   3                Subversion Commandline Client:  Test Suite
   4                ==========================================
   5
   6 The cmdline client test suite doesn't use the C-level testing
   7 framework, but is structured similarly.  Instead of testing library
   8 APIs, it drives the client just like a user would, examining the
   9 output and the on-disk results (i.e., the working copy) carefully as
  10 it goes.  In other words, this is "black box" testing of the
  11 command-line client.  It has no access to code internals; it never
  12 looks inside the .svn/ directory; it only performs actions that a
  13 human user would do.
  14
  15 These tests require Python 2.2 or later.
  16
  17   [ For more general information on Subversion's testing system,
  18     please read the README in subversion/tests/. ]
  19
  20
  21 How To Run The Tests
  22 ====================
  23
  24 To run a test script over ra_local, invoke it from THIS DIRECTORY.
  25
  26    $ cd subversion/tests/cmdline/
  27
  28 Invoke the script with no arguments to run all the tests in that
  29 script:
  30
  31    $ ./basic_tests.py
  32
  33 Invoke with one or more numeric arguments to run those particular tests:
  34
  35    $ ./basic_tests.py 7 13 17
  36
  37 And invoke with the "--list" option to list information about some or
  38 all tests available in that script:
  39
  40    $ ./basic_tests.py --list 2 3 4
  41    $ ./basic_tests.py --list
  42
  43 Note: if you are building Subversion in a directory other than the source
  44 directory (q.v. INSTALL), you will have to invoke the tests from within
  45 the build directory:
  46
  47    $ cd obj/subversion/tests/cmdline
  48    $ ../../../../svn/subversion/tests/cmdline/basic_tests.py
  49
  50
  51 Running over mod_dav_svn
  52 ------------------------
  53
  54 Running a script over mod_dav_svn is basically the same, but you have to
  55 set up httpd 2.0 first (on the same machine, since the tests create
  56 repositories on the fly), and pass a URL argument to the test scripts.
  57
  58 Assuming you have httpd 2.0 installed in /usr/local/apache2, just add
  59 two Location directives to /usr/local/apache2/conf/httpd.conf, with
  60 paths adjusted appropriately:
  61
  62    <Location /svn-test-work/repositories>
  63      DAV svn
  64      SVNParentPath /home/yourusernamehere/projects/svn/subversion/tests/cmdline/svn-test-work/repositories
  65      AuthzSVNAccessFile /home/yourusernamehere/projects/svn/subversion/tests/cmdline/svn-test-work/authz
  66      AuthType Basic
  67      AuthName "Subversion Repository"
  68      AuthUserFile /usr/local/apache2/conf/users
  69      Require valid-user
  70    </Location>
  71
  72    <Location /svn-test-work/local_tmp/repos>
  73      DAV svn
  74      SVNPath /home/yourusernamehere/projects/svn/subversion/tests/cmdline/svn-test-work/local_tmp/repos
  75      AuthzSVNAccessFile /home/yourusernamehere/projects/svn/subversion/tests/cmdline/svn-test-work/authz
  76      AuthType Basic
  77      AuthName "Subversion Repository"
  78      AuthUserFile /usr/local/apache2/conf/users
  79      Require valid-user
  80    </Location>
  81
  82 Httpd should be running on port 80.  You may also need to ensure that
  83 it's running as you, so it has read/write access to the repositories
  84 that are probably living in your Subversion working copy.  To do this,
  85 set the User and Group directives in httpd.conf, something like this:
  86
  87    User yourusernamehere
  88    Group users
  89
  90 You need to run the tests over mod_dav_svn with authentication enabled, so
  91 just drop the following 2-line snippet into the
  92 /usr/local/apache2/conf/users file [1]:
  93
  94 ----------------------------
  95 jrandom:xCGl35kV9oWCY
  96 jconstant:xCGl35kV9oWCY
  97 ----------------------------
  98
  99 Now, (re)start Apache and run the tests over mod_dav_svn.
 100
 101 You can run a test script over DAV:
 102
 103    $ ./basic_tests.py --url http://localhost
 104    $ ./basic_tests.py --url http://localhost 3
 105
 106 or
 107
 108    $ ./basic_tests.py --url=http://localhost
 109    $ ./basic_tests.py --url=http://localhost 3
 110
 111 If you run httpd on a port other than 80, you can specify the port in
 112 the URL: "http://localhost:15835" for example.
 113
 114 To run all tests over DAV, pass BASE_URL when running 'make check'
 115 from the top of the build dir:
 116
 117    $ make check BASE_URL=http://localhost
 118
 119 BASE_URL=URL can also be used when running individual tests:
 120
 121    $ ./basic_tests.py BASE_URL=http://localhost
 122    $ ./basic_tests.py BASE_URL=http://localhost 3
 123
 124
 125 Note [1]: It would be quite too much to expect those password entries
 126           to work on Windows... Apache httpd on Windows doesn't
 127           understand crypted passwords, but it does understand
 128           MD5-hashed passwords.  The correct password entries for
 129           Windows are:
 130
 131           ----------------------------
 132           jrandom:$apr1$3p1.....$FQW6RceW5QhJ2blWDQgKn0
 133           jconstant:$apr1$jp1.....$Usrqji1c9H6AbOxOGAzzb0
 134           ----------------------------
 135
 136
 137 Running over ra_svn
 138 -------------------
 139
 140 It's also easy to run the tests against a local svnserve:
 141
 142 $ subversion/svnserve/svnserve -d -r `pwd`/subversion/tests/cmdline
 143 $ make check BASE_URL=svn://localhost
 144
 145 or, to run individual tests,
 146
 147 $ ./basic_tests.py --url=svn://localhost 3
 148
 149 To enable Cyrus SASL on the server side you should either set the
 150 ENABLE_SASL variable when calling make:
 151
 152 $ make check BASE_URL=svn://localhost ENABLE_SASL=true
 153
 154 or if you're running an individual test,
 155
 156 $ ./basic_tests.py --url=svn://localhost --enable-sasl 3
 157
 158 Note that to do this you'll have to have a subversion.conf file in your
 159 SASL lib dir (i.e. something like /usr/lib/sasl2/subversion.conf), it
 160 should contain something like:
 161
 162 pwcheck_method: auxprop
 163 mech_list: CRAM-MD5
 164
 165 And then you'll have to add the users jrandom and jconstant to your
 166 SASL password db,
 167
 168 $ saslpasswd2 -c -u svntest jrandom
 169 $ saslpasswd2 -c -u svntest jconstant
 170
 171 As usual, both users should use the password 'rayjandom'.
 172
 173 Directory Contents
 174 ==================
 175
 176    *.py                  The tests themselves.
 177
 178    svntest/              Python package, provides test suite framework
 179
 180           /main.py:         Global vars, utility routines; exports
 181                             run_tests(), the main test routine.
 182
 183           /tree.py:         Infrastructure for SVNTreeNode class.
 184                               - tree constructors, tree comparison routines.
 185                               - routines to parse subcommand output into
 186                                 specific kinds of trees.
 187                               - routines to parse a working copy and
 188                                 entries files into specific kinds of trees.
 189
 190           /wc.py:           Functions for interacting with a working
 191                             copy, and converting to/from trees.
 192
 193           /actions.py:      Main API for driving subversion client and
 194                             using trees to verify results.
 195
 196           /verify.py:       Verifies output from Subversion.
 197
 198           /entry.py:        Parse an `entries' file (### not used yet)
 199
 200
 201
 202 What the Python Tests are Doing
 203 ===============================
 204
 205 I.  Theory
 206
 207   A. Types of Verification
 208
 209    The point of this test system is that it's *automated*: that is,
 210    each test can algorithmically verify the results and indicate "PASS"
 211    or "FAIL".
 212
 213    We've identified two broad classes of verification:
 214
 215    1.  Verifying svn subcommand output.
 216
 217       Most important subcommands (co, up, ci, im, st) print results to
 218       stdout as a list of paths.  Even though the paths may be printed
 219       out in an unpredictable order, we still want to make sure this
 220       list is exactly the *set* of lines we expect to get.
 221
 222    2.  Verifying the working copy itself.
 223
 224       Every time a subcommand could potentially change something on
 225       disk, we need to inspect the working copy.  Specifically, this
 226       means we need to make sure the working copy has exactly the
 227       tree-structure we expect, and each file has exactly the contents
 228       and properties we expect.
 229
 230
 231 II.  Practice:  Trees
 232
 233   Sam TH <sam@uchicago.edu> proposed and began work on a solution
 234   whereby all important, inspectable information is parsed into a
 235   general, in-memory tree representation.  By comparing actual
 236   vs. expected tree structures, we get automated verification.
 237
 238   A.  Tree node structure
 239
 240       Each "tree node" in a tree has these fields:
 241
 242       - name :  the name of the node
 243       - children:  list of child nodes (if the node is a dir)
 244       - contents:  textual contents (if the node is a file)
 245       - properties:  a hash to hold subversion props
 246       - atts:        a hash of meta-information about tree nodes themselves
 247
 248
 249   B.  Parsing subcommand output into a tree
 250
 251       Special parsers examine lines printed by subcommands, and
 252       convert them into a tree of tree-nodes.  The 'contents' and
 253       'properties' fields are empty; but prepending on the subcommand,
 254       specific attributes in the 'atts' field are set in tree-nodes:
 255
 256        - svn co/up:        a 'status' attribute is set to a two-character
 257                            value from the set (A, D, G, U, C, _, ' ') or
 258                            a 'verb' attribute is set to ('Restored')
 259
 260        - svn status:       a 'status' attribute (as above), plus 'wc_rev'
 261                            and 'repos_rev' attributes to hold the wc
 262                            and repos revision numbers.
 263
 264        - svn ci/im:        a 'verb' attribute is set to one of
 265                            (Adding, Sending, Deleting)
 266
 267
 268   C.  Parsing a working copy into a tree
 269
 270      We also have a routines that walks a regular working copy and
 271      returns a tree representing disk contents and props.  In this
 272      case the 'atts' hash in each node is empty, but the 'contents'
 273      and 'props' fields are filled in.
 274
 275
 276
 277 How to Write New Tests
 278 ======================
 279
 280 If you'd like to write a new python test, first decide which file it
 281 might fit into; test scripts each contain collections of tests grouped
 282 by rough categories.  (Is it testing a new subcommand?  New
 283 enhancement?  Tricky use-case?  Regression test?)
 284
 285 Next, read the long documentation comment at the top of
 286 svntest/tree.py.  It will explain the general API that most tests use.
 287
 288 Finally, try copying-and-pasting a simple test and then edit from
 289 there.  Don't forget to add your test to the 'test_list' variable at
 290 the bottom of the file.
 291
 292