Rewrite unit test instruction to be easier to use.

TEST.rst

@@ -1,6 +1,15 @@
-=====
-Tests
-=====
+=============================
+Tests using the pytest runner
+=============================
+
+QUICK TEST
+==========
+
+Are your Python, Postgres and PostGIS dependencies are all installed?
+Run the tests in a created ``gis`` database::
+
+    $ sudo -u postgres psql ./tests/create_database.sql
+    $ py.test
 
 Install system dependencies
 ===========================
@@ -17,9 +26,17 @@ Install the Python dependencies::
 
     $ pip install -r requirements.txt
     $ pip install psycopg2
+    $ pip install pytest
+
+Set up the database using psql
+==============================
+
+Create all ``gis`` database objects at once::
+
+    $ sudo -u postgres psql ./tests/create_database.sql
 
-Set up the database
-===================
+Or set up the database using SHELL commands
+===========================================
 
 Create the ``gis`` role::
 

run_tests.sh

@@ -0,0 +1,22 @@
+#! /bin/bash
+# -----------------------------------------------------------------------------
+# GeoAlchemy2: Run Unit Tests
+# -----------------------------------------------------------------------------
+# This SHELL script creates a database named "gis" and adds PostGIS support.
+# -----------------------------------------------------------------------------
+
+#  Set current PostGIS version when not provided.
+# -----------------------------------------------------------------------------
+if [ "$POSTGIS_VERSION" == "" ]; then
+    export POSTGIS_VERSION=2.1
+fi
+
+# Set up the test environment in PosgreSQL.
+# -----------------------------------------------------------------------------
+echo "Setting up GIS test database ..."
+source ./tests/setup_tests.sh
+
+# Use pytest to run unit tests. 
+# -----------------------------------------------------------------------------
+py.test
+

tests/create_database.sql

@@ -0,0 +1,40 @@
+-- GeoAlchemy2 PostGIS Tests: Set up the database
+-- -----------------------------------------------------------------------------
+-- This PSQL script creates a database named "gis" which needs PostGIS support.
+-- Use this to run the GeoAlchemy2 unit tests for Python.
+-- -----------------------------------------------------------------------------
+-- NOTE: Log-in as a DB Superuser, e.g. "postgres".
+-- -----------------------------------------------------------------------------
+
+-- Create the "gis" role:
+CREATE ROLE gis PASSWORD 'gis' SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN;
+
+-- Create the "gis" database:
+CREATE DATABASE gis ENCODING 'UTF8';
+
+-- Connect to "gis" database for all other objects.
+\connect gis
+
+CREATE SCHEMA gis;
+
+-- Grant permissions:
+GRANT CREATE ON DATABASE gis TO "gis";
+GRANT USAGE, CREATE ON SCHEMA gis TO "gis";
+
+-- Enable PostGIS for the "gis" database.
+-- -----------------------------------------------------------------------------
+-- NOTE: See ./tests/setup_tests.sh where an IF-statment installs PostGIS.
+
+-- -----------------------------------------------------------------------------
+-- For PostGIS 1.5: Use the PSQL scripts.
+--
+-- OFF \i /usr/share/postgresql/9.x/contrib/postgis-1.5/postgis.sql
+-- OFF \i /usr/share/postgresql/9.x/contrib/postgis-1.5/spatial_ref_sys.sql
+-- -----------------------------------------------------------------------------
+
+-- -----------------------------------------------------------------------------
+-- For PostGIS 2: Create the extension here.
+-- -----------------------------------------------------------------------------
+-- CREATE EXTENSION postgis;
+-- CREATE EXTENSION postgis_topology;
+

tests/setup_tests.sh

@@ -0,0 +1,34 @@
+#! /bin/bash
+# -----------------------------------------------------------------------------
+# GeoAlchemy2 Setup Tests: Set up the test environment 
+# -----------------------------------------------------------------------------
+# This SHELL script creates a database named "gis" and adds PostGIS support.
+# The env variable POSTGIS_VERSION selects PostGIS 1.5 or 2.x+ versions.
+# Use this to prepare for the GeoAlchemy2 unit tests for Python.
+# -----------------------------------------------------------------------------
+# NOTE: Log-in as a DB Superuser, e.g. "postgres".
+# -----------------------------------------------------------------------------
+
+echo "Creating GIS test database ..."
+psql -U postgres -f ./tests/create_database.sql
+
+# -----------------------------------------------------------------------------
+# Enable PostGIS for the "gis" database.
+# -----------------------------------------------------------------------------
+echo "Installing PostGIS version $POSTGIS_VERSION ..."
+
+if [ "$POSTGIS_VERSION" == "1.5" ]; then
+    # -------------------------------------------------------------------------
+    # For PostGIS 1.5: Use the PSQL scripts.
+    # -------------------------------------------------------------------------
+    psql -U postgres -f /usr/share/postgresql/9.1/contrib/postgis-1.5/postgis.sql;
+    psql -U postgres -f /usr/share/postgresql/9.1/contrib/postgis-1.5/spatial_ref_sys.sql;
+    echo "OK PostGIS version $POSTGIS_VERSION"
+else
+    # -------------------------------------------------------------------------
+    # For PostGIS 2: Create the extension in PSQL.
+    # -------------------------------------------------------------------------
+    psql -U postgres -c "CREATE EXTENSION postgis;";
+    echo "OK PostGIS version $POSTGIS_VERSION"
+fi
+

tests/test_functional.py

@@ -23,7 +23,7 @@
 from shapely.geometry import LineString
 
 
-engine = create_engine('postgresql://gis:gis@localhost/gis', echo=True)
+engine = create_engine('postgresql://gis:gis@localhost:5432/gis', echo=True)
 metadata = MetaData(engine)
 Base = declarative_base(metadata=metadata)