sqlalchemy/README.unittests

=====================
SQLALCHEMY UNIT TESTS
=====================

SETUP
-----
SQLite support is required.  These instructions assume standard Python 2.4 or
higher. See the section on alternate Python implementations for information on
testing with 2.3 and other Pythons.

The 'test' directory must be on the PYTHONPATH.

cd into the SQLAlchemy distribution directory

In bash:

    $ export PYTHONPATH=./test/

On windows:

    C:\sa\> set PYTHONPATH=test\

    Adjust any other use Unix-style paths in this README as needed.

The unittest framework will automatically prepend the lib/ directory to
sys.path.  This forces the local version of SQLAlchemy to be used, bypassing
any setuptools-installed installations (setuptools places .egg files ahead of
plain directories, even if on PYTHONPATH, unfortunately).


RUNNING ALL TESTS
-----------------
To run all tests:

    $ python test/alltests.py


RUNNING INDIVIDUAL TESTS
-------------------------
Any unittest module can be run directly from the module file:

    python test/orm/mapper.py

To run a specific test within the module, specify it as ClassName.methodname:

    python test/orm/mapper.py MapperTest.testget


COMMAND LINE OPTIONS
--------------------
Help is available via --help

    $ python test/alltests.py --help

    usage: alltests.py [options] [tests...]

    Options:
      -h, --help            show this help message and exit
      --verbose             enable stdout echoing/printing
      --quiet               suppress output
    [...]

Command line options can applied to alltests.py or any individual test module.
Many are available.  The most commonly used are '--db' and '--dburi'.


DATABASE TARGETS
----------------

Tests will target an in-memory SQLite database by default.  To test against
another database, use the --dburi option with any standard SQLAlchemy URL:

    --dburi=postgres://user:password@localhost/test

Use an empty database and a database user with general DBA privileges.  The
test suite will be creating and dropping many tables and other DDL, and
preexisting tables will interfere with the tests

If you'll be running the tests frequently, database aliases can save a lot of
typing.  The --dbs option lists the built-in aliases and their matching URLs:

    $ python test/alltests.py --dbs
    Available --db options (use --dburi to override)
               mysql    mysql://scott:tiger@127.0.0.1:3306/test
              oracle    oracle://scott:tiger@127.0.0.1:1521
            postgres    postgres://scott:tiger@127.0.0.1:5432/test
    [...]

To run tests against an aliased database:

    $ python test/alltests.py --db=postgres

To customize the URLs with your own users or hostnames, make a simple .ini
file called `test.cfg` at the top level of the SQLAlchemy source distribution
or a `.satest.cfg` in your home directory:

    [db]
    postgres=postgres://myuser:mypass@localhost/mydb

Your custom entries will override the defaults and you'll see them reflected
in the output of --dbs.


CONFIGURING LOGGING
-------------------
SQLAlchemy logs its activity and debugging through Python's logging package.
Any log target can be directed to the console with command line options, such
as:

    $ python test/orm/unitofwork.py --log-info=sqlalchemy.orm.mapper \
      --log-debug=sqlalchemy.pool --log-info=sqlalchemy.engine

This would log mapper configuration, connection pool checkouts, and SQL
statement execution.


BUILT-IN COVERAGE REPORTING
------------------------------
Coverage is tracked with coverage.py module, included in the './test/'
directory.  Running the test suite with the --coverage switch will generate a
local file ".coverage" containing coverage details, and a report will be
printed to standard output with an overview of the coverage gathered from the
last unittest run (the file is deleted between runs).

After the suite has been run with --coverage, an annotated version of any
source file can be generated, marking statements that are executed with > and
statements that are missed with !, by running the coverage.py utility with the
"-a" (annotate) option, such as:

    $ python ./test/testlib/coverage.py -a ./lib/sqlalchemy/sql.py

This will create a new annotated file ./lib/sqlalchemy/sql.py,cover. Pretty
cool!


TESTING NEW DIALECTS
--------------------
You can use the SQLAlchemy test suite to test any new database dialect in
development.  All possible database features will be exercised by default.
Test decorators are provided that can exclude unsupported tests for a
particular dialect.  You'll see them all over the source, feel free to add
your dialect to them or apply new decorations to existing tests as required.

It's fine to start out with very broad exclusions, e.g. "2-phase commit is not
supported on this database" and later refine that as needed "2-phase commit is
not available until server version 8".

To be considered for inclusion in the SQLAlchemy distribution, a dialect must
be integrated with the standard test suite.  Dialect-specific tests can be
placed in the 'dialects/' directory.  Comprehensive testing of
database-specific column types and their proper reflection are a very good
place to start.

When working through the tests, start with 'engine' and 'sql' tests.  'engine'
performs a wide range of transaction tests that might deadlock on a brand-new
dialect- try disabling those if you're having problems and revisit them later.

Once the 'sql' tests are passing, the 'orm' tests should pass as well, modulo
any adjustments needed for SQL features the ORM uses that might not be
available in your database.  But if an 'orm' test requires changes to your
dialect or the SQLAlchemy core to pass, there's a test missing in 'sql'!  Any
time you can spend boiling down the problem to it's essential sql roots and
adding a 'sql' test will be much appreciated.

The test suite is very effective at illuminating bugs and inconsistencies in
an underlying DB-API (or database!) implementation.  Workarounds are almost
always possible.  If you hit a wall, join us on the mailing list or, better,
IRC!


ALTERNATE PYTHON IMPLEMENTATIONS
--------------------------------
The test suite restricts itself to largely Python 2.3-level constructs and
standard library features, with the notable exception of decorators, which are
used extensively throughout the suite.

A source transformation tool is included that allows testing on Python 2.3 or
any other Python implementation that lacks @decorator support.

To use it:

  $ python test/clone.py -c --filter=py23 test23

This will copy the test/ directory structure into test23/, with @decorators in
the source code transformed into 2.3-friendly syntax.


TIPS
----
Postgres: The tests require an 'alt_schema' and 'alt_schema_2' to be present in
the testing database.

Postgres: When running the tests on postgres, postgres can get slower and
slower each time you run the tests.  This seems to be related to the constant
creation/dropping of tables.  Running a "VACUUM FULL" on the database will
speed it up again.