Opened 7 years ago

Closed 7 years ago

#5430 closed (fixed)

incomplete docs for running Django's own unit tests

Reported by: akaihola Owned by: akaihola
Component: Documentation Version: master
Severity: Keywords:
Cc: Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

Description

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.

Attachments (1)

docs-runtests.diff (1.9 KB) - added by akaihola 7 years ago.
additional documentation for running Django's own unit tests

Download all attachments as: .zip

Change History (8)

comment:1 Changed 7 years ago by Simon G. <dev@…>

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted

akaihola - want to patch this?

comment:2 Changed 7 years ago by akaihola

  • Owner changed from nobody to akaihola
  • Status changed from new to assigned

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.

comment:3 Changed 7 years ago by 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).

comment:4 Changed 7 years ago by akaihola

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?

comment:5 Changed 7 years ago by akaihola

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).

Changed 7 years ago by akaihola

additional documentation for running Django's own unit tests

comment:6 Changed 7 years ago by adrian

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

comment:7 Changed 7 years ago by adrian

  • Resolution set to fixed
  • Status changed from assigned to closed

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

Note: See TracTickets for help on using tickets.
Back to Top