~diego-fmpwizard/mysql-proxy/bug-43424

TESTING OVERVIEW

----------------

The normal test suite is under ./tests/suite/base

Run it with 

$ make check

Or if you want to run it manually, do

$ lua tests/run-tests.lua tests/suite/base

CREATING A NEW TEST CASE

------------------------

A test case in this testing environment is made of the following components

./t/test_name.test

./t/test_name.lua      (optional)

./t/test_name.options  (optional)  

./r/test_name.result

The basics are like in the server test suite.

a ./t/test_name.test contains SQL statements and mysqltest commands as defined in the manual

http://dev.mysql.com/doc/mysqltest/en/mysqltest-commands.html

The corresponding ./r/test_name.result contains the output of the statements above, as produced by mysqltest.

In addition to the above basics, when preparing a test case for MySSQL Proxy, you can add the following ones:

./t/test_name.lua

This is a Lua script that gets loaded to MySQL Proxy before the test starts.

If no such test is defined, the Proxy starts with an empty script.

./t/test_name.options

This file contains Lua instructions that are executed before the test.

For the user's convenience, there are a few functions that you can call from this file

   * start_proxy(proxy_name, options_table)

     starts a proxy instance, with given parameters. The proxy name is

     used to retrieve information about this instance, to use the proxy

     or to remove it

     example:

     start_proxy('my_name', 

       {

        ["proxy-backend-addresses"] = PROXY_HOST .. ':' .. PROXY_MASTER_PORT ,

        ["proxy-read-only-backend-addresses"] = PROXY_HOST .. ':' .. PROXY_SLAVE_PORT ,

        ["proxy-address"]           = PROXY_HOST .. ':' .. PROXY_PORT ,

        ["admin-address"]           = PROXY_HOST .. ':' .. ADMIN_PORT ,

        ["pid-file"]                = PROXY_PIDFILE,

        ["proxy-lua-script"]        = 'my_name.lua',

        })

    As illustrated, there are several global variables that can be referenced within this

    options file:

    PROXY_HOST

    PROXY_PORT

    ADMIN_PORT

    (TODO: complete the list)

   * stop_proxy()

     removes all proxy instances created with start_proxy()

   * simulate_replication([master_options,slave_options])

     starts two instances of the proxy, both pointing to the same

     backend server. You can connect to a real replication, by

     supplying appropriate options

   * chain_proxy(first_lua_script, second_lua_script [, use_replication])

     starts two proxy instances, the first one pointing to the backend

     server, the second one pointing to the first instance.

     If use_replication is given (boolean), then a master backend is used

     instead of a real backend. If no master/slave replication is

     available, simulate_replication() is called

   * sql_execute(queries, proxy_name)

     sends one or more queries to a given proxy. ('queries' can be either

     a string or an array of strings)

     If no proxy name is provided, the query is sent to the backend server.

SKIPPING TESTS

--------------

If you want to skip one or more tests, edit the file suite_name/tests_to_skip.lua

CREATING A NEW TEST SUITE

-------------------------

The Proxy test suite follows the same principles used by the server test suite.

There is a directory (usually ./t) containing .test scripts, with the 

instructions to run. And there is another directory (./r) containing the

expected results. For each .test file in ./t, there must be a corresponding 

.tesult file in ./r

For more information on the test framework, see the manual.

http://dev.mysql.com/doc/mysqltest/en/index.html

To run your test suite, create a directory under ./trunk/tests/suite, add two 

subdirectories /t and /r, and then use the above mentioned command.

For example:

$ mkdir tests/suite/myapp

$ mkdir tests/suite/myapp/t

$ mkdir tests/suite/myapp/r

# add test and result files under t and r

$ lua tests/run-tests.lua tests/suite/myapp

LIBRARY PATHS

-------------

The test suite uses the following paths to search for Lua libraries when 

a 'require' statement is issued. Each path is associated to an environment 

variable:

This directory contains Lua libraries

  variable       default                   description

  -------------- ------------------------- -----------------------

  LUA_LDIR       /usr/share/lua/5.1/?.lua  server wide Lua libraries

  LUA_PATH       /usr/local/share/?.lua    MySQL Proxy Lua libraries

  LUA_USER_PATH  ./trunk/lib/?.lua         user defined libraries

In addition to the above paths, the current suite is searched for

libraries as well. 

    suite_name ..  '/t/?.lua'  

TROUBLESHOOTING

---------------

If Lua complains about missing the lfs library, prepend the LUA_CPATH variable to the actual command:

$ LUA_CPATH='tests/.libs/?.so' lua tests/run-tests.lua tests/suite/base

If the test suite complains about access denied, perhaps you need to provide a password. 

The default user for the test suite is 'root', with no password.

If you want to run the tests with a different username and password, 

set the following environment variables

MYSQL_USER

MYSQL_PASSWORD