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
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
These are the assorted notes that will be turned into a manual eventually.
==========================
Tests are organized in suites.
A "suite" is a subdirectory inside, one of,
<basedir>/mysql-test/suite
<basedir>/mysql-test
<basedir>/share/mysql-test/suite
<basedir>/share/mysql-test
<basedir>/share/mysql/mysql-test/suite
<basedir>/share/mysql/mysql-test
<basedir>/storage/*/mysql-test-suites
This is supposed to cover running mtr from a source directory and installed.
==========================
A suite contains *.test and *.result files. They can be in the t/ and r/
subdirectories under the suitedir or directly in the suitedir
(that is suitedir/t/*.test or suitedir/*.test, same for *.result))
==========================
A suite can contain a suite.opt file - at the same location where .test files
are or in the suite directory. As usual, the .opt file can use $-substitutions
for the environment variables.
Usually, using my.cnf template (see below) is preferrable.
But command line options (.opt files and combinations file) get special
treatment - they can have special options that affect mtr behavior. cnf
files cannot. Special options are
--timezone, --plugin-load, --result-file, --config-file-template,
--default-time-zone, --force-restart
In particular, all --plugin-load instances on the command line (on the
combined command line, assembled from different .opt and combinations
files) are merged into one. That is, if, say, test-master.opt file contains
--plugin-load=aaa.so and suite.opt has --plugin-load=bbb.so that mysqld
will get --plugin-load=aaa.so:bbb.so. Also, empty --plugin-load options are
removed from the command line. Which means that one can safely specify
--plugin-load=$AAA_SO and if aaa.so was not built (perhaps, the plugin was
statically linked into the server), the .opt file will not result in the
invalid command line option that can cause the server to refuse to start.
==========================
A suite can have suite.pm file in the suitedir. It must declare a
package that inherits from My::Suite.
The suite.pm needs to have @ISA=qw(My::Suite) and it must end
with bless {}; - that is it must return an object of that class.
It can also return a string - in this case all tests in the suite
will be skipped, with this string being printed as a reason.
A suite class can define config_files(), servers(), list_cases(),
and start_test() methods.
A config_files() method returns a list of additional config files (besides
my.cnf), that this suite needs to be created. For every file it specifies
a function that will create it, when given a My::Config object. For example:
sub config_files { ( 'config.ini' => \&write_ini, 'new.conf' => \&do_new ) }
A servers() method returns a list of processes that needs to be started for
this suite. A process is specified as a pair (regex, hash). A regex must
match a section in the my.cnf template (for example, qr/mysqld\./ corresponds
to all mysqld processes), a hash contains these options:
SORT => a number, processes are started in the order of increasing SORT
values (and stopped in the reverse order). mysqld has number 300.
START => a function to start a process. It takes two arguments,
My::Config::Group and My::Test. If START is undefined the process
will not be started.
WAIT => a function waits for the process to be started. It takes
My::Config::Group as an argument. Internallys mtr first invokes
START for all processes, then WAIT for all started processes.
example: sub servers { ( qr/^foo$/ => { SORT => 200,
START => \&start_foo,
WAIT => \&wait_foo } ) }
See sphinx suite for an example.
A list_cases() method returns a complete list of cases for this suite.
By default it will be the list of files that have .test extension,
but without the extension. This list will be filtered by mtr, subject to
different mtr options (--big-test, --start-from, etc), the suite does not have
to do it.
A start_test() method starts one test process, by default it will be mysqltest.
See unit suite for an example of list_cases() and start_test() methods.
==========================
A suite can have my.cnf template file in the suitedir.
A my.cnf template uses a normal my.cnf syntax - groups, options,
and values - with templating extensions. They are
* There can be groups with non-standard names, not used by mysqld.
These groups may be used by the suite.pm file somehow.
For example, they can be written to the additional config files.
See sphinx suite for an example.
* There can be ENV group. It sets values for the environment variables.
* Values can refer to each other - they will be expanded as needed.
A reference to a value of an option looks like @groupname.optionname.
For example
[mysqld.2]
master-port= @mysqld.1.port
it sets the master-port in the mysqld.2 group to the value of
port in the mysqld.1 group.
* An option name may start from '#'. In the resulting my.cnf it will look
like a comment, but it still can be referred to. For example:
[example]
#foo = localhost:@mysqld.1.port
bar = http://@example.#foo/index.html
* There are two special - in this regard - groups.
Via the ENV group one can refer to any environment variable, not only
to values in the [ENV] group of my.cnf file.
Via the OPT group one can refer to special values:
@OPT.vardir - a path to vardir
@OPT.port - a new port number is reserved out of the pool. It will not
match any other port number used by this test run.
See sphinx suite for an example.
Most probably a suite my.cnf will need to start from
!include include/default_my.cnf
and then modify the configuration as necessary.
==========================
A suite can have combinations file in the suitedir. It uses my.cnf syntax
but it cannot use @-substitutions. Instead, it can use $-substitutions for
the environment variables. Because the combination options will not be
merged to a my.cnf, but will be added to the command line. Example:
[conf1]
opt1=val1
[conf2]
opt1=val2
opt2=$HAVE_SOMETHING
Such a file will cause every test from the suite to be run twice - once
with mysqld using --opt1=val1 and the other one with mysqld using
--opt1=val2 --opt2=$HAVE_SOMETHING
One can limit mtr run to a subset of combinations by setting environment
variable SUITENAME_COMBINATIONS to the ':'-separated set of combination
names. E.g.
RPL_COMBINATIONS=mix:row ./mtr --suite rpl
See innodb suite for an example of how suite.pm may set this variable
to exclude unsupported configurations.
==========================
|
