# HG changeset patch
# User Aurelien Campeas <aurelien.campeas@logilab.fr>
# Date 1250847537 -7200
# Node ID e5bdf98be37fc897df05aece6225e871aac0dc61
# Parent  6e871df3005805b1d5bd5ff0193bc4f4c689c8fa
[doc] important note about tests and connections/users

diff -r 6e871df30058 -r e5bdf98be37f doc/book/en/development/testing/index.rst
--- a/doc/book/en/development/testing/index.rst	Fri Aug 21 10:44:45 2009 +0200
+++ b/doc/book/en/development/testing/index.rst	Fri Aug 21 11:38:57 2009 +0200
@@ -16,14 +16,48 @@
 * `EnvBasedTC`, to simulate a complete environment (web + repository)
 * `RepositoryBasedTC`, to simulate a repository environment only
 
-Thos two classes almost have the same interface and offers numerous methods to
-write tests rapidely and efficiently.
+Those two classes almost have the same interface and offer numerous
+methods to write tests rapidly and efficiently.
 
 XXX FILLME describe API
 
 In most of the cases, you will inherit `EnvBasedTC` to write Unittest or
 functional tests for your entities, views, hooks, etc...
 
+Managing connections or users
++++++++++++++++++++++++++++++
+
+Since unit tests are done with the SQLITE backend and this does not
+support multiple connections at a time, you must be careful when
+simulating security, changing users.
+
+By default, tests run with a user with admin privileges. This
+user/connection must never be closed.
+qwq
+Before a self.login, one has to release the connection pool in use with a self.commit, self.rollback or self.close.
+
+When one is logged in as a normal user and wants to switch back to the admin user, one has to use self.restore_connection().
+
+Usually it looks like this:
+
+.. sourcecode:: python
+
+    # execute using default admin connection
+    self.execute(...)
+    # I want to login with another user, ensure to free admin connection pool
+    # (could have used rollback but not close here, we should never close defaut admin connection)
+    self.commit()
+    cnx = self.login('user')
+    # execute using user connection
+    self.execute(...)
+    # I want to login with another user or with admin user
+    self.commit();  cnx.close()
+    # restore admin connection, never use cnx = self.login('admin'), it will return
+    # the default admin connection and one may be tempted to close it
+    self.restore_connection()
+
+Take care of the references kept to the entities created with a connection or the other.
+
 
 Email notifications tests
 -------------------------