tests/README

   1 * RUNNING THE REGRESSION SUITE
   2
   3 This test suite looks for a configuration file named
   4 ".clsql-test.config" located in the users home directory. This file
   5 contains a single assoc-list that specifies the connection specs for
   6 each database type to be tested. There is an example file in
   7 contained in CLSQL's examples directory.
   8
   9 These tests require the downloading of the rt package from
  10 http://files.b9.com/.
  11
  12 Load clsql.asd or put it somewhere where ASDF can find it
  13 and call:
  14
  15 (asdf:oos 'asdf:test-op 'clsql)
  16
  17 The test suite will then automatically run on all of the backends that
  18 you have defined in .clsql-test.config
  19
  20 * REGRESSION TEST SUITE GOALS
  21
  22 The intent of this test suite is to provide sufficient coverage for
  23 the system to support the following:
  24
  25 ** Refactoring and Redesign of particular subsystems
  26
  27 Refactoring and redesign efforts are normally restricted to a single
  28 subsystem, or perhaps to interdependent subsystems.  In such cases, a
  29 set of regression tests which excercise the existing interface of the
  30 rest of CLSQL to the changing subsystems should be in place and passing
  31 before the coding starts.
  32
  33 ** Ensuring portability and Supporting new ports.
  34
  35 The more coverage the test suite provides the easier portability is to
  36 maintain, particularly if we have instances of the test suite running
  37 against the head on the supporting lisp environment/OS/hardware/DBMS
  38 combinations.  Since no individual within the project has the ability
  39 to run all of those combinations themselves, we are dependent upon some
  40 informal coordination between the mintainers of the various ports.
  41
  42 ** Adding new RDBMS backends
  43
  44 The entire CLSQL DBMS interface needs to be excercised by the test
  45 suite, such that a new RDBMS backend that passes all the tests can be
  46 reasonably assured of working with the CLSQL layers above that.  These
  47 tests should also serve as impromptu documentation for the details of
  48 that interface and what it expects frothe RDBMS driver layers.
  49
  50 ** Bug identification and QA
  51
  52 As new bugs are identified, they should have a regression test written
  53 which excercises them. This is to ensue that we donot start
  54 backtracking. These tests by theselves are also very valuable for
  55 developers, so even if you cannot fix a bug yourself, providing a
  56 testto excercise it greatly reduces the amount of timea developer must
  57 spend finding the bug prior to fixing it.
  58
  59
  60 * TEST DESIGN ISSUES
  61
  62 ** Multiple RDBMS Issues
  63
  64 CLSQL supports several RDBMS backends, and it should be possible to run
  65 every test against all of them.  However, there are some features
  66 which we want tests for but which are not implemented on several of
  67 the backends.
  68
  69 ** Test Hygiene
  70
  71 Tests should be able to be run multiple times against the same
  72 database.  It is also important that they clean up after themselves
  73 when they create tables, sequences or other pesistent entities in the
  74 RDBMS backends, because often there are limits to the number of those
  75 thatcan exist at one time, and it also makes debuging thru the SQL
  76 monitors difficult when there aretons of unused tables lying around.
  77
  78 If test need to load large datasets, they should have a mechanism to
  79 ensure the dataset is loaded just once, and not with every test run.
  80
  81 Lastly, because there are various idiosyncracies with RDBMSs, please
  82 ensure that you run the entire test suite once when you write your
  83 tests, to ensure that your test does not leave some state behind which
  84 causes other tests to fail.
  85
  86 ** Test Run Configuration
  87
  88 The file test-init.lisp defines several variables which can be used to
  89 control the connection dictionary of the database against which tests
  90 will be run.
  91
  92
  93 * DATABASE CONNECTIONS/LIFECYCLE
  94
  95 ** CreateDB
  96    *** Without existing DB
  97    *** With existing DB and use old
  98    *** With existing DB and use new
  99    *** Error if existing DB
 100
 101 ** Data Definition
 102   *** Create Tables/Sequences/Indexes -- Should cover creation of
 103       tables with all supported types of fields.
 104   *** Delete Tables/Sequences/Indexes
 105   *** Inspection of Tables and attributes, including types
 106
 107 ** Data Manipulation
 108   *** Update
 109   *** Insert
 110   *** Delete
 111   *** Query
 112
 113 ** Functional Interface
 114   *** Creation/Modification of SQL expressions
 115   *** Querying
 116
 117 ** Embedded SQL syntax
 118   *** Excercise all sql operators
 119
 120 ** Object Interface
 121   *** View class definition
 122   *** Object creation/manipulation/deletion
 123   *** Inter-object Relations
 124
 125 ** Editing Contexts
 126   *** Object Create/Modification/Deletion in a context -- partly covered already
 127   *** Interaction of multiple contexts
 128   *** Schema manipulation within a context
 129   *** Rollback and error handling within a context