incomplete docs for running Django's own unit tests

[Antti Kaihola]

At ​http://www.djangoproject.com/documentation/contributing/#unit-tests under the title "Running the unit tests", the documentation states:

Yes, the unit tests need a settings module,
but only for database connection info,
with the DATABASE_ENGINE setting.
You will also need a ROOT_URLCONF setting
(its value is ignored; it just needs to be present)
and a SITE_ID setting (any non-zero integer value
will do) in order for all the tests to pass.

The unit tests will not touch your existing databases;
they create a new database, called django_test_db,
which is deleted when the tests are finished.
This means your user account needs permission
to execute CREATE DATABASE.

For SQLite the above is true, but for at least PostgreSQL also DATABASE_NAME and DATABASE_USER need to be specified, and DATABASE_NAME must be the name of an existing database to which the user has access, but it *must not* be django_test_db.

[Simon G. <dev@…>]

akaihola - want to patch this?

[Antti Kaihola]

Sure, I can make a patch for this, but could someone confirm that the requirements for settings.py when running unit tests are the same for all backends (except SQLite)? It would be strange to talk only about PostgreSQL there.

[Simon G. <dev@…>]

The DATABASE_NAME/_USER will also be required by MySQL*, and the db will need to exist too.

(* unless it's set up to not require a username and password in which case it'll probably attempt to connect with some default user with only SELECT privileges - I wouldn't worry about this).

[Antti Kaihola]

The test database name isn't actually called "django_test_db" any more, it's "test_<username>" where <username> is the name of the user account used to run the tests. This must have been changed yesterday since the string "django_test_db" isn't anywhere in the source code for current trunk.

settings.py requirements in a nutshell:

• sqlite3 (verified by akaihola)
  • DATABASE_ENGINE = 'sqlite3'
  • ROOT_URLCONF = '' # can be anything, ignored
  • SITE_ID = 1 # any non-zero integer will do
• postgresql-psycopg2 (verified by akaihola)
  • same as for sqlite3, plus:
  • DATABASE_NAME = '<dbname>' # NOT 'test_<username>', but another db for which the given user has access
  • DATABASE_USER = '<username>' # user account to run tests with
• mysql_old, mysql (verified by Simon G.)
  • same as for postgresql-psycopg2 (see comment above)

Are the requirements similar for the rest of the backends?

[Antti Kaihola]

Oops, actually it's even more complicated than that: at least for postgresql-psycqpg2, DATABASE_NAME must be a name of a database for which the user has access, and the test database is called test_<DATABASE_NAME> (the user account name has nothing to do with it).

[Antti Kaihola]

additional documentation for running Django's own unit tests

[Adrian Holovaty]

I'm editing this and committing it now...

[Adrian Holovaty]

(In [6295]) Fixed #5430 -- Improved docs for running Django's own unit tests in docs/contributing.txt. Thanks, akaihola