From: Mike Bayer Date: Mon, 6 May 2019 14:11:04 +0000 (-0400) Subject: Update to latest README.unittests.rst X-Git-Tag: rel_1_0_11~16 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c88864401b802a25704362a79e1f77bbcc172f3c;p=thirdparty%2Fsqlalchemy%2Falembic.git Update to latest README.unittests.rst Also note run_tests.py is deprecated. Change-Id: Ie82dd3133b487f61b32e005d6f2b8941cddfcce3 Fixes: #557 --- diff --git a/README.unittests.rst b/README.unittests.rst index 5b3b53c4..35e5fd4b 100644 --- a/README.unittests.rst +++ b/README.unittests.rst @@ -1,35 +1,222 @@ -Running Unit Tests +================================ +SQLALCHEMY / ALEMBIC UNIT TESTS +================================ + +Note that Alembic uses a test framework that is mostly equivalent to the one +that SQLAlchemy uses. While it is as of May, 2019 still vendored over (e.g. +copied from SQLAlchemy into Alembic's source tree with local modifications), +the potential plan is that Alembic will use SQLAlchemy's suite directly one +support for older SQLAlchemy versions is dropped. + +This document is mostly copied directly from that of SQLAlchemy. Note that +Alembic's test suite currently has "backend" tests (e.g., tests that require a +real database) only for PostgreSQL and MySQL; other backends like Oracle and +SQL Server are not required. + + +Basic Test Running +================== + +A test target exists within the setup.py script. For basic test runs:: + + python setup.py test + + +Running with Tox +================ + +For more elaborate CI-style test running, the tox script provided will +run against various Python / database targets. For a basic run against +Python 2.7 using an in-memory SQLite database:: + + tox -e py27-sqlite + +The tox runner contains a series of target combinations that can run +against various combinations of databases. The test suite can be +run against SQLite with "backend" tests also running against a PostgreSQL +database:: + + tox -e py36-sqlite-postgresql + +Or to run just "backend" tests (NOTE: Alembic has no tests marked this +way so this option is not important) against a MySQL databases:: + + tox -e py36-mysql-backendonly + +Running against backends other than SQLite requires that a database of that +vendor be available at a specific URL. See "Setting Up Databases" below +for details. + +The py.test Engine ================== -Tests can be run be run using via py.test, via the nose front-end -script, or the Python setup.py script:: +Both the tox runner and the setup.py runner are using py.test to invoke +the test suite. Within the realm of py.test, SQLAlchemy itself is adding +a large series of option and customizations to the py.test runner using +plugin points, to allow for SQLAlchemy's multiple database support, +database setup/teardown and connectivity, multi process support, as well as +lots of skip / database selection rules. + +Running tests with py.test directly grants more immediate control over +database options and test selection. + +A generic py.test run looks like:: + + py.test -n4 + +Above, the full test suite will run against SQLite, using four processes. +If the "-n" flag is not used, the pytest-xdist is skipped and the tests will +run linearly, which will take a pretty long time. + +The py.test command line is more handy for running subsets of tests and to +quickly allow for custom database connections. Example:: + + py.test --dburi=postgresql+psycopg2://scott:tiger@localhost/test test/sql/test_query.py + +Above will run the tests in the test/sql/test_query.py file (a pretty good +file for basic "does this database work at all?" to start with) against a +running PostgreSQL database at the given URL. + +The py.test frontend can also run tests against multiple kinds of databases +at once - a large subset of tests are marked as "backend" tests, which will +be run against each available backend, and additionally lots of tests are targeted +at specific backends only, which only run if a matching backend is made available. +For example, to run the test suite against both PostgreSQL and MySQL at the same time:: + + py.test -n4 --db postgresql --db mysql + + +Setting Up Databases +==================== + +The test suite identifies several built-in database tags that run against +a pre-set URL. These can be seen using --dbs:: + + $ py.test --dbs + Available --db options (use --dburi to override) + default sqlite:///:memory: + firebird firebird://sysdba:masterkey@localhost//Users/classic/foo.fdb + mssql mssql+pyodbc://scott:tiger@ms_2008 + mssql_pymssql mssql+pymssql://scott:tiger@ms_2008 + mysql mysql://scott:tiger@127.0.0.1:3306/test?charset=utf8 + oracle oracle://scott:tiger@127.0.0.1:1521 + oracle8 oracle://scott:tiger@127.0.0.1:1521/?use_ansi=0 + pg8000 postgresql+pg8000://scott:tiger@127.0.0.1:5432/test + postgresql postgresql://scott:tiger@127.0.0.1:5432/test + postgresql_psycopg2cffi postgresql+psycopg2cffi://scott:tiger@127.0.0.1:5432/test + pymysql mysql+pymysql://scott:tiger@127.0.0.1:3306/test?charset=utf8 + sqlite sqlite:///:memory: + sqlite_file sqlite:///querytest.db + +What those mean is that if you have a database running that can be accessed +by the above URL, you can run the test suite against it using ``--db ``. + +The URLs are present in the ``setup.cfg`` file. You can make your own URLs by +creating a new file called ``test.cfg`` and adding your own ``[db]`` section:: + + # test.cfg file + [db] + my_postgresql=postgresql://username:pass@hostname/dbname + +Above, we can now run the tests with ``my_postgresql``:: + + py.test --db my_postgresql + +We can also override the existing names in our ``test.cfg`` file, so that we can run +with the tox runner also:: + + # test.cfg file + [db] + postgresql=postgresql://username:pass@hostname/dbname + +Now when we run ``tox -e py27-postgresql``, it will use our custom URL instead +of the fixed one in setup.cfg. + +Database Configuration +====================== + +The test runner will by default create and drop tables within the default +database that's in the database URL, *unless* the multiprocessing option +is in use via the py.test "-n" flag, which invokes pytest-xdist. The +multiprocessing option is **enabled by default** for both the tox runner +and the setup.py frontend. When multiprocessing is used, the SQLAlchemy +testing framework will create a new database for each process, and then +tear it down after the test run is complete. So it will be necessary +for the database user to have access to CREATE DATABASE in order for this +to work. + +Several tests require alternate usernames or schemas to be present, which +are used to test dotted-name access scenarios. On some databases such +as Oracle or Sybase, these are usernames, and others such as PostgreSQL +and MySQL they are schemas. The requirement applies to all backends +except SQLite and Firebird. The names are:: + + test_schema + test_schema_2 (only used on PostgreSQL) + +Please refer to your vendor documentation for the proper syntax to create +these namespaces - the database user must have permission to create and drop +tables within these schemas. Its perfectly fine to run the test suite +without these namespaces present, it only means that a handful of tests which +expect them to be present will fail. + +Additional steps specific to individual databases are as follows:: + + POSTGRESQL: To enable unicode testing with JSONB, create the + database with UTF8 encoding:: + + postgres=# create database test with owner=scott encoding='utf8' template=template0; + + To include tests for HSTORE, create the HSTORE type engine:: + + postgres=# \c test; + You are now connected to database "test" as user "postgresql". + test=# create extension hstore; + CREATE EXTENSION + + Full-text search configuration should be set to English, else + several tests of ``.match()`` will fail. This can be set (if it isn't so + already) with: + + ALTER DATABASE test SET default_text_search_config = 'pg_catalog.english' + + ORACLE: a user named "test_schema" is created in addition to the default + user. + + The primary database user needs to be able to create and drop tables, + synonyms, and constraints within the "test_schema" user. For this + to work fully, including that the user has the "REFERENCES" role + in a remote schema for tables not yet defined (REFERENCES is per-table), + it is required that the test the user be present in the "DBA" role: + + grant dba to scott; + + MSSQL: Tests that involve multiple connections require Snapshot Isolation + ability implemented on the test database in order to prevent deadlocks that + will occur with record locking isolation. This feature is only available + with MSSQL 2005 and greater. You must enable snapshot isolation at the + database level and set the default cursor isolation with two SQL commands: + + ALTER DATABASE MyDatabase SET ALLOW_SNAPSHOT_ISOLATION ON + + ALTER DATABASE MyDatabase SET READ_COMMITTED_SNAPSHOT ON - py.test - python run_tests.py +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 setup.py test + $ ./py.test test/orm/test_unitofwork.py -s \ + --log-debug=sqlalchemy.pool --log-info=sqlalchemy.engine -There's also a tox.ini file with several configurations:: +Above we add the py.test "-s" flag so that standard out is not suppressed. - tox -Setting up Optional Databases ------------------------------- +DEVELOPING AND TESTING NEW DIALECTS (SQLAlchemy Only) +------------------------------------------------------- -The test suite will attempt to run a subset of tests against various -database backends, including Postgresql and MySQL. It uses the database -URLs in the [db] section of setup.cfg to locate a URL for particular backend types. -If the URL cannot be loaded, either because the requisite DBAPI is -not present, or if the target database is found to be not accessible, -the test is skipped. +See the file README.dialects.rst for detail on dialects. -To run tests for these backends, replace URLs with working ones -inside the setup.cfg file. Setting a URL here requires that the -corresponding DBAPI is installed as well as that the target database -is running. A connection to the database should provide access -to a *blank* schema, where tables will be created and dropped. It -is critical that this schema have no tables in it already. -For Postgresql, it is also necessary that the target database contain -a user-accessible schema called "test_schema". diff --git a/run_tests.py b/run_tests.py index 71770fc0..d4f27d51 100755 --- a/run_tests.py +++ b/run_tests.py @@ -1,3 +1,9 @@ +####### NOTE: +####### This file is deprecated as is nose support. +####### Please use py.test or the tox test runner to run tests. +####### See README.unittests.rst + + import os # use bootstrapping so that test plugins are loaded # without touching the main library before coverage starts