5
SQLAlchemy unit tests by default run using Python's built-in sqlite3
6
module. If running on Python 2.4, pysqlite must be installed.
8
Unit tests are run using nose. Nose is available at::
10
https://pypi.python.org/pypi/nose/
12
SQLAlchemy implements a nose plugin that must be present when tests are run.
13
This plugin is invoked when the test runner script provided with
16
The test suite as of version 0.8.2 also requires the mock library. While
17
mock is part of the Python standard library as of 3.3, previous versions
18
will need to have it installed, and is available at::
20
https://pypi.python.org/pypi/mock
22
**NOTE:** - the nose plugin is no longer installed by setuptools as of
23
version 0.7 ! Use "python setup.py test" or "./sqla_nose.py".
25
RUNNING TESTS VIA SETUP.PY
26
--------------------------
27
A plain vanilla run of all tests using sqlite can be run via setup.py:
29
$ python setup.py test
31
The -v flag also works here::
33
$ python setup.py test -v
41
If you're running the tests on Microsoft Windows, then there is an additional
42
argument that must be passed to ./sqla_nose.py::
44
> ./sqla_nose.py --first-package-wins
46
This is required because nose's importer will normally evict a package from
47
sys.modules if it sees a package with the same name in a different location.
48
Setting this argument disables that behavior.
50
Assuming all tests pass, this is a very unexciting output. To make it more
55
RUNNING INDIVIDUAL TESTS
56
-------------------------
57
Any directory of test modules can be run at once by specifying the directory
60
$ ./sqla_nose.py test/dialect
62
Any test module can be run directly by specifying its module name::
64
$ ./sqla_nose.py test.orm.test_mapper
66
To run a specific test within the module, specify it as module:ClassName.methodname::
68
$ ./sqla_nose.py test.orm.test_mapper:MapperTest.test_utils
73
Help is available via --help::
75
$ ./sqla_nose.py --help
77
The --help screen is a combination of common nose options and options which
78
the SQLAlchemy nose plugin adds. The most commonly SQLAlchemy-specific
79
options used are '--db' and '--dburi'.
85
Tests will target an in-memory SQLite database by default. To test against
86
another database, use the --dburi option with any standard SQLAlchemy URL::
88
--dburi=postgresql://user:password@localhost/test
90
Use an empty database and a database user with general DBA privileges.
91
The test suite will be creating and dropping many tables and other DDL, and
92
preexisting tables will interfere with the tests.
94
Several tests require alternate usernames or schemas to be present, which
95
are used to test dotted-name access scenarios. On some databases such
96
as Oracle or Sybase, these are usernames, and others such as Postgresql
97
and MySQL they are schemas. The requirement applies to all backends
98
except SQLite and Firebird. The names are::
101
test_schema_2 (only used on Postgresql)
103
Please refer to your vendor documentation for the proper syntax to create
104
these namespaces - the database user must have permission to create and drop
105
tables within these schemas. Its perfectly fine to run the test suite
106
without these namespaces present, it only means that a handful of tests which
107
expect them to be present will fail.
109
Additional steps specific to individual databases are as follows::
111
MYSQL: Default storage engine should be "MyISAM". Tests that require
112
"InnoDB" as the engine will specify this explicitly.
114
ORACLE: a user named "test_schema" is created.
116
The primary database user needs to be able to create and drop tables,
117
synonyms, and constraints within the "test_schema" user. For this
118
to work fully, including that the user has the "REFERENCES" role
119
in a remote schema for tables not yet defined (REFERENCES is per-table),
120
it is required that the test the user be present in the "DBA" role:
124
SYBASE: Similar to Oracle, "test_schema" is created as a user, and the
125
primary test user needs to have the "sa_role".
127
It's also recommended to turn on "trunc log on chkpt" and to use a
128
separate transaction log device - Sybase basically seizes up when
129
the transaction log is full otherwise.
131
A full series of setup assuming sa/master:
133
disk init name="translog", physname="/opt/sybase/data/translog.dat", size="10M"
134
create database sqlalchemy on default log on translog="10M"
135
sp_dboption sqlalchemy, "trunc log on chkpt", true
136
sp_addlogin scott, "tiger7"
137
sp_addlogin test_schema, "tiger7"
140
sp_adduser test_schema
142
sp_role "grant", sa_role, scott
144
Sybase will still freeze for up to a minute when the log becomes
145
full. To manually dump the log::
147
dump tran sqlalchemy with truncate_only
149
MSSQL: Tests that involve multiple connections require Snapshot Isolation
150
ability implemented on the test database in order to prevent deadlocks that
151
will occur with record locking isolation. This feature is only available
152
with MSSQL 2005 and greater. You must enable snapshot isolation at the
153
database level and set the default cursor isolation with two SQL commands:
155
ALTER DATABASE MyDatabase SET ALLOW_SNAPSHOT_ISOLATION ON
157
ALTER DATABASE MyDatabase SET READ_COMMITTED_SNAPSHOT ON
159
MSSQL+zxJDBC: Trying to run the unit tests on Windows against SQL Server
160
requires using a test.cfg configuration file as the cmd.exe shell won't
161
properly pass the URL arguments into the nose test runner.
163
If you'll be running the tests frequently, database aliases can save a lot of
164
typing. The --dbs option lists the built-in aliases and their matching URLs::
166
$ ./sqla_nose.py --dbs
167
Available --db options (use --dburi to override)
168
mysql mysql://scott:tiger@127.0.0.1:3306/test
169
oracle oracle://scott:tiger@127.0.0.1:1521
170
postgresql postgresql://scott:tiger@127.0.0.1:5432/test
173
To run tests against an aliased database::
175
$ ./sqla_nose.py --db=postgresql
177
To customize the URLs with your own users or hostnames, create a file
178
called `test.cfg` at the top level of the SQLAlchemy source distribution.
179
This file is in Python config format, and contains a [db] section which
180
lists out additional database configurations::
183
postgresql=postgresql://myuser:mypass@localhost/mydb
185
Your custom entries will override the defaults and you'll see them reflected
186
in the output of --dbs.
190
SQLAlchemy logs its activity and debugging through Python's logging package.
191
Any log target can be directed to the console with command line options, such
194
$ ./sqla_nose.py test.orm.unitofwork --log-info=sqlalchemy.orm.mapper \
195
--log-debug=sqlalchemy.pool --log-info=sqlalchemy.engine
197
This would log mapper configuration, connection pool checkouts, and SQL
201
BUILT-IN COVERAGE REPORTING
202
------------------------------
203
Coverage is tracked using Nose's coverage plugin. See the nose
204
documentation for details. Basic usage is::
206
$ ./sqla_nose.py test.sql.test_query --with-coverage
208
BIG COVERAGE TIP !!! There is an issue where existing .pyc files may
209
store the incorrect filepaths, which will break the coverage system. If
210
coverage numbers are coming out as low/zero, try deleting all .pyc files.
212
DEVELOPING AND TESTING NEW DIALECTS
213
-----------------------------------
215
See the new file README.dialects.rst for detail on dialects.
added
removed
README.unittests.rst
