← Back to branch summary

~drizzle-trunk/drizzle/development

« back to all changes in this revision

Viewing changes to docs/testing/dbqp.rst

  • Committer: Monty Taylor
  • Date: 2011-03-10 18:09:05 UTC
  • mfrom: (2225.2.2 refactor)
  • mto: This revision was merged to the branch mainline in revision 2228.
  • Revision ID: mordred@inaugust.com-20110310180905-ttx05t7q7ff6nl7c
Merge Olad: Refactoring

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/testing/dbqp.rst
 
1
**********************************
 
2
dbqp
 
3
**********************************
 
4
 
 
5
Synopsis
 
6
========
 
7
Drizzle testing tool
 
8
 
 
9
**./dbqp** [ *OPTIONS* ] [ TESTCASE ]
 
10
 
 
11
Description
 
12
===========
 
13
 
 
14
:program:`dbqp.py` is BETA software.  It is intended to provide a standardized
 
15
platform to facilitate Drizzle testing.  
 
16
 
 
17
The default mode is 'dtr' and is used to execute tests from the Drizzle 
 
18
test suite.  These tests are included with Drizzle distributions and 
 
19
provide a way for users to verify that the system will operate according
 
20
to expectations.
 
21
 
 
22
The dtr tests use a diff-based paradigm, meaning that the test runner executes
 
23
a test and then compares the results received with pre-recorded expected 
 
24
results.  In the event of a test failure, the program will provide output
 
25
highlighting the differences found between expected and actual results; this
 
26
can be useful for troubleshooting and in bug reports.
 
27
 
 
28
The program is also integrated with the random query generator testing tool
 
29
and a 'rangden' mode is available - it will execute randgen tests when
 
30
provided a path to a randgen installation.  Tests are organized similar to dtr
 
31
tests, but are .cnf file based.
 
32
 
 
33
A 'cleanup' mode is also available as a convenience - it will simply shutdown
 
34
any servers that may have been started via start-and-exit.
 
35
 
 
36
While most users are concerned with ensuring general functionality, the 
 
37
program also allows a user to quickly spin up a server for ad-hoc testing
 
38
and to run the test-suite against an already running Drizzle server.
 
39
 
 
40
Running tests
 
41
=========================
 
42
 
 
43
There are several different ways to run tests using :program:`dbqp.py`.
 
44
 
 
45
It should be noted that unless :option:`--force` is used, the program will
 
46
stop execution upon encountering the first failing test. 
 
47
:option:`--force` is recommended if you are running several tests - it will
 
48
allow you to view all successes and failures in one run.
 
49
 
 
50
Running individual tests
 
51
------------------------
 
52
If one only wants to run a few, specific tests, they may do so this way::
 
53
 
 
54
    ./dbqp.py [OPTIONS] test1 [test2 ... testN]
 
55
 
 
56
Running all tests within a suite
 
57
--------------------------------
 
58
Many of the tests supplied with Drizzle are organized into suites.  
 
59
 
 
60
The tests within drizzle/tests/t are considered the 'main' suite.  
 
61
Other suites are located in either drizzle/tests/suite or within the various
 
62
directories in drizzle/plugin.  Tests for a specific plugin should live in 
 
63
the plugin's directory - drizzle/plugin/example_plugin/tests
 
64
 
 
65
To run the tests in a specific suite::
 
66
 
 
67
    ./dbqp.py [OPTIONS] --suite=SUITENAME
 
68
 
 
69
Running specific tests within a suite
 
70
--------------------------------------
 
71
To run a specific set of tests within a suite::
 
72
 
 
73
    ./dbqp.py [OPTIONS] --suite=SUITENAME TEST1 [TEST2..TESTN]
 
74
 
 
75
Calling tests using <suitename>.<testname> currently does not work.
 
76
One must specify the test suite via the :option:`--suite` option.
 
77
 
 
78
 
 
79
Running all available tests
 
80
---------------------------
 
81
Currently, the quickest way to execute all tests in all suites is
 
82
to use 'make test-dbqp' from the drizzle root.
 
83
 
 
84
Otherwise, one should simply name all suites::
 
85
 
 
86
    ./dbqp.py [OPTIONS] --suite=SUITE1, SUITE2, ...SUITEN
 
87
 
 
88
Interpreting test results
 
89
=========================
 
90
The output of the test runner is quite simple.  Every test should pass.
 
91
In the event of a test failure, please take the time to file a bug here:
 
92
*https://bugs.launchpad.net/drizzle*
 
93
 
 
94
During a run, the program will provide the user with:
 
95
  * test name (suite + name)
 
96
  * test status (pass/fail/skipped)
 
97
  * time spent executing each test
 
98
 
 
99
At the end of a run, the program will provide the user with a listing of:
 
100
  * how many tests were run
 
101
  * counts and percentages of total exectuted for all test statuses
 
102
  * a listing of failing, skipped, or disabled tests
 
103
  * total time spent executing the tests
 
104
 
 
105
Example output::
 
106
 
 
107
    <snip>
 
108
    30 Jan 2011 16:26:31 : main.small_tmp_table                                    [ pass ]           38
 
109
    30 Jan 2011 16:26:31 : main.snowman                                            [ pass ]           42
 
110
    30 Jan 2011 16:26:31 : main.statement_boundaries                               [ pass ]           47
 
111
    30 Jan 2011 16:26:31 : main.status                                             [ pass ]           51
 
112
    30 Jan 2011 16:26:31 : main.strict                                             [ pass ]          138
 
113
    30 Jan 2011 16:26:43 : main.subselect                                          [ fail ]        12361
 
114
    30 Jan 2011 16:26:43 : --- drizzle/tests/r/subselect.result 2011-01-30 16:23:54.975776148 -0500
 
115
    30 Jan 2011 16:26:43 : +++ drizzle/tests/r/subselect.reject 2011-01-30 16:26:43.835519303 -0500
 
116
    30 Jan 2011 16:26:43 : @@ -5,7 +5,7 @@
 
117
    30 Jan 2011 16:26:43 : 2
 
118
    30 Jan 2011 16:26:43 : explain extended select (select 2);
 
119
    30 Jan 2011 16:26:43 : id   select_type     table   type    possible_keys   key     key_len ref     rows    filtered        Extra
 
120
    30 Jan 2011 16:26:43 : -9   PRIMARY NULL    NULL    NULL    NULL    NULL    NULL    NULL    NULL    No tables used
 
121
    30 Jan 2011 16:26:43 : +1   PRIMARY NULL    NULL    NULL    NULL    NULL    NULL    NULL    NULL    No tables used
 
122
    <snip>
 
123
    30 Jan 2011 16:30:20 : ================================================================================
 
124
    30 Jan 2011 16:30:20 INFO: Test execution complete in 314 seconds
 
125
    30 Jan 2011 16:30:20 INFO: Summary report:
 
126
    30 Jan 2011 16:30:20 INFO: Executed 552/552 test cases, 100.00 percent
 
127
    30 Jan 2011 16:30:20 INFO: STATUS: FAIL, 1/552 test cases, 0.18 percent executed
 
128
    30 Jan 2011 16:30:20 INFO: STATUS: PASS, 551/552 test cases, 99.82 percent executed
 
129
    30 Jan 2011 16:30:20 INFO: FAIL tests: main.subselect
 
130
    30 Jan 2011 16:30:20 INFO: Spent 308 / 314 seconds on: TEST(s)
 
131
    30 Jan 2011 16:30:20 INFO: Test execution complete
 
132
    30 Jan 2011 16:30:20 INFO: Stopping all running servers...
 
133
 
 
134
    
 
135
Additional uses
 
136
===============
 
137
Starting a server for manual testing
 
138
------------------------------------
 
139
 
 
140
:program:`dbqp.py` allows a user to get a Drizzle server up and running
 
141
quickly.  This can be useful for fast ad-hoc testing.
 
142
 
 
143
To do so call::
 
144
 
 
145
    ./dbqp.py --start-and-exit [*OPTIONS*]
 
146
 
 
147
This will start a Drizzle server that you can connect to and query
 
148
 
 
149
Starting a server against a pre-populated DATADIR
 
150
--------------------------------------------------
 
151
 
 
152
Using :option:`--start-dirty` prevents :program:`dbqp.py` from attempting
 
153
to initialize (clean) the datadir.  This can be useful if you want to use
 
154
an already-populated datadir for testing.
 
155
 
 
156
NOTE: This feature is still being tested, use caution with your data!!!
 
157
 
 
158
Randgen mode / Executing randgen tests
 
159
---------------------------------------
 
160
 
 
161
Using :option:`--mode` =randgen and :option:`--randgen-path` =/path/to/randgen
 
162
will cause the randgen tests to execute.  This are simple .cnf file-based
 
163
tests that define various randgen command lines that are useful in testing
 
164
the server.  Test organization is similar to the dtr tests.  Tests live in 
 
165
suites, the default suite is 'main' and they all live in
 
166
drizzle/tests/randgen_tests::
 
167
 
 
168
        ./dbqp.py --mode=randgen --randgen-path=/path/to/randgen
 
169
 
 
170
A user may specify suites and individual tests to run, just as with dtr-based
 
171
testing.  Test output is the same as well::
 
172
 
 
173
    ./dbqp --mode=randgen --randgen-path=/home/username/repos/randgen
 
174
    Setting --no-secure-file-priv=True for randgen mode...
 
175
    <snip>
 
176
    23 Feb 2011 11:42:43 INFO: Using testing mode: randgen
 
177
    <snip>
 
178
    23 Feb 2011 11:44:58 : ================================================================================
 
179
    23 Feb 2011 11:44:58 : TEST NAME                                               [ RESULT ]    TIME (ms)
 
180
    23 Feb 2011 11:44:58 : ================================================================================
 
181
    23 Feb 2011 11:44:58 : main.optimizer_subquery                                 [ pass ]       134153
 
182
    23 Feb 2011 11:45:03 : main.outer_join                                         [ pass ]         5136
 
183
    23 Feb 2011 11:45:06 : main.simple                                             [ pass ]         2246
 
184
    23 Feb 2011 11:45:06 : ================================================================================
 
185
    23 Feb 2011 11:45:06 INFO: Test execution complete in 142 seconds
 
186
    23 Feb 2011 11:45:06 INFO: Summary report:
 
187
    23 Feb 2011 11:45:06 INFO: Executed 3/3 test cases, 100.00 percent
 
188
    23 Feb 2011 11:45:06 INFO: STATUS: PASS, 3/3 test cases, 100.00 percent executed
 
189
    23 Feb 2011 11:45:06 INFO: Spent 141 / 142 seconds on: TEST(s)
 
190
    23 Feb 2011 11:45:06 INFO: Test execution complete
 
191
    23 Feb 2011 11:45:06 INFO: Stopping all running servers...
 
192
 
 
193
Cleanup mode
 
194
-------------
 
195
A cleanup mode is provided for user convenience.  This simply shuts down
 
196
any servers whose pid files are detected in the dbqp workdir.  It is mainly
 
197
intended as a quick cleanup for post-testing with :option:`--start-and-exit`::
 
198
 
 
199
        ./dbqp.py --mode=cleanup
 
200
 
 
201
    Setting --start-dirty=True for cleanup mode...
 
202
    23 Feb 2011 11:35:59 INFO: Using Drizzle source tree:
 
203
    23 Feb 2011 11:35:59 INFO: basedir: drizzle
 
204
    23 Feb 2011 11:35:59 INFO: clientbindir: drizzle/client
 
205
    23 Feb 2011 11:35:59 INFO: testdir: drizzle/tests
 
206
    23 Feb 2011 11:35:59 INFO: server_version: 2011.02.2188
 
207
    23 Feb 2011 11:35:59 INFO: server_compile_os: unknown-linux-gnu
 
208
    23 Feb 2011 11:35:59 INFO: server_platform: x86_64
 
209
    23 Feb 2011 11:35:59 INFO: server_comment: (Source distribution (dbqp_randgen))
 
210
    23 Feb 2011 11:35:59 INFO: Using --start-dirty, not attempting to touch directories
 
211
    23 Feb 2011 11:35:59 INFO: Using default-storage-engine: innodb
 
212
    23 Feb 2011 11:35:59 INFO: Using testing mode: cleanup
 
213
    23 Feb 2011 11:35:59 INFO: Killing pid 10484 from drizzle/tests/workdir/testbot0/server0/var/run/server0.pid
 
214
    23 Feb 2011 11:35:59 INFO: Stopping all running servers...
 
215
 
 
216
Program architecture
 
217
====================
 
218
 
 
219
:program:`dbqp.py`'s 'dtr' mode uses a simple diff-based mechanism for testing.
 
220
This is the default mode and where the majority of Drizzle testing occurs.  
 
221
It will execute the statements contained in a test and compare the results 
 
222
to pre-recorded expected results.  In the event of a test failure, you
 
223
will be presented with a diff::
 
224
 
 
225
    main.exp1                                                    [ fail ]
 
226
    --- drizzle/tests/r/exp1.result     2010-11-02 02:10:25.107013998 +0300
 
227
    +++ drizzle/tests/r/exp1.reject     2010-11-02 02:10:32.017013999 +0300
 
228
    @@ -5,4 +5,5 @@
 
229
    a
 
230
    1
 
231
    2
 
232
    +3
 
233
    DROP TABLE t1;
 
234
 
 
235
A test case consists of a .test and a .result file.  The .test file includes
 
236
the various statements to be executed for a test.  The .result file lists
 
237
the expected results for a given test file.  These files live in tests/t 
 
238
and tests/r, respectively.  This structure is the same for all test suites.
 
239
 
 
240
dbqp.py options
 
241
===================
 
242
 
 
243
The :program:`dbqp.py` tool has several available options:
 
244
 
 
245
./dbqp.py [ OPTIONS ] [ TESTCASE ]
 
246
 
 
247
 
 
248
Options
 
249
-------
 
250
 
 
251
.. program:: dbqp.py
 
252
 
 
253
.. option:: -h, --help
 
254
 
 
255
   show this help message and exit
 
256
 
 
257
Options for the test-runner itself
 
258
----------------------------------
 
259
 
 
260
.. program:: dbqp.py
 
261
 
 
262
.. option:: --force
 
263
 
 
264
    Set this to continue test execution beyond the first failed test
 
265
 
 
266
.. option:: --start-and-exit
 
267
 
 
268
   Spin up the server(s) for the first specified test then exit 
 
269
   (will leave servers running)
 
270
 
 
271
.. option:: --verbose
 
272
 
 
273
   Produces extensive output about test-runner state.  
 
274
   Distinct from --debug
 
275
 
 
276
.. option:: --debug
 
277
 
 
278
   Provide internal-level debugging output.  
 
279
   Distinct from --verbose
 
280
 
 
281
.. option:: --mode=MODE
 
282
 
 
283
   Testing mode.  
 
284
   We only support dtr...for now >;) 
 
285
   [dtr]
 
286
 
 
287
.. option:: --record
 
288
 
 
289
   Record a testcase result 
 
290
   (if the testing mode supports it) 
 
291
   [False]
 
292
 
 
293
.. option:: --fast
 
294
 
 
295
   Don't try to cleanup from earlier runs 
 
296
   (currently just a placeholder) [False]
 
297
 
 
298
.. option:: --randgen-path=RANDGENPATH
 
299
 
 
300
    The path to a randgen installation that can be used to
 
301
    execute randgen-based tests
 
302
 
 
303
 
 
304
Options for controlling which tests are executed
 
305
------------------------------------------------
 
306
 
 
307
.. program:: dbqp.py
 
308
 
 
309
.. option:: --suite=SUITELIST
 
310
 
 
311
   The name of the suite containing tests we want. 
 
312
   Can accept comma-separated list (with no spaces). 
 
313
   Additional --suite args are appended to existing list 
 
314
   [autosearch]
 
315
 
 
316
.. option:: --suitepath=SUITEPATHS 
 
317
 
 
318
   The path containing the suite(s) you wish to execute. 
 
319
   Use on --suitepath for each suite you want to use.
 
320
 
 
321
.. option:: --do-test=DOTEST
 
322
 
 
323
   input can either be a prefix or a regex. 
 
324
   Will only execute tests that match the provided pattern
 
325
 
 
326
.. option:: --skip-test=SKIPTEST
 
327
 
 
328
   input can either be a prefix or a regex.  
 
329
   Will exclude tests that match the provided pattern
 
330
 
 
331
.. option:: --reorder
 
332
 
 
333
   sort the testcases so that they are executed optimally
 
334
   for the given mode [False]
 
335
 
 
336
.. option:: --repeat=REPEAT     
 
337
 
 
338
    Run each test case the specified number of times.  For
 
339
    a given sequence, the first test will be run n times,
 
340
    then the second, etc [1]
 
341
 
 
342
Options for defining the code that will be under test
 
343
-----------------------------------------------------
 
344
 
 
345
.. program:: dbqp.py
 
346
 
 
347
.. option:: --basedir=BASEDIR   
 
348
 
 
349
   Pass this argument to signal to the test-runner 
 
350
   that this is an in-tree test (not required).  
 
351
   We automatically set a number of variables 
 
352
   relative to the argument (client-bindir, 
 
353
   serverdir, testdir) [../]
 
354
 
 
355
.. option:: --serverdir=SERVERPATH
 
356
 
 
357
   Path to the server executable.  [auto-search]
 
358
 
 
359
.. option:: --client-bindir=CLIENTBINDIR
 
360
 
 
361
   Path to the directory containing client program
 
362
   binaries for use in testing [auto-search]
 
363
 
 
364
.. option:: --default-storage-engine=DEFAULTENGINE
 
365
                        
 
366
   Start drizzled using the specified engine [innodb]
 
367
 
 
368
Options for defining the testing environment
 
369
--------------------------------------------
 
370
 
 
371
.. program:: dbqp.py
 
372
 
 
373
.. option:: --testdir=TESTDIR   
 
374
 
 
375
    Path to the test dir, containing additional files for
 
376
    test execution. [pwd]
 
377
 
 
378
.. option:: --workdir=WORKDIR   
 
379
 
 
380
   Path to the directory test-run will use to store
 
381
   generated files and directories.
 
382
   [basedir/tests/dbqp_work]
 
383
 
 
384
.. option:: --top-srcdir=TOPSRCDIR
 
385
 
 
386
   build option [basedir_default]
 
387
 
 
388
.. option:: --top-builddir=TOPBUILDDIR
 
389
 
 
390
   build option [basedir_default]
 
391
 
 
392
.. option:: --no-shm            
 
393
 
 
394
   By default, we symlink workdir to a location in shm.
 
395
   Use this flag to not symlink [False]
 
396
 
 
397
.. option:: --start-dirty       
 
398
 
 
399
   Don't try to clean up working directories before test
 
400
   execution [False]
 
401
 
 
402
.. option:: --no-secure-file-priv
 
403
                        
 
404
   Turn off the use of --secure-file-priv=vardir for
 
405
   started servers
 
406
 
 
407
Options to pass options on to the server
 
408
-----------------------------------------
 
409
 
 
410
.. program:: dbqp.py
 
411
 
 
412
.. option:: --drizzled=DRIZZLEDOPTIONS
 
413
           
 
414
    Pass additional options to the server.  Will be passed
 
415
    to all servers for all tests (mostly for --start-and-
 
416
    exit)
 
417
 
 
418
 
 
419
Options for defining the tools we use for code analysis (valgrind, gprof, gcov, etc)
 
420
------------------------------------------------------------------------------------
 
421
 
 
422
.. program:: dbqp.py
 
423
 
 
424
.. option:: --valgrind          
 
425
 
 
426
   Run drizzletest and drizzled executables using
 
427
   valgrind with default options [False]
 
428
 
 
429
.. option:: --valgrind-option=VALGRINDARGLIST
 
430
                       
 
431
   Pass an option to valgrind (overrides/removes default
 
432
   valgrind options)
 
433
 
 
434
Options for controlling the use of debuggers with test execution
 
435
----------------------------------------------------------------
 
436
 
 
437
.. program:: dbqp.py
 
438
 
 
439
.. option:: --gdb
 
440
 
 
441
    Start the drizzled server(s) in gdb
 
442
 
 
443
.. option:: --manual-gdb
 
444
 
 
445
    Allows you to start the drizzled server(s) in gdb
 
446
    manually (in another window, etc
 
447
 
 
448
Options to call additional utilities such as datagen
 
449
------------------------------------------------------
 
450
 
 
451
.. program:: dbqp.py
 
452
 
 
453
.. option:: --gendata=GENDATAFILE
 
454
            
 
455
    Call the randgen's gendata utility to use the
 
456
    specified configuration file.  This will populate the
 
457
    server prior to any test execution
 
458