doc/book/en/devrepo/testing.rst
author Sylvain Thénault <sylvain.thenault@logilab.fr>
Tue, 17 Jul 2012 12:24:46 +0200
changeset 8483 4ba11607d84a
parent 8168 707466abe9cc
child 9257 ce338133c92c
permissions -rw-r--r--
[entity api] unify set_attributes / set_relations into a cw_set method. Closes #2423719 Allowing similar usage as create_entity/cw_instantiate. Update cw code base to remove deprecated calls.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     1
.. -*- coding: utf-8 -*-
5266
84f285d96363 [doc/book] regroup views chapters under common umbrella (in the development part) & some fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5255
diff changeset
     2
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     3
Tests
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     4
=====
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     5
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     6
Unit tests
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     7
----------
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     8
6301
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6243
diff changeset
     9
The *CubicWeb* framework provides the
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6243
diff changeset
    10
:class:`cubicweb.devtools.testlib.CubicWebTC` test base class .
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    11
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    12
Tests shall be put into the mycube/test directory. Additional test
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    13
data shall go into mycube/test/data.
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    14
6301
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6243
diff changeset
    15
It is much advised to write tests concerning entities methods,
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6243
diff changeset
    16
actions, hooks and operations, security. The
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6243
diff changeset
    17
:class:`~cubicweb.devtools.testlib.CubicWebTC` base class has
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6243
diff changeset
    18
convenience methods to help test all of this.
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    19
6301
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6243
diff changeset
    20
In the realm of views, automatic tests check that views are valid
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6243
diff changeset
    21
XHTML. See :ref:`automatic_views_tests` for details. Since 3.9, bases
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6243
diff changeset
    22
for web functional testing using `windmill
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6243
diff changeset
    23
<http://www.getwindmill.com/>`_ are set. See test cases in
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6243
diff changeset
    24
cubicweb/web/test/windmill and python wrapper in
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6243
diff changeset
    25
cubicweb/web/test_windmill/ if you want to use this in your own cube.
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    26
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    27
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    28
Most unit tests need a live database to work against. This is achieved
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    29
by CubicWeb using automatically sqlite (bundled with Python, see
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    30
http://docs.python.org/library/sqlite3.html) as a backend.
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    31
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    32
The database is stored in the mycube/test/tmpdb,
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    33
mycube/test/tmpdb-template files. If it does not (yet) exists, it will
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    34
be built automatically when the test suit starts.
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    35
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    36
.. warning::
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    37
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    38
  Whenever the schema changes (new entities, attributes, relations)
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    39
  one must delete these two files. Changes concerned only with entity
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    40
  or relation type properties (constraints, cardinalities,
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    41
  permissions) and generally dealt with using the
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    42
  `sync_schema_props_perms()` fonction of the migration environment
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    43
  need not a database regeneration step.
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    44
6344
0cb0d8d83e4c [book] add a link in hooks section to test, talk about create_entity in tests section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6301
diff changeset
    45
.. _hook_test:
0cb0d8d83e4c [book] add a link in hooks section to test, talk about create_entity in tests section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6301
diff changeset
    46
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    47
Unit test by example
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    48
````````````````````
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    49
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    50
We start with an example extracted from the keyword cube (available
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    51
from http://www.cubicweb.org/project/cubicweb-keyword).
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    52
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    53
.. sourcecode:: python
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    54
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    55
    from cubicweb.devtools.testlib import CubicWebTC
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    56
    from cubicweb import ValidationError
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    57
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    58
    class ClassificationHooksTC(CubicWebTC):
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    59
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    60
        def setup_database(self):
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    61
            req = self.request()
7116
dfd4680a23f0 [session] add find_entities and find_one_entity to session/request API (closes #1550045)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 7078
diff changeset
    62
            group_etype = req.find_one_entity('CWEType', name='CWGroup')
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    63
            c1 = req.create_entity('Classification', name=u'classif1',
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    64
                                   classifies=group_etype)
7116
dfd4680a23f0 [session] add find_entities and find_one_entity to session/request API (closes #1550045)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 7078
diff changeset
    65
            user_etype = req.find_one_entity('CWEType', name='CWUser')
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    66
            c2 = req.create_entity('Classification', name=u'classif2',
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    67
                                   classifies=user_etype)
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    68
            self.kw1 = req.create_entity('Keyword', name=u'kwgroup', included_in=c1)
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    69
            self.kw2 = req.create_entity('Keyword', name=u'kwuser', included_in=c2)
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    70
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    71
        def test_cannot_create_cycles(self):
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    72
            # direct obvious cycle
8483
4ba11607d84a [entity api] unify set_attributes / set_relations into a cw_set method. Closes #2423719
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 8168
diff changeset
    73
            self.assertRaises(ValidationError, self.kw1.cw_set,
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    74
                              subkeyword_of=self.kw1)
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    75
            # testing indirect cycles
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    76
            kw3 = self.execute('INSERT Keyword SK: SK name "kwgroup2", SK included_in C, '
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    77
                               'SK subkeyword_of K WHERE C name "classif1", K eid %s'
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    78
                               % self.kw1.eid).get_entity(0,0)
8483
4ba11607d84a [entity api] unify set_attributes / set_relations into a cw_set method. Closes #2423719
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 8168
diff changeset
    79
            self.kw1.cw_set(subkeyword_of=kw3)
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    80
            self.assertRaises(ValidationError, self.commit)
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    81
6301
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6243
diff changeset
    82
The test class defines a :meth:`setup_database` method which populates the
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    83
database with initial data. Each test of the class runs with this
6301
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6243
diff changeset
    84
pre-populated database. A commit is done automatically after the
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6243
diff changeset
    85
:meth:`setup_database` call. You don't have to call it explicitely.
5186
f3c2cb460ad9 [doc] note on pytestconf, fixlets
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5150
diff changeset
    86
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    87
The test case itself checks that an Operation does it job of
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    88
preventing cycles amongst Keyword entities.
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
    89
6344
0cb0d8d83e4c [book] add a link in hooks section to test, talk about create_entity in tests section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6301
diff changeset
    90
`create_entity` is a useful method, which easily allows to create an
0cb0d8d83e4c [book] add a link in hooks section to test, talk about create_entity in tests section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6301
diff changeset
    91
entity. You can link this entity to others entities, by specifying as
0cb0d8d83e4c [book] add a link in hooks section to test, talk about create_entity in tests section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6301
diff changeset
    92
argument, the relation name, and the entity to link, as value. In the
0cb0d8d83e4c [book] add a link in hooks section to test, talk about create_entity in tests section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6301
diff changeset
    93
above example, the `Classification` entity is linked to a `CWEtype`
0cb0d8d83e4c [book] add a link in hooks section to test, talk about create_entity in tests section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6301
diff changeset
    94
via the relation `classifies`. Conversely, if you are creating a
0cb0d8d83e4c [book] add a link in hooks section to test, talk about create_entity in tests section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6301
diff changeset
    95
`CWEtype` entity, you can link it to a `Classification` entity, by
0cb0d8d83e4c [book] add a link in hooks section to test, talk about create_entity in tests section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6301
diff changeset
    96
adding `reverse_classifies` as argument.
0cb0d8d83e4c [book] add a link in hooks section to test, talk about create_entity in tests section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6301
diff changeset
    97
6301
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6243
diff changeset
    98
.. note::
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6243
diff changeset
    99
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6243
diff changeset
   100
   :meth:`commit` method is not called automatically in test_XXX
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6243
diff changeset
   101
   methods. You have to call it explicitely if needed (notably to test
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6243
diff changeset
   102
   operations). It is a good practice to call :meth:`clear_all_caches`
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6243
diff changeset
   103
   on entities after a commit to avoid request cache effects.
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6243
diff changeset
   104
5255
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   105
You can see an example of security tests in the
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   106
:ref:`adv_tuto_security`.
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   107
5266
84f285d96363 [doc/book] regroup views chapters under common umbrella (in the development part) & some fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5255
diff changeset
   108
It is possible to have these tests run continuously using `apycot`_.
84f285d96363 [doc/book] regroup views chapters under common umbrella (in the development part) & some fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5255
diff changeset
   109
84f285d96363 [doc/book] regroup views chapters under common umbrella (in the development part) & some fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5255
diff changeset
   110
.. _apycot: http://www.logilab.org/project/apycot
5186
f3c2cb460ad9 [doc] note on pytestconf, fixlets
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5150
diff changeset
   111
6592
4dad0ec0a44f [book] FAQ: reorganize content, improve NoSelectableObject section, add database
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6471
diff changeset
   112
.. _securitytest:
4dad0ec0a44f [book] FAQ: reorganize content, improve NoSelectableObject section, add database
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6471
diff changeset
   113
2953
e5bdf98be37f [doc] important note about tests and connections/users
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2175
diff changeset
   114
Managing connections or users
e5bdf98be37f [doc] important note about tests and connections/users
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2175
diff changeset
   115
+++++++++++++++++++++++++++++
e5bdf98be37f [doc] important note about tests and connections/users
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2175
diff changeset
   116
e5bdf98be37f [doc] important note about tests and connections/users
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2175
diff changeset
   117
Since unit tests are done with the SQLITE backend and this does not
e5bdf98be37f [doc] important note about tests and connections/users
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2175
diff changeset
   118
support multiple connections at a time, you must be careful when
e5bdf98be37f [doc] important note about tests and connections/users
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2175
diff changeset
   119
simulating security, changing users.
e5bdf98be37f [doc] important note about tests and connections/users
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2175
diff changeset
   120
e5bdf98be37f [doc] important note about tests and connections/users
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2175
diff changeset
   121
By default, tests run with a user with admin privileges. This
e5bdf98be37f [doc] important note about tests and connections/users
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2175
diff changeset
   122
user/connection must never be closed.
e5bdf98be37f [doc] important note about tests and connections/users
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2175
diff changeset
   123
5186
f3c2cb460ad9 [doc] note on pytestconf, fixlets
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5150
diff changeset
   124
Before a self.login, one has to release the connection pool in use
f3c2cb460ad9 [doc] note on pytestconf, fixlets
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5150
diff changeset
   125
with a self.commit, self.rollback or self.close.
f3c2cb460ad9 [doc] note on pytestconf, fixlets
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5150
diff changeset
   126
5255
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   127
The `login` method returns a connection object that can be used as a
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   128
context manager:
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   129
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   130
.. sourcecode:: python
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   131
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   132
   with self.login('user1') as user:
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   133
       req = user.req
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   134
       req.execute(...)
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   135
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   136
On exit of the context manager, either a commit or rollback is issued,
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   137
which releases the connection.
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   138
5186
f3c2cb460ad9 [doc] note on pytestconf, fixlets
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5150
diff changeset
   139
When one is logged in as a normal user and wants to switch back to the
5255
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   140
admin user without committing, one has to use
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   141
self.restore_connection().
2953
e5bdf98be37f [doc] important note about tests and connections/users
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2175
diff changeset
   142
5255
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   143
Usage with restore_connection:
2953
e5bdf98be37f [doc] important note about tests and connections/users
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2175
diff changeset
   144
e5bdf98be37f [doc] important note about tests and connections/users
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2175
diff changeset
   145
.. sourcecode:: python
e5bdf98be37f [doc] important note about tests and connections/users
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2175
diff changeset
   146
e5bdf98be37f [doc] important note about tests and connections/users
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2175
diff changeset
   147
    # execute using default admin connection
e5bdf98be37f [doc] important note about tests and connections/users
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2175
diff changeset
   148
    self.execute(...)
e5bdf98be37f [doc] important note about tests and connections/users
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2175
diff changeset
   149
    # I want to login with another user, ensure to free admin connection pool
5255
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   150
    # (could have used rollback but not close here
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   151
    # we should never close defaut admin connection)
2953
e5bdf98be37f [doc] important note about tests and connections/users
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2175
diff changeset
   152
    self.commit()
e5bdf98be37f [doc] important note about tests and connections/users
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2175
diff changeset
   153
    cnx = self.login('user')
e5bdf98be37f [doc] important note about tests and connections/users
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2175
diff changeset
   154
    # execute using user connection
e5bdf98be37f [doc] important note about tests and connections/users
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2175
diff changeset
   155
    self.execute(...)
e5bdf98be37f [doc] important note about tests and connections/users
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2175
diff changeset
   156
    # I want to login with another user or with admin user
e5bdf98be37f [doc] important note about tests and connections/users
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2175
diff changeset
   157
    self.commit();  cnx.close()
e5bdf98be37f [doc] important note about tests and connections/users
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2175
diff changeset
   158
    # restore admin connection, never use cnx = self.login('admin'), it will return
e5bdf98be37f [doc] important note about tests and connections/users
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2175
diff changeset
   159
    # the default admin connection and one may be tempted to close it
e5bdf98be37f [doc] important note about tests and connections/users
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2175
diff changeset
   160
    self.restore_connection()
e5bdf98be37f [doc] important note about tests and connections/users
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2175
diff changeset
   161
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   162
.. warning::
2953
e5bdf98be37f [doc] important note about tests and connections/users
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2175
diff changeset
   163
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   164
   Do not use the references kept to the entities created with a
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   165
   connection from another !
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   166
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   167
Email notifications tests
6065
eae118a84cc6 [doc/book] note about bootstrap_cubes file
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
   168
`````````````````````````
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   169
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   170
When running tests potentially generated e-mails are not really sent
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   171
but is found in the list `MAILBOX` of module
6301
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6243
diff changeset
   172
:mod:`cubicweb.devtools.testlib`.
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   173
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   174
You can test your notifications by analyzing the contents of this list, which
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   175
contains objects with two attributes:
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   176
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   177
* `recipients`, the list of recipients
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   178
* `msg`, object email.Message
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   179
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   180
Let us look at simple example from the ``blog`` cube.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   181
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   182
.. sourcecode:: python
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   183
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   184
    from cubicweb.devtools.testlib import CubicWebTC, MAILBOX
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   185
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   186
    class BlogTestsCubicWebTC(CubicWebTC):
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   187
        """test blog specific behaviours"""
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   188
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   189
        def test_notifications(self):
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   190
            req = self.request()
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   191
            cubicweb_blog = req.create_entity('Blog', title=u'cubicweb',
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   192
                                description=u'cubicweb is beautiful')
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   193
            blog_entry_1 = req.create_entity('BlogEntry', title=u'hop',
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   194
                                             content=u'cubicweb hop')
8483
4ba11607d84a [entity api] unify set_attributes / set_relations into a cw_set method. Closes #2423719
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 8168
diff changeset
   195
            blog_entry_1.cw_set(entry_of=cubicweb_blog)
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   196
            blog_entry_2 = req.create_entity('BlogEntry', title=u'yes',
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   197
                                             content=u'cubicweb yes')
8483
4ba11607d84a [entity api] unify set_attributes / set_relations into a cw_set method. Closes #2423719
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 8168
diff changeset
   198
            blog_entry_2.cw_set(entry_of=cubicweb_blog)
6825
5ac338bc2133 [doc] update unittest api
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6731
diff changeset
   199
            self.assertEqual(len(MAILBOX), 0)
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   200
            self.commit()
6825
5ac338bc2133 [doc] update unittest api
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6731
diff changeset
   201
            self.assertEqual(len(MAILBOX), 2)
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   202
            mail = MAILBOX[0]
6825
5ac338bc2133 [doc] update unittest api
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6731
diff changeset
   203
            self.assertEqual(mail.subject, '[data] hop')
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   204
            mail = MAILBOX[1]
6825
5ac338bc2133 [doc] update unittest api
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6731
diff changeset
   205
            self.assertEqual(mail.subject, '[data] yes')
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   206
6243
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   207
Visible actions tests
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   208
`````````````````````
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   209
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   210
It is easy to write unit tests to test actions which are visible to
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   211
user or to a category of users. Let's take an example in the
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   212
`conference cube`_.
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   213
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   214
.. _`conference cube`: http://www.cubicweb.org/project/cubicweb-conference
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   215
.. sourcecode:: python
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   216
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   217
    class ConferenceActionsTC(CubicWebTC):
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   218
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   219
        def setup_database(self):
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   220
            self.conf = self.create_entity('Conference',
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   221
                                           title=u'my conf',
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   222
                                           url_id=u'conf',
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   223
                                           start_on=date(2010, 1, 27),
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   224
                                           end_on = date(2010, 1, 29),
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   225
                                           call_open=True,
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   226
                                           reverse_is_chair_at=chair,
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   227
                                           reverse_is_reviewer_at=reviewer)
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   228
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   229
        def test_admin(self):
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   230
            req = self.request()
7116
dfd4680a23f0 [session] add find_entities and find_one_entity to session/request API (closes #1550045)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 7078
diff changeset
   231
            rset = req.find_entities('Conference')
6825
5ac338bc2133 [doc] update unittest api
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6731
diff changeset
   232
            self.assertListEqual(self.pactions(req, rset),
6243
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   233
                                  [('workflow', workflow.WorkflowActions),
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   234
                                   ('edit', confactions.ModifyAction),
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   235
                                   ('managepermission', actions.ManagePermissionsAction),
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   236
                                   ('addrelated', actions.AddRelatedActions),
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   237
                                   ('delete', actions.DeleteAction),
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   238
                                   ('generate_badge_action', badges.GenerateBadgeAction),
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   239
                                   ('addtalkinconf', confactions.AddTalkInConferenceAction)
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   240
                                   ])
6825
5ac338bc2133 [doc] update unittest api
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6731
diff changeset
   241
            self.assertListEqual(self.action_submenu(req, rset, 'addrelated'),
6243
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   242
                                  [(u'add Track in_conf Conference object',
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   243
                                    u'http://testing.fr/cubicweb/add/Track'
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   244
                                    u'?__linkto=in_conf%%3A%(conf)s%%3Asubject&'
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   245
                                    u'__redirectpath=conference%%2Fconf&'
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   246
                                    u'__redirectvid=' % {'conf': self.conf.eid}),
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   247
                                   ])
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   248
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   249
You just have to execute a rql query corresponding to the view you want to test,
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   250
and to compare the result of
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   251
:meth:`~cubicweb.devtools.testlib.CubicWebTC.pactions` with the list of actions
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   252
that must be visible in the interface. This is a list of tuples. The first
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   253
element is the action's `__regid__`, the second the action's class.
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   254
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   255
To test actions in submenu, you just have to test the result of
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   256
:meth:`~cubicweb.devtools.testlib.CubicWebTC.action_submenu` method. The last
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   257
parameter of the method is the action's category. The result is a list of
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   258
tuples. The first element is the action's title, and the second element the
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   259
action's url.
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   260
c0ee416040fa [book - #1251780] add a section to explain how to write tests to test which actions are visible
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6242
diff changeset
   261
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   262
.. _automatic_views_tests:
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   263
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   264
Automatic views testing
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   265
-----------------------
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   266
6242
d9ebb391782c [book - #1251260] add a warning in automatic test when user redefine the base class
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6167
diff changeset
   267
This is done automatically with the :class:`cubicweb.devtools.testlib.AutomaticWebTest`
d9ebb391782c [book - #1251260] add a warning in automatic test when user redefine the base class
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6167
diff changeset
   268
class. At cube creation time, the mycube/test/test_mycube.py file
d9ebb391782c [book - #1251260] add a warning in automatic test when user redefine the base class
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6167
diff changeset
   269
contains such a test. The code here has to be uncommented to be
d9ebb391782c [book - #1251260] add a warning in automatic test when user redefine the base class
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6167
diff changeset
   270
usable, without further modification.
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   271
5255
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   272
The ``auto_populate`` method uses a smart algorithm to create
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   273
pseudo-random data in the database, thus enabling the views to be
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   274
invoked and tested.
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   275
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   276
Depending on the schema, hooks and operations constraints, it is not
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   277
always possible for the automatic auto_populate to proceed.
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   278
5255
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   279
It is possible of course to completely redefine auto_populate. A
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   280
lighter solution is to give hints (fill some class attributes) about
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   281
what entities and relations have to be skipped by the auto_populate
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   282
mechanism. These are:
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   283
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   284
* `no_auto_populate`, may contain a list of entity types to skip
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   285
* `ignored_relations`, may contain a list of relation types to skip
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   286
* `application_rql`, may contain a list of rql expressions that
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   287
  auto_populate cannot guess by itself; these must yield resultsets
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   288
  against which views may be selected.
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   289
6242
d9ebb391782c [book - #1251260] add a warning in automatic test when user redefine the base class
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6167
diff changeset
   290
.. warning::
d9ebb391782c [book - #1251260] add a warning in automatic test when user redefine the base class
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6167
diff changeset
   291
d9ebb391782c [book - #1251260] add a warning in automatic test when user redefine the base class
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6167
diff changeset
   292
  Take care to not let the imported `AutomaticWebTest` in your test module
d9ebb391782c [book - #1251260] add a warning in automatic test when user redefine the base class
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6167
diff changeset
   293
  namespace, else both your subclass *and* this parent class will be run.
d9ebb391782c [book - #1251260] add a warning in automatic test when user redefine the base class
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6167
diff changeset
   294
7078
bad26a22fe29 [test] New Handling of database for test.
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6825
diff changeset
   295
Cache heavy database setup
bad26a22fe29 [test] New Handling of database for test.
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6825
diff changeset
   296
-------------------------------
bad26a22fe29 [test] New Handling of database for test.
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6825
diff changeset
   297
bad26a22fe29 [test] New Handling of database for test.
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6825
diff changeset
   298
Some tests suite require a complex setup of the database that takes seconds (or
bad26a22fe29 [test] New Handling of database for test.
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6825
diff changeset
   299
event minutes) to complete. Doing the whole setup for all individual tests make
bad26a22fe29 [test] New Handling of database for test.
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6825
diff changeset
   300
the whole run very slow. The ``CubicWebTC`` class offer a simple way to prepare
bad26a22fe29 [test] New Handling of database for test.
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6825
diff changeset
   301
specific database once for multiple tests. The `test_db_id` class attribute of
bad26a22fe29 [test] New Handling of database for test.
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6825
diff changeset
   302
your ``CubicWebTC`` must be set a unique identifier and the
bad26a22fe29 [test] New Handling of database for test.
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6825
diff changeset
   303
:meth:`pre_setup_database` class method build the cached content. As the
bad26a22fe29 [test] New Handling of database for test.
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6825
diff changeset
   304
:meth:`pre_setup_database` method is not grantee to be called, you must not set
bad26a22fe29 [test] New Handling of database for test.
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6825
diff changeset
   305
any class attribut to be used during test there.  Databases for each `test_db_id`
bad26a22fe29 [test] New Handling of database for test.
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6825
diff changeset
   306
are automatically created if not already in cache.  Clearing the cache is up to
bad26a22fe29 [test] New Handling of database for test.
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6825
diff changeset
   307
the user. Cache files are found in the :file:`data/database` subdirectory of your
bad26a22fe29 [test] New Handling of database for test.
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6825
diff changeset
   308
test directory.
bad26a22fe29 [test] New Handling of database for test.
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6825
diff changeset
   309
bad26a22fe29 [test] New Handling of database for test.
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6825
diff changeset
   310
.. warning::
bad26a22fe29 [test] New Handling of database for test.
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6825
diff changeset
   311
bad26a22fe29 [test] New Handling of database for test.
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6825
diff changeset
   312
  Take care to always have the same :meth:`pre_setup_database` function for all
bad26a22fe29 [test] New Handling of database for test.
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6825
diff changeset
   313
  call with a given `test_db_id` otherwise you test will have unpredictable
bad26a22fe29 [test] New Handling of database for test.
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6825
diff changeset
   314
  result given the first encountered one.
bad26a22fe29 [test] New Handling of database for test.
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6825
diff changeset
   315
6167
376e6c3d4002 [doc] add documentation on RealDatabaseConfiguration
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 6065
diff changeset
   316
Testing on a real-life database
376e6c3d4002 [doc] add documentation on RealDatabaseConfiguration
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 6065
diff changeset
   317
-------------------------------
376e6c3d4002 [doc] add documentation on RealDatabaseConfiguration
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 6065
diff changeset
   318
376e6c3d4002 [doc] add documentation on RealDatabaseConfiguration
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 6065
diff changeset
   319
The ``CubicWebTC`` class uses the `cubicweb.devtools.ApptestConfiguration`
376e6c3d4002 [doc] add documentation on RealDatabaseConfiguration
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 6065
diff changeset
   320
configuration class to setup its testing environment (database driver,
376e6c3d4002 [doc] add documentation on RealDatabaseConfiguration
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 6065
diff changeset
   321
user password, application home, and so on). The `cubicweb.devtools`
376e6c3d4002 [doc] add documentation on RealDatabaseConfiguration
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 6065
diff changeset
   322
module also provides a `RealDatabaseConfiguration`
376e6c3d4002 [doc] add documentation on RealDatabaseConfiguration
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 6065
diff changeset
   323
class that will read a regular cubicweb sources file to fetch all
376e6c3d4002 [doc] add documentation on RealDatabaseConfiguration
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 6065
diff changeset
   324
this information but will also prevent the database to be initalized
376e6c3d4002 [doc] add documentation on RealDatabaseConfiguration
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 6065
diff changeset
   325
and reset between tests.
376e6c3d4002 [doc] add documentation on RealDatabaseConfiguration
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 6065
diff changeset
   326
376e6c3d4002 [doc] add documentation on RealDatabaseConfiguration
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 6065
diff changeset
   327
For a test class to use a specific configuration, you have to set
376e6c3d4002 [doc] add documentation on RealDatabaseConfiguration
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 6065
diff changeset
   328
the `_config` class attribute on the class as in:
376e6c3d4002 [doc] add documentation on RealDatabaseConfiguration
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 6065
diff changeset
   329
376e6c3d4002 [doc] add documentation on RealDatabaseConfiguration
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 6065
diff changeset
   330
.. sourcecode:: python
376e6c3d4002 [doc] add documentation on RealDatabaseConfiguration
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 6065
diff changeset
   331
376e6c3d4002 [doc] add documentation on RealDatabaseConfiguration
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 6065
diff changeset
   332
    from cubicweb.devtools import RealDatabaseConfiguration
376e6c3d4002 [doc] add documentation on RealDatabaseConfiguration
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 6065
diff changeset
   333
    from cubicweb.devtools.testlib import CubicWebTC
376e6c3d4002 [doc] add documentation on RealDatabaseConfiguration
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 6065
diff changeset
   334
376e6c3d4002 [doc] add documentation on RealDatabaseConfiguration
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 6065
diff changeset
   335
    class BlogRealDatabaseTC(CubicWebTC):
376e6c3d4002 [doc] add documentation on RealDatabaseConfiguration
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 6065
diff changeset
   336
        _config = RealDatabaseConfiguration('blog',
376e6c3d4002 [doc] add documentation on RealDatabaseConfiguration
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 6065
diff changeset
   337
                                            sourcefile='/path/to/realdb_sources')
376e6c3d4002 [doc] add documentation on RealDatabaseConfiguration
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 6065
diff changeset
   338
376e6c3d4002 [doc] add documentation on RealDatabaseConfiguration
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 6065
diff changeset
   339
        def test_blog_rss(self):
7856
51a3fb272bf3 [skeleton] fix new class configuration in realdbtest
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 7116
diff changeset
   340
            req = self.request()
51a3fb272bf3 [skeleton] fix new class configuration in realdbtest
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 7116
diff changeset
   341
            rset = req.execute('Any B ORDERBY D DESC WHERE B is BlogEntry, '
51a3fb272bf3 [skeleton] fix new class configuration in realdbtest
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 7116
diff changeset
   342
                'B created_by U, U login "logilab", B creation_date D')
6167
376e6c3d4002 [doc] add documentation on RealDatabaseConfiguration
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 6065
diff changeset
   343
            self.view('rss', rset)
376e6c3d4002 [doc] add documentation on RealDatabaseConfiguration
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 6065
diff changeset
   344
376e6c3d4002 [doc] add documentation on RealDatabaseConfiguration
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 6065
diff changeset
   345
6065
eae118a84cc6 [doc/book] note about bootstrap_cubes file
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
   346
Testing with other cubes
eae118a84cc6 [doc/book] note about bootstrap_cubes file
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
   347
------------------------
eae118a84cc6 [doc/book] note about bootstrap_cubes file
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
   348
eae118a84cc6 [doc/book] note about bootstrap_cubes file
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
   349
Sometimes a small component cannot be tested all by itself, so one
eae118a84cc6 [doc/book] note about bootstrap_cubes file
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
   350
needs to specify other cubes to be used as part of the the unit test
eae118a84cc6 [doc/book] note about bootstrap_cubes file
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
   351
suite. This is handled by the ``bootstrap_cubes`` file located under
6471
6e0642346f80 [book] small note about test/data/schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 6344
diff changeset
   352
``mycube/test/data``. One example from the `preview` cube::
6065
eae118a84cc6 [doc/book] note about bootstrap_cubes file
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
   353
eae118a84cc6 [doc/book] note about bootstrap_cubes file
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
   354
 card, file, preview
eae118a84cc6 [doc/book] note about bootstrap_cubes file
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
   355
eae118a84cc6 [doc/book] note about bootstrap_cubes file
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
   356
The format is:
eae118a84cc6 [doc/book] note about bootstrap_cubes file
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
   357
eae118a84cc6 [doc/book] note about bootstrap_cubes file
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
   358
* possibly several empy lines or lines starting with ``#`` (comment lines)
eae118a84cc6 [doc/book] note about bootstrap_cubes file
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
   359
* one line containing a coma separated list of cube names.
eae118a84cc6 [doc/book] note about bootstrap_cubes file
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
   360
6471
6e0642346f80 [book] small note about test/data/schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 6344
diff changeset
   361
It is also possible to add a ``schema.py`` file in
6e0642346f80 [book] small note about test/data/schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 6344
diff changeset
   362
``mycube/test/data``, which will be used by the testing framework,
6e0642346f80 [book] small note about test/data/schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 6344
diff changeset
   363
therefore making new entity types and relations available to the
6e0642346f80 [book] small note about test/data/schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 6344
diff changeset
   364
tests. 
5255
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   365
6731
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   366
Literate programming
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   367
--------------------
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   368
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   369
CubicWeb provides some literate programming capabilities. The :ref:`cubicweb-ctl`
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   370
`shell` command accepts differents format files. If your file ends with `.txt`
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   371
or `.rst`, the file will be parsed by :mod:`doctest.testfile` with CubicWeb
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   372
:ref:`migration` API enabled in it.
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   373
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   374
Create a `scenario.txt` file into `test/` directory and fill with some content.
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   375
Please refer the :mod:`doctest.testfile` `documentation`_.
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   376
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   377
.. _documentation: http://docs.python.org/library/doctest.html
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   378
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   379
Then, you can run it directly by::
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   380
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   381
    $ cubicweb-ctl shell <cube_instance> test/scenario.txt
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   382
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   383
When your scenario file is ready, put it in a new test case to be able to run
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   384
it automatically.
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   385
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   386
.. sourcecode:: python
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   387
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   388
      from os.path import dirname, join
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   389
      from logilab.common.testlib import unittest_main
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   390
      from cubicweb.devtools.testlib import CubicWebTC
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   391
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   392
      class AcceptanceTC(CubicWebTC):
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   393
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   394
              def test_scenario(self):
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   395
                      self.assertDocTestFile(join(dirname(__file__), 'scenario.txt'))
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   396
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   397
      if __name__ == '__main__':
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   398
              unittest_main()
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   399
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   400
Skipping a scenario
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   401
```````````````````
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   402
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   403
If you want to set up initial conditions that you can't put in your unit test
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   404
case, you have to use a :exc:`KeyboardInterrupt` exception only because of the
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   405
way :mod:`doctest` module will catch all the exceptions internally.
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   406
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   407
    >>> if condition_not_met:
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   408
    ...     raise KeyboardInterrupt('please, check your fixture.')
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   409
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   410
Passing paramaters
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   411
``````````````````
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   412
Using extra arguments to parametrize your scenario is possible by prepend them
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   413
by double dashes.
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   414
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   415
Please refer to the `cubicweb-ctl shell --help` usage.
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   416
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   417
.. important::
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   418
    Your scenario file must be utf-8 encoded.
3ea1f7a6311c [book] Notes about literate testing
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6592
diff changeset
   419
5255
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   420
Test APIS
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   421
---------
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   422
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   423
Using Pytest
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   424
````````````
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   425
5266
84f285d96363 [doc/book] regroup views chapters under common umbrella (in the development part) & some fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5255
diff changeset
   426
The `pytest` utility (shipping with `logilab-common`_, which is a
84f285d96363 [doc/book] regroup views chapters under common umbrella (in the development part) & some fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5255
diff changeset
   427
mandatory dependency of CubicWeb) extends the Python unittest
84f285d96363 [doc/book] regroup views chapters under common umbrella (in the development part) & some fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5255
diff changeset
   428
functionality and is the preferred way to run the CubicWeb test
84f285d96363 [doc/book] regroup views chapters under common umbrella (in the development part) & some fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5255
diff changeset
   429
suites. Bare unittests also work the usual way.
84f285d96363 [doc/book] regroup views chapters under common umbrella (in the development part) & some fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5255
diff changeset
   430
84f285d96363 [doc/book] regroup views chapters under common umbrella (in the development part) & some fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5255
diff changeset
   431
.. _logilab-common: http://www.logilab.org/project/logilab-common
5255
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   432
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   433
To use it, you may:
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   434
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   435
* just launch `pytest` in your cube to execute all tests (it will
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   436
  discover them automatically)
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   437
* launch `pytest unittest_foo.py` to execute one test file
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   438
* launch `pytest unittest_foo.py bar` to execute all test methods and
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   439
  all test cases whose name contain `bar`
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   440
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   441
Additionally, the `-x` option tells pytest to exit at the first error
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   442
or failure. The `-i` option tells pytest to drop into pdb whenever an
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   443
exception occurs in a test.
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   444
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   445
When the `-x` option has been used and the run stopped on a test, it
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   446
is possible, after having fixed the test, to relaunch pytest with the
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   447
`-R` option to tell it to start testing again from where it previously
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   448
failed.
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   449
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   450
Using the `TestCase` base class
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   451
```````````````````````````````
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   452
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   453
The base class of CubicWebTC is logilab.common.testlib.TestCase, which
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   454
provides a lot of convenient assertion methods.
15ea2f3464a4 [doc/book] complete the unit tests chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5229
diff changeset
   455
5229
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   456
.. autoclass:: logilab.common.testlib.TestCase
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   457
   :members:
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   458
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   459
CubicWebTC API
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   460
``````````````
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   461
.. autoclass:: cubicweb.devtools.testlib.CubicWebTC
67dbd07a05f3 [doc/book] expand tesing material
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5186
diff changeset
   462
   :members:
8168
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   463
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   464
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   465
What you need to know about request and session
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   466
-----------------------------------------------
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   467
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   468
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   469
.. image:: ../images/request_session.png
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   470
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   471
First, remember to think that some code run on a client side, some
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   472
other on the repository side. More precisely:
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   473
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   474
* client side: web interface, raw db-api connection (cubicweb-ctl shell for
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   475
  instance);
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   476
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   477
* repository side: RQL query execution, that may trigger hooks and operation.
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   478
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   479
The client interact with the repository through a db-api connection.
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   480
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   481
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   482
A db-api connection is tied to a session in the repository. The connection and
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   483
request objects are unaccessible from repository code / the session object is
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   484
unaccessible from client code (theorically at least).
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   485
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   486
The :mod:`cubicweb.dbapi` module provides a base request class. The web interface
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   487
provides an extended request class.
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   488
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   489
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   490
The `request` object provides access to all cubicweb resources, eg:
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   491
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   492
* the registry (which itself provides access to the schema and the
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   493
  configuration);
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   494
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   495
* an underlying db-api connection (when using req.execute, you actually call the
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   496
  db-api);
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   497
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   498
* other specific resources depending on the client type (url generation according
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   499
  to base url, form parameters, etc.).
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   500
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   501
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   502
A `session` provides an api similar to a request regarding RQL execution and
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   503
access to global resources (registry and all), but also have the following
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   504
responsibilities:
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   505
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   506
* handle transaction data, that will live during the time of a single
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   507
  transaction. This includes the database connections that will be used to
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   508
  execute RQL queries.
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   509
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   510
* handle persistent data that may be used across different (web) requests
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   511
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   512
* security and hooks control (not possible through a request)
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   513
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   514
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   515
The `_cw` attribute
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   516
```````````````````
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   517
The `_cw` attribute available on every application object provides access to all
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   518
cubicweb resources, eg:
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   519
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   520
For code running on the client side (eg web interface view), `_cw` is a request
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   521
instance.
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   522
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   523
For code running on the repository side (hooks and operation), `_cw` is a session
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   524
instance.
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   525
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   526
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   527
Beware some views may be called with a session (eg notifications) or with a
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   528
DB-API request. In the later case, see :meth:`use_web_compatible_requests` on
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   529
:class:`Connection` instances.
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   530
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   531
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   532
Request, session and transaction
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   533
````````````````````````````````
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   534
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   535
In the web interface, an HTTP request is handle by a single request, which will
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   536
be thrown way once the response send.
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   537
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   538
The web publisher handle the transaction:
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   539
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   540
* commit / rollback is done automatically
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   541
* you should not commit / rollback explicitly
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   542
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   543
When using a raw db-api, you're on your own regarding transaction.
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   544
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   545
On the other hand, db-api connection and session live from a user login to its logout.
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   546
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   547
Because session lives for a long time, and database connections is a limited
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   548
resource, we can't bound a session to its own database connection for all its
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   549
lifetime. The repository handles a pool of connections (4 by default), and it's
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   550
responsible to attribute them as needed.
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   551
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   552
Let's detail the process:
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   553
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   554
1. an incoming RQL query comes from a client to the repository
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   555
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   556
2. the repository attributes a database connection to the session
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   557
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   558
3. the repository's querier execute the query
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   559
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   560
4. this query may trigger hooks. Hooks and operation may execute some rql queries
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   561
   through `_cw.execute`. Those queries go directly to the querier, hence don't
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   562
   touch the database connection, they use the one attributed in 2.
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   563
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   564
5. the repository's get the result of the query in 1. If it was a RQL read query,
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   565
   the database connection is released. If it was a write query, the connection
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   566
   is then tied to the session until the transaction is commited or rollbacked.
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   567
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   568
6. results are sent back to the client
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   569
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   570
This implies several things:
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   571
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   572
* when using a request, or code executed in hooks, this database connection
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   573
  handling is totally transparent
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   574
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   575
* however, take care when writing test: you are usually faking / testing both the
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   576
  server and the client side, so you have to decide when to use self.request() /
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   577
  self.session. Ask yourself "where the code I want to test will be running,
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   578
  client or repository side ?". The response is usually : use a request :)
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   579
  However, if you really need using a session:
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   580
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   581
  - commit / rollback will free the database connection (unless explicitly told
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   582
    not to do so).
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   583
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   584
  - if you issue a query after that without asking for a database connection
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   585
    (`session.get_cnxset()`), you will end up with a 'None type has no attribute
707466abe9cc [book] add doc about request, session and connection management you need to know when writing tests
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7856
diff changeset
   586
    source()' error