doc/book/en/development/testing/index.rst
branchstable
changeset 5150 7a9e71ee5671
parent 5149 a6bcb3c264fe
child 5151 2f70fa8b6854
child 5153 3684ccae5cdc
equal deleted inserted replaced
5149:a6bcb3c264fe 5150:7a9e71ee5671
     1 .. -*- coding: utf-8 -*-
       
     2 
       
     3 Tests
       
     4 =====
       
     5 
       
     6 .. toctree::
       
     7    :maxdepth: 1
       
     8 
       
     9 
       
    10 Unit tests
       
    11 ----------
       
    12 
       
    13 *CubicWeb* framework provides essentially two Python test classes in the
       
    14 module `cubicweb.devtools.apptest`:
       
    15 
       
    16 * `EnvBasedTC`, to simulate a complete environment (web + repository)
       
    17 * `RepositoryBasedTC`, to simulate a repository environment only
       
    18 
       
    19 Those two classes almost have the same interface and offer numerous
       
    20 methods to write tests rapidly and efficiently.
       
    21 
       
    22 XXX FILLME describe API
       
    23 
       
    24 In most of the cases, you will inherit `EnvBasedTC` to write Unittest or
       
    25 functional tests for your entities, views, hooks, etc...
       
    26 
       
    27 Managing connections or users
       
    28 +++++++++++++++++++++++++++++
       
    29 
       
    30 Since unit tests are done with the SQLITE backend and this does not
       
    31 support multiple connections at a time, you must be careful when
       
    32 simulating security, changing users.
       
    33 
       
    34 By default, tests run with a user with admin privileges. This
       
    35 user/connection must never be closed.
       
    36 qwq
       
    37 Before a self.login, one has to release the connection pool in use with a self.commit, self.rollback or self.close.
       
    38 
       
    39 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().
       
    40 
       
    41 Usually it looks like this:
       
    42 
       
    43 .. sourcecode:: python
       
    44 
       
    45     # execute using default admin connection
       
    46     self.execute(...)
       
    47     # I want to login with another user, ensure to free admin connection pool
       
    48     # (could have used rollback but not close here, we should never close defaut admin connection)
       
    49     self.commit()
       
    50     cnx = self.login('user')
       
    51     # execute using user connection
       
    52     self.execute(...)
       
    53     # I want to login with another user or with admin user
       
    54     self.commit();  cnx.close()
       
    55     # restore admin connection, never use cnx = self.login('admin'), it will return
       
    56     # the default admin connection and one may be tempted to close it
       
    57     self.restore_connection()
       
    58 
       
    59 Do not use the references kept to the entities created with a connection from another.
       
    60 
       
    61 
       
    62 Email notifications tests
       
    63 -------------------------
       
    64 When running tests potentially generated e-mails are not really
       
    65 sent but is found in the list `MAILBOX` of module `cubicweb.devtools.apptest`.
       
    66 This list is reset at each test *setUp* (by the setUp of classes `EnvBasedTC`
       
    67 and `RepositoryBasedTC`).
       
    68 
       
    69 
       
    70 You can test your notifications by analyzing the contents of this list, which
       
    71 contains objects with two attributes:
       
    72 * `recipients`, the list of recipients
       
    73 * `msg`, object email.Message
       
    74 
       
    75 
       
    76 Automatic testing
       
    77 -----------------
       
    78 XXXFILLME