tests/README

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