← Back to branch summary

~jan-kneschke/mysql-proxy/packet-tracking-assertions

« back to all changes in this revision

Viewing changes to tags/mysql-proxy-0.6.1/README.TESTS

  • Committer: Kay Roepke
  • Author(s): Jan Kneschke
  • Date: 2008-01-23 22:00:28 UTC
  • Revision ID: kay@mysql.com-20080123220028-hq2xqb69apa75fnx
first round on mysql-shell based on the proxy code

this is mostly a verification if the proxy-code is flexible enough to handle 
all three scenarios of: client, server and forwarding (proxy)

Show diffs side-by-side

added added

removed removed

Lines of Context:
tags/mysql-proxy-0.6.1/README.TESTS
 
1
TESTING OVERVIEW
 
2
----------------
 
3
 
 
4
The normal test suite is under ./tests/suite/base
 
5
Run it with 
 
6
 
 
7
$ make check
 
8
 
 
9
 
 
10
Or if you want to run it manually, do
 
11
 
 
12
$ lua tests/run-tests.lua tests/suite/base
 
13
 
 
14
CREATING A NEW TEST CASE
 
15
------------------------
 
16
A test case in this testing environment is made of the following components
 
17
 
 
18
./t/test_name.test
 
19
./t/test_name.lua      (optional)
 
20
./t/test_name.options  (optional)  
 
21
./r/test_name.result
 
22
 
 
23
The basics are like in the server test suite.
 
24
 
 
25
a ./t/test_name.test contains SQL statements and mysqltest commands as defined in the manual
 
26
http://dev.mysql.com/doc/mysqltest/en/mysqltest-commands.html
 
27
 
 
28
The corresponding ./r/test_name.result contains the output of the statements above, as produced by mysqltest.
 
29
 
 
30
In addition to the above basics, when preparing a test case for MySSQL Proxy, you can add the following ones:
 
31
 
 
32
./t/test_name.lua
 
33
This is a Lua script that gets loaded to MySQL Proxy before the test starts.
 
34
If no such test is defined, the Proxy starts with an empty script.
 
35
 
 
36
./t/test_name.options
 
37
This file contains Lua instructions that are executed before the test.
 
38
For the user's convenience, there are a few functions that you can call from this file
 
39
 
 
40
   * start_proxy(proxy_name, options_table)
 
41
     starts a proxy instance, with given parameters. The proxy name is
 
42
     used to retrieve information about this instance, to use the proxy
 
43
     or to remove it
 
44
     example:
 
45
     start_proxy('my_name', 
 
46
       {
 
47
        ["proxy-backend-addresses"] = PROXY_HOST .. ':' .. PROXY_MASTER_PORT ,
 
48
        ["proxy-read-only-backend-addresses"] = PROXY_HOST .. ':' .. PROXY_SLAVE_PORT ,
 
49
        ["proxy-address"]           = PROXY_HOST .. ':' .. PROXY_PORT ,
 
50
        ["admin-address"]           = PROXY_HOST .. ':' .. ADMIN_PORT ,
 
51
        ["pid-file"]                = PROXY_PIDFILE,
 
52
        ["proxy-lua-script"]        = 'my_name.lua',
 
53
        })
 
54
    
 
55
    As illustrated, there are several global variables that can be referenced within this
 
56
    options file:
 
57
    PROXY_HOST
 
58
    PROXY_PORT
 
59
    ADMIN_PORT
 
60
    (TODO: complete the list)
 
61
 
 
62
   * stop_proxy()
 
63
     removes all proxy instances created with start_proxy()
 
64
 
 
65
   * simulate_replication([master_options,slave_options])
 
66
     starts two instances of the proxy, both pointing to the same
 
67
     backend server. You can connect to a real replication, by
 
68
     supplying appropriate options
 
69
 
 
70
   * chain_proxy(first_lua_script, second_lua_script [, use_replication])
 
71
     starts two proxy instances, the first one pointing to the backend
 
72
     server, the second one pointing to the first instance.
 
73
     If use_replication is given (boolean), then a master backend is used
 
74
     instead of a real backend. If no master/slave replication is
 
75
     available, simulate_replication() is called
 
76
 
 
77
   * sql_execute(queries, proxy_name)
 
78
     sends one or more queries to a given proxy. ('queries' can be either
 
79
     a string or an array of strings)
 
80
     If no proxy name is provided, the query is sent to the backend server.
 
81
 
 
82
 
 
83
 
 
84
 
 
85
SKIPPING TESTS
 
86
--------------
 
87
 
 
88
If you want to skip one or more tests, edit the file suite_name/tests_to_skip.lua
 
89
 
 
90
 
 
91
CREATING A NEW TEST SUITE
 
92
-------------------------
 
93
 
 
94
The Proxy test suite follows the same principles used by the server test suite.
 
95
There is a directory (usually ./t) containing .test scripts, with the 
 
96
instructions to run. And there is another directory (./r) containing the
 
97
expected results. For each .test file in ./t, there must be a corresponding 
 
98
.tesult file in ./r
 
99
For more information on the test framework, see the manual.
 
100
http://dev.mysql.com/doc/mysqltest/en/index.html
 
101
 
 
102
To run your test suite, create a directory under ./trunk/tests/suite, add two 
 
103
subdirectories /t and /r, and then use the above mentioned command.
 
104
For example:
 
105
 
 
106
$ mkdir tests/suite/myapp
 
107
$ mkdir tests/suite/myapp/t
 
108
$ mkdir tests/suite/myapp/r
 
109
 
 
110
# add test and result files under t and r
 
111
 
 
112
$ lua tests/run-tests.lua tests/suite/myapp
 
113
 
 
114
LIBRARY PATHS
 
115
-------------
 
116
The test suite uses the following paths to search for Lua libraries when 
 
117
a 'require' statement is issued. Each path is associated to an environment 
 
118
variable:
 
119
 
 
120
This directory contains Lua libraries
 
121
  variable       default                   description
 
122
  -------------- ------------------------- -----------------------
 
123
  LUA_LDIR       /usr/share/lua/5.1/?.lua  server wide Lua libraries
 
124
  LUA_PATH       /usr/local/share/?.lua    MySQL Proxy Lua libraries
 
125
  LUA_USER_PATH  ./trunk/lib/?.lua         user defined libraries
 
126
 
 
127
In addition to the above paths, the current suite is searched for
 
128
libraries as well. 
 
129
    suite_name ..  '/t/?.lua'  
 
130
 
 
131
TROUBLESHOOTING
 
132
---------------
 
133
 
 
134
If Lua complains about missing the lfs library, prepend the LUA_CPATH variable to the actual command:
 
135
$ LUA_CPATH='tests/.libs/?.so' lua tests/run-tests.lua tests/suite/base
 
136
 
 
137
If the test suite complains about access denied, perhaps you need to provide a password. 
 
138
The default user for the test suite is 'root', with no password.
 
139
If you want to run the tests with a different username and password, 
 
140
set the following environment variables
 
141
MYSQL_USER
 
142
MYSQL_PASSWORD
 
143