mcs/class/System.Data/Test/DataProviderTests/README

   1 Test Framework for Ado.NET\r
   2 December 23, 2004\r
   3 \r
   4 \r
   5 Table of Contents\r
   6 \r
   7     1.0 Overview\r
   8     2.0 Requirements\r
   9     3.0 Design\r
  10         3.1 Various Components\r
  11         3.2 Low Level Design\r
  12 \r
  13     4.0 Setup\r
  14         4.1 Database Setup\r
  15         4.2 Configuration\r
  16         4.3 How to add new database / tables / values\r
  17 \r
  18     5.0 DataReader tests:\r
  19         5.1 Control Flow\r
  20         5.2 Configuration files\r
  21         5.3 How to add new queries\r
  22 \r
  23     6.0 DataAdapter tests\r
  24         6.1 Control Flow\r
  25         6.2 Configuration files\r
  26         6.3 How to add new queries\r
  27 \r
  28     7.0 Running the tests\r
  29 \r
  30     8.0 ToDo List\r
  31 \r
  32  \r
  33 \r
  34 1.0  Overview\r
  35 \r
  36         This framework aims at testing various database providers \r
  37         using a common set of testcases and comparing the results \r
  38         with a static list. This framework abstracts \r
  39         the connection, table- creation and other user operations.\r
  40 \r
  41 \r
  42 2.0  Requirements\r
  43 \r
  44         These are the high-level requirements :\r
  45 \r
  46                 * The framework should abstract database, table, \r
  47                   sql queries and other user operations.\r
  48                 * The framework should provide for the setup of \r
  49                   database tables and store procedures required \r
  50                   before the actual tests start.\r
  51                 * The framework should provide for comparison of\r
  52                   results.\r
  53                 * One should be able to run the tests for any or all\r
  54                   of the databases\r
  55                 * Should be extensible for newer databases\r
  56 \r
  57 \r
  58 3.0  Design \r
  59   \r
  60   3.1  Various Components:\r
  61 \r
  62         The various components of the framework are :\r
  63         \r
  64                 a) Setup / Teardown of database Tables / Stored Procedures :\r
  65                    This component is used to create test database for each of \r
  66                    the databases to be tested. It will create tables / stored \r
  67                    procedures /views based on testing requirements. After \r
  68                    creating tables, it also populates values (including \r
  69                    negative/border values) in the tables.\r
  70                 \r
  71                 b) Tests for DataProvider Code :\r
  72                    The tests contained in this component try to connect  \r
  73                    to database, create commands, execute them, and retrieve \r
  74                    results. In this component, the retrieved results are \r
  75                    placed in a DataReader and are processed from there only.\r
  76                 \r
  77                 c) Tests for System.Data Code :\r
  78                    These tests are similar to tests in (c) , except that the \r
  79                    results retrieved from the database are populated in a \r
  80                    DataSet, which represents an in-memory cache of data.\r
  81                    Changes made to this DataSet are re-conciliated with the \r
  82                    database. \r
  83                 \r
  84                 d) Results comparison:\r
  85                    This does not exist as a independent component, but is \r
  86                    an inevitable part of (c) and (d). This involves comparing \r
  87                    the values retrieved from the database with the actual\r
  88                    values entered.\r
  89         \r
  90   3.2  Low Level Design \r
  91 \r
  92         Setup/Teardown of database tables/stored procedures :\r
  93 \r
  94                 * All the operations to be performed on the database (like \r
  95                   creating, dropping,  inserting values ) are specified in \r
  96                   a config file. All the data necessary for carrying out these\r
  97                   operations (like the connection parameters, table description, \r
  98                   column values, column types) are also specified in the \r
  99                   config (XML) file.\r
 100 \r
 101                 * The first column of each table is the serial no and is \r
 102                   essentially the primary key. This is done to enforce \r
 103                   ordering while data retrieval.\r
 104 \r
 105                 * If any constraints have to be defined, they also have to be\r
 106                   added to this config file.\r
 107 \r
 108                 * Generic stored procedures (that are same for all tables,\r
 109                   e.g. retrieving values from a table) are also described in\r
 110                   the config file in the form of a template. This template has \r
 111                   appropriate tags for table names and columns. By replacing these \r
 112                   tags with actual names, we get the script for a stored \r
 113                   procedure. These kinds of stored procedures, if defined, are \r
 114                   created for all the tables described in the config file.\r
 115 \r
 116                 * For stored procedures using two or more tables,  appropriate \r
 117                   tags have to be mentioned in the template. For example,\r
 118                   the tag [[TAB2]] will have to be replaced by the name of \r
 119                   the second table, the tag [[TAB2-COL1]] will have to replaced \r
 120                   by the name of first column of the second table and so on. This\r
 121                   is yet to be implemented.\r
 122 \r
 123                 * For tests involving DataAdapter, Dataset, the changes that \r
 124                   need to be done to the dataset and reconciled back to the\r
 125                   database are also mentioned in the config file.\r
 126 \r
 127         Data Provider Tests :\r
 128                 \r
 129                 There is a base class which defines those members and methods \r
 130                 that would be common for all databases. This class essentially \r
 131                 contains members to hold the connection, commands, data readers, \r
 132                 dataset, data adapter, etc. and has methods to query / update \r
 133                 the database and compare the retrieved data against the actual \r
 134                 data entered (as in the config file).\r
 135 \r
 136                 We then derive a class specific to each database from this base \r
 137                 class. These derived classes have code specific to each database.\r
 138 \r
 139     4.0 Setup\r
 140 \r
 141         4.1 Database Setup\r
 142                 \r
 143                 As mentioned in section 3.2, all the database operations and\r
 144                 the required data has to be specified in a config file.\r
 145                 Right now, this framework supports only four databases :\r
 146 \r
 147                         * MySql\r
 148                         * MsSql\r
 149                         * Oracle\r
 150                         * Postgres\r
 151 \r
 152         4.2 Configuration\r
 153 \r
 154                 The configuration file is an XML file in which there is a \r
 155                 configuration section corresponding to each database. Under each \r
 156                 such section, we have the following data :\r
 157 \r
 158                         1) User operations : Create/Drop tables or Insert data\r
 159 \r
 160                         2) Connection parameters : Connection strings (for connecting\r
 161                                                    through ODBC and in the normal way)\r
 162                         3) Table definition :\r
 163                                 a) Table name\r
 164                                 b) Names and Types of columns\r
 165                                 c) Any other constraints\r
 166 \r
 167                         4) Data to be inserted into each table :\r
 168                                 a) Table number in which to enter data\r
 169                                 b) number of rows\r
 170                                 c) value to be entered in each column of various rows\r
 171 \r
 172                         5) StoredProcedures:\r
 173                                 a) Type of stored procedure (only 'generic' type is\r
 174                                    supported as of now)\r
 175                                 b) Name of the stored procedure\r
 176                                 c) Number of statements it has\r
 177                                 d) Template of the stored procedure body\r
 178 \r
 179 \r
 180         4.3 How to add new database / tables / values\r
 181 \r
 182                 For adding new databases, we will have to add appropriate \r
 183                 data to the config file. Also we need to add code for connecting\r
 184                 to the new database using appropriate providers.\r
 185 \r
 186                 Adding a new table to an existing database or additional rows\r
 187                 to an existing table, is just a config file change. While \r
 188                 changing the config file, one must make sure that the number \r
 189                 of tables/columns/rows are consistent with the data.\r
 190 \r
 191 \r
 192     5.0 DataReader tests:\r
 193 \r
 194         5.1 Configuration :\r
 195 \r
 196                 Apart from the configuration parameteres listed in sec 4.2, \r
 197                 here the config file also contains the queries to be run on\r
 198                 each table.\r
 199 \r
 200         5.2 Control Flow\r
 201 \r
 202                 The control flow goes like this :\r
 203                   1) Create a database connection and command\r
 204                   2) Run each of the query and retrieve the data using a DataReader\r
 205                   3) Parse the query to find out what all columns were selected \r
 206                      and from which table\r
 207                   4) Verify the data in the DataReader against the ones in the \r
 208                      config file.\r
 209 \r
 210         5.3 How to add new queries\r
 211 \r
 212             Add appropriate entries to the config file.\r
 213 \r
 214 \r
 215     6.0 DataAdapter tests\r
 216 \r
 217         6.1 Configuration files\r
 218 \r
 219                 In addition to the configuration parameters mentioned in sec 5.1, \r
 220                 we also have a list of changes to be done to each table. These\r
 221                 are the changes that have to done to a DataSet before updating\r
 222                 the database.\r
 223                 A change description contains the row and the column number to \r
 224                 be changed and the value.\r
 225 \r
 226         6.2 Control Flow\r
 227 \r
 228                 The control flow goes like this :\r
 229                   1) Create a database connection and command\r
 230                   2) Fill a DataSet by running each of the query specified \r
 231                      in the config file\r
 232                   3) Parse the query to find out what all columns were selected \r
 233                      and from which table\r
 234                   4) Verify the data in the DataSet against the ones in the \r
 235                      config file.\r
 236                   5) Select all data from each table.\r
 237                   6) Make appropriate changes to the DataSet and update \r
 238                      the database\r
 239                   7) Clear and Fill the DataSet again.\r
 240                   8) Verify the data in the DataSet against the ones in the \r
 241                      config file considering the changes done.\r
 242 \r
 243         6.3 How to add new queries\r
 244 \r
 245                 Config file change.\r
 246 \r
 247     7.0 Running the tests\r
 248 \r
 249         The setup and the tests can be done by issuing a \r
 250         \r
 251         'make run-test' \r
 252         \r
 253         under 'System.Data/Test/DataProviderTests' directory. Doing this will\r
 254         first do the setup of databases and run tests for data readers and\r
 255         data adapters.\r
 256         \r
 257         Doing a 'make run-test' under any of the subdirectories 'datadaptertests'\r
 258         or 'datareadertests' will run the tests for Data Apadters and \r
 259         DataReaders only.\r
 260 \r
 261         To run tests for a specific database, one needs to do a :\r
 262 \r
 263         'make DATABASE=<db> run-test'\r
 264 \r
 265     8.0 ToDo List\r
 266 \r
 267         * To make the framework more extensible\r
 268         * Right now the framework understands simple queries (like select) only.\r
 269           Also querying from only one table is supported as of now. The frameowrk \r
 270           should be a able to understand other kinds of queries too.\r
 271         * Only generic stored procedures (common for all tables) are supported \r
 272           as of now. We might want to extend this to be able to write stored-procedures\r
 273           spanning more than one table, etc\r
 274         * Integrate with the daily tests\r
 275         * Better error reporting\r
 276     \r