Yaltik
/
flectra
2
0
Fork 0
Code Pull Requests Releases Activity
flectra/doc/reference/javascript.rst

1416 lines
50 KiB
ReStructuredText
Raw Permalink Blame History

:banner: banners/flectra_javascript.jpg
.. highlight:: javascript
.. default-domain:: js
==========
Javascript
==========
.. automodule:: *
:members:
=======
Widgets
=======
:class:`~Widget`
Exported in ``web.Widget``, the base class for all visual components.
It corresponds to an MVC view, and provides a number of service to
simplify handling of a section of a page:
* Handles parent/child relationships between widgets
* Provides extensive lifecycle management with safety features (e.g.
automatically destroying children widgets during the destruction of a
parent)
* Automatic rendering with :ref:`qweb <reference/qweb>`
* Backbone-compatible shortcuts
DOM Root
--------
A :class:`~Widget` is responsible for a section of the page
materialized by the DOM root of the widget.
A widget's DOM root is available via two attributes:
.. attribute:: Widget.el
raw DOM element set as root to the widget
.. attribute:: Widget.$el
jQuery wrapper around :attr:`~Widget.el`
There are two main ways to define and generate this DOM root:
.. attribute:: Widget.template
Should be set to the name of a :ref:`QWeb template <reference/qweb>`.
If set, the template will be rendered after the widget has been
initialized but before it has been started. The root element generated by
the template will be set as the DOM root of the widget.
.. attribute:: Widget.tagName
Used if the widget has no template defined. Defaults to ``div``,
will be used as the tag name to create the DOM element to set as
the widget's DOM root. It is possible to further customize this
generated DOM root with the following attributes:
.. attribute:: Widget.id
Used to generate an ``id`` attribute on the generated DOM
root.
.. attribute:: Widget.className
Used to generate a ``class`` attribute on the generated DOM root.
.. attribute:: Widget.attributes
Mapping (object literal) of attribute names to attribute
values. Each of these k:v pairs will be set as a DOM attribute
on the generated DOM root.
None of these is used in case a template is specified on the widget.
The DOM root can also be defined programmatically by overridding
.. function:: Widget.renderElement
Renders the widget's DOM root and sets it. The default
implementation will render a set template or generate an element
as described above, and will call
:func:`~Widget.setElement` on the result.
Any override to :func:`~Widget.renderElement` which
does not call its ``_super`` **must** call
:func:`~Widget.setElement` with whatever it
generated or the widget's behavior is undefined.
.. note::
The default :func:`~Widget.renderElement` can
be called repeatedly, it will *replace* the previous DOM root
(using ``replaceWith``). However, this requires that the
widget correctly sets and unsets its events (and children
widgets). Generally, :func:`~Widget.renderElement` should
not be called repeatedly unless the widget advertizes this feature.
Using a widget
''''''''''''''
A widget's lifecycle has 3 main phases:
* creation and initialization of the widget instance
.. function:: Widget.init(parent)
initialization method of widgets, synchronous, can be overridden to
take more parameters from the widget's creator/parent
:param parent: the new widget's parent, used to handle automatic
destruction and event propagation. Can be ``null`` for
the widget to have no parent.
:type parent: :class:`~Widget`
* DOM injection and startup, this is done by calling one of:
.. function:: Widget.appendTo(element)
Renders the widget and inserts it as the last child of the target, uses
`.appendTo()`_
.. function:: Widget.prependTo(element)
Renders the widget and inserts it as the first child of the target, uses
`.prependTo()`_
.. function:: Widget.insertAfter(element)
Renders the widget and inserts it as the preceding sibling of the target,
uses `.insertAfter()`_
.. function:: Widget.insertBefore(element)
Renders the widget and inserts it as the following sibling of the target,
uses `.insertBefore()`_
All of these methods accept whatever the corresponding jQuery method accepts
(CSS selectors, DOM nodes or jQuery objects). They all return a deferred_
and are charged with three tasks:
* rendering the widget's root element via
:func:`~Widget.renderElement`
* inserting the widget's root element in the DOM using whichever jQuery
method they match
* starting the widget, and returning the result of starting it
.. function:: Widget.start()
asynchronous startup of the widget once it's been injected in the DOM,
generally used to perform asynchronous RPC calls to fetch whatever
remote data is necessary for the widget to do its work.
Must return a deferred_ to indicate when its work is done.
A widget is *not guaranteed* to work correctly until its
:func:`~Widget.start` method has finished executing. The
widget's parent/creator must wait for a widget to be fully started
before interacting with it
:returns: deferred_ object
* widget destruction and cleanup
.. function:: Widget.destroy()
destroys the widget's children, unbinds its events and removes its root
from the DOM. Automatically called when the widget's parent is destroyed,
must be called explicitly if the widget has no parents or if it is
removed but its parent remains.
A widget being destroyed is automatically unlinked from its parent.
Related to widget destruction is an important utility method:
.. function:: Widget.alive(deferred[, reject=false])
A significant issue with RPC and destruction is that an RPC call may take
a long time to execute and return while a widget is being destroyed or
after it has been destroyed, trying to execute its operations on a widget
in a broken/invalid state.
This is a frequent source of errors or strange behaviors.
:func:`~Widget.alive` can be used to wrap an RPC call,
ensuring that whatever operations should be executed when the call ends
are only executed if the widget is still alive::
this.alive(this.model.query().all()).then(function (records) {
// would break if executed after the widget is destroyed, wrapping
// rpc in alive() prevents execution
_.each(records, function (record) {
self.$el.append(self.format(record));
});
});
:param deferred: a deferred_ object to wrap
:param reject: by default, if the RPC call returns after the widget has
been destroyed the returned deferred_ is left in limbo
(neither resolved nor rejected). If ``reject`` is set to
``true``, the deferred_ will be rejected instead.
:returns: deferred_ object
.. function:: Widget.isDestroyed()
:returns: ``true`` if the widget is being or has been destroyed, ``false``
otherwise
Accessing DOM content
'''''''''''''''''''''
Because a widget is only responsible for the content below its DOM root, there
is a shortcut for selecting sub-sections of a widget's DOM:
.. function:: Widget.$(selector)
Applies the CSS selector specified as parameter to the widget's
DOM root::
this.$(selector);
is functionally identical to::
this.$el.find(selector);
:param String selector: CSS selector
:returns: jQuery object
.. note:: this helper method is similar to ``Backbone.View.$``
Resetting the DOM root
''''''''''''''''''''''
.. function:: Widget.setElement(element)
Re-sets the widget's DOM root to the provided element, also
handles re-setting the various aliases of the DOM root as well as
unsetting and re-setting delegated events.
:param Element element: a DOM element or jQuery object to set as
the widget's DOM root
.. note:: should be mostly compatible with `Backbone's
setElement`_
DOM events handling
-------------------
A widget will generally need to respond to user action within its
section of the page. This entails binding events to DOM elements.
To this end, :class:`~Widget` provides a shortcut:
.. attribute:: Widget.events
Events are a mapping of an event selector (an event name and an optional
CSS selector separated by a space) to a callback. The callback can
be the name of a widget's method or a function object. In either case, the
``this`` will be set to the widget::
events: {
'click p.oe_some_class a': 'some_method',
'change input': function (e) {
e.stopPropagation();
}
},
The selector is used for jQuery's `event delegation`_, the
callback will only be triggered for descendants of the DOM root
matching the selector\ [#eventsdelegation]_. If the selector is left out
(only an event name is specified), the event will be set directly on the
widget's DOM root.
.. function:: Widget.delegateEvents
This method is in charge of binding :attr:`~Widget.events` to the
DOM. It is automatically called after setting the widget's DOM root.
It can be overridden to set up more complex events than the
:attr:`~Widget.events` map allows, but the parent should always be
called (or :attr:`~Widget.events` won't be handled correctly).
.. function:: Widget.undelegateEvents
This method is in charge of unbinding :attr:`~Widget.events` from
the DOM root when the widget is destroyed or the DOM root is reset, in
order to avoid leaving "phantom" events.
It should be overridden to un-set any event set in an override of
:func:`~Widget.delegateEvents`.
.. note:: this behavior should be compatible with `Backbone's
delegateEvents`_, apart from not accepting any argument.
Subclassing Widget
------------------
:class:`~Widget` is subclassed in the standard manner (via the
:func:`~Class.extend` method), and provides a number of
abstract properties and concrete methods (which you may or may not want to
override). Creating a subclass looks like this::
var MyWidget = Widget.extend({
// QWeb template to use when rendering the object
template: "MyQWebTemplate",
events: {
// events binding example
'click .my-button': 'handle_click',
},
init: function(parent) {
this._super(parent);
// insert code to execute before rendering, for object
// initialization
},
start: function() {
var sup = this._super();
// post-rendering initialization code, at this point
// allows multiplexing deferred objects
return $.when(
// propagate asynchronous signal from parent class
sup,
// return own's asynchronous signal
this.rpc(/* … */))
}
});
The new class can then be used in the following manner::
// Create the instance
var my_widget = new MyWidget(this);
// Render and insert into DOM
my_widget.appendTo(".some-div");
After these two lines have executed (and any promise returned by
:func:`~Widget.appendTo` has been resolved if needed), the widget is
ready to be used.
.. note:: the insertion methods will start the widget themselves, and will
return the result of :func:`~Widget.start()`.
If for some reason you do not want to call these methods, you will
have to first call :func:`~Widget.render()` on the
widget, then insert it into your DOM and start it.
If the widget is not needed anymore (because it's transient), simply terminate
it::
my_widget.destroy();
will unbind all DOM events, remove the widget's content from the DOM and
destroy all widget data.
Development Guidelines
----------------------
* Identifiers (``id`` attribute) should be avoided. In generic applications
and modules, ``id`` limits the re-usability of components and tends to make
code more brittle. Most of the time, they can be replaced with nothing,
classes or keeping a reference to a DOM node or jQuery element.
If an ``id`` is absolutely necessary (because a third-party library requires
one), the id should be partially generated using ``_.uniqueId()`` e.g.::
this.id = _.uniqueId('my-widget-')
* Avoid predictable/common CSS class names. Class names such as "content" or
"navigation" might match the desired meaning/semantics, but it is likely an
other developer will have the same need, creating a naming conflict and
unintended behavior. Generic class names should be prefixed with e.g. the
name of the component they belong to (creating "informal" namespaces, much
as in C or Objective-C).
* Global selectors should be avoided. Because a component may be used several
times in a single page (an example in Flectra is dashboards), queries should be
restricted to a given component's scope. Unfiltered selections such as
``$(selector)`` or ``document.querySelectorAll(selector)`` will generally
lead to unintended or incorrect behavior. Flectra Web's
:class:`~Widget` has an attribute providing its DOM root
(:attr:`~Widget.$el`), and a shortcut to select nodes directly
(:func:`~Widget.$`).
* More generally, never assume your components own or controls anything beyond
its own personal :attr:`~Widget.$el`
* html templating/rendering should use QWeb unless absolutely trivial.
* All interactive components (components displaying information to the screen
or intercepting DOM events) must inherit from :class:`~Widget`
and correctly implement and use its API and life cycle.
.. _.appendTo():
http://api.jquery.com/appendTo/
.. _.prependTo():
http://api.jquery.com/prependTo/
.. _.insertAfter():
http://api.jquery.com/insertAfter/
.. _.insertBefore():
http://api.jquery.com/insertBefore/
.. _event delegation:
http://api.jquery.com/delegate/
.. _Backbone's setElement:
http://backbonejs.org/#View-setElement
.. _Backbone's delegateEvents:
http://backbonejs.org/#View-delegateEvents
.. _deferred: http://api.jquery.com/category/deferred-object/
====
RPC
====
To display and interact with data, calls to the Flectra server are necessary.
This is performed using :abbr:`RPC <Remote Procedure Call>`.
Flectra Web provides two primary APIs to handle this: a low-level
JSON-RPC based API communicating with the Python section of Flectra
Web (and of your module, if you have a Python part) and a high-level
API above that allowing your code to talk directly to high-level Flectra models.
All networking APIs are :ref:`asynchronous <reference/async>`. As a result,
all of them will return Deferred_ objects (whether they resolve those with
values or not). Understanding how those work before before moving on is
probably necessary.
High-level API: calling into Flectra models
-------------------------------------------
Access to Flectra object methods (made available through XML-RPC from the server)
is done via :class:`Model`. It maps onto the Flectra server objects via two primary
methods, :func:`~Model.call` (exported in ``web.Model``) and :func:`~Model.query`
(exported in ``web.DataModel``, only available in the backend client).
:func:`~Model.call` is a direct mapping to the corresponding method of
the Flectra server object. Its usage is similar to that of the Flectra Model API,
with three differences:
* The interface is :ref:`asynchronous <reference/async>`, so instead of
returning results directly RPC method calls will return
Deferred_ instances, which will themselves resolve to the
result of the matching RPC call.
* Because ECMAScript 3/Javascript 1.5 doesnt feature any equivalent to
``__getattr__`` or ``method_missing``, there needs to be an explicit
method to dispatch RPC methods.
* No notion of pooler, the model proxy is instantiated where needed,
not fetched from an other (somewhat global) object::
var Users = new Model('res.users');
Users.call('change_password', ['oldpassword', 'newpassword'],
{context: some_context}).then(function (result) {
// do something with change_password result
});
:func:`~Model.query` is a shortcut for a builder-style
interface to searches (``search`` + ``read`` in Flectra RPC terms). It
returns a :class:`~flectra.web.Query` object which is immutable but
allows building new :class:`~flectra.web.Query` instances from the
first one, adding new properties or modifiying the parent object's::
Users.query(['name', 'login', 'user_email', 'signature'])
.filter([['active', '=', true], ['company_id', '=', main_company]])
.limit(15)
.all().then(function (users) {
// do work with users records
});
The query is only actually performed when calling one of the query
serialization methods, :func:`~flectra.web.Query.all` and
:func:`~flectra.web.Query.first`. These methods will perform a new
RPC call every time they are called.
For that reason, it's actually possible to keep "intermediate" queries
around and use them differently/add new specifications on them.
.. class:: Model(name)
.. attribute:: Model.name
name of the model this object is bound to
.. function:: Model.call(method[, args][, kwargs])
Calls the ``method`` method of the current model, with the
provided positional and keyword arguments.
:param String method: method to call over rpc on the
:attr:`~Model.name`
:param Array<> args: positional arguments to pass to the
method, optional
:param Object<> kwargs: keyword arguments to pass to the
method, optional
:rtype: Deferred<>
.. function:: Model.query(fields)
:param Array<String> fields: list of fields to fetch during
the search
:returns: a :class:`~flectra.web.Query` object
representing the search to perform
.. class:: flectra.web.Query(fields)
The first set of methods is the "fetching" methods. They perform
RPC queries using the internal data of the object they're called
on.
.. function:: flectra.web.Query.all()
Fetches the result of the current :class:`~flectra.web.Query` object's
search.
:rtype: Deferred<Array<>>
.. function:: flectra.web.Query.first()
Fetches the **first** result of the current
:class:`~flectra.web.Query`, or ``null`` if the current
:class:`~flectra.web.Query` does have any result.
:rtype: Deferred<Object | null>
.. function:: flectra.web.Query.count()
Fetches the number of records the current
:class:`~flectra.web.Query` would retrieve.
:rtype: Deferred<Number>
.. function:: flectra.web.Query.group_by(grouping...)
Fetches the groups for the query, using the first specified
grouping parameter
:param Array<String> grouping: Lists the levels of grouping
asked of the server. Grouping
can actually be an array or
varargs.
:rtype: Deferred<Array<flectra.web.QueryGroup>> | null
The second set of methods is the "mutator" methods, they create a
**new** :class:`~flectra.web.Query` object with the relevant
(internal) attribute either augmented or replaced.
.. function:: flectra.web.Query.context(ctx)
Adds the provided ``ctx`` to the query, on top of any existing
context
.. function:: flectra.web.Query.filter(domain)
Adds the provided domain to the query, this domain is
``AND``-ed to the existing query domain.
.. function:: opeenrp.web.Query.offset(offset)
Sets the provided offset on the query. The new offset
*replaces* the old one.
.. function:: flectra.web.Query.limit(limit)
Sets the provided limit on the query. The new limit *replaces*
the old one.
.. function:: flectra.web.Query.order_by(fields…)
Overrides the model's natural order with the provided field
specifications. Behaves much like Django's :py:meth:`QuerySet.order_by
<django.db.models.query.QuerySet.order_by>`:
* Takes 1..n field names, in order of most to least importance
(the first field is the first sorting key). Fields are
provided as strings.
* A field specifies an ascending order, unless it is prefixed
with the minus sign "``-``" in which case the field is used
in the descending order
Divergences from Django's sorting include a lack of random sort
(``?`` field) and the inability to "drill down" into relations
for sorting.
Aggregation (grouping)
''''''''''''''''''''''
Flectra has powerful grouping capacities, but they are kind-of strange
in that they're recursive, and level n+1 relies on data provided
directly by the grouping at level n. As a result, while
:py:meth:`flectra.models.Model.read_group` works it's not a very intuitive
API.
Flectra Web eschews direct calls to :py:meth:`~flectra.models.Model.read_group`
in favor of calling a method of :class:`~flectra.web.Query`, :py:meth:`much
in the way it is done in SQLAlchemy <sqlalchemy.orm.query.Query.group_by>`
[#terminal]_::
some_query.group_by(['field1', 'field2']).then(function (groups) {
// do things with the fetched groups
});
This method is asynchronous when provided with 1..n fields (to group
on) as argument, but it can also be called without any field (empty
fields collection or nothing at all). In this case, instead of
returning a Deferred object it will return ``null``.
When grouping criterion come from a third-party and may or may not
list fields (e.g. could be an empty list), this provides two ways to
test the presence of actual subgroups (versus the need to perform a
regular query for records):
* A check on ``group_by``'s result and two completely separate code
paths::
var groups;
if (groups = some_query.group_by(gby)) {
groups.then(function (gs) {
// groups
});
}
// no groups
* Or a more coherent code path using :func:`when`'s ability to
coerce values into deferreds::
$.when(some_query.group_by(gby)).then(function (groups) {
if (!groups) {
// No grouping
} else {
// grouping, even if there are no groups (groups
// itself could be an empty array)
}
});
The result of a (successful) :func:`~flectra.web.Query.group_by` is
an array of :class:`~flectra.web.QueryGroup`:
.. class:: flectra.web.QueryGroup
.. function:: flectra.web.QueryGroup.get(key)
returns the group's attribute ``key``. Known attributes are:
``grouped_on``
which grouping field resulted from this group
``value``
``grouped_on``'s value for this group
``length``
the number of records in the group
``aggregates``
a {field: value} mapping of aggregations for the group
.. function:: flectra.web.QueryGroup.query([fields...])
equivalent to :func:`Model.query` but pre-filtered to
only include the records within this group. Returns a
:class:`~flectra.web.Query` which can be further manipulated as
usual.
.. function:: flectra.web.QueryGroup.subgroups()
returns a deferred to an array of :class:`~flectra.web.QueryGroup`
below this one
Low-level API: RPC calls to Python side
---------------------------------------
While the previous section is great for calling core OpenERP code
(models code), it does not work if you want to call the Python side of
Flectra Web.
For this, a lower-level API exists on on
:class:`~Session` objects (the class is exported in ``web.Session``, but
an instance isusually available through ``web.session``): the ``rpc`` method.
This method simply takes an absolute path (the absolute URL of the JSON
:ref:`route <reference/http/routing>` to call) and a mapping of attributes to
values (passed as keyword arguments to the Python method). This function
fetches the return value of the Python methods, converted to JSON.
For instance, to call the ``resequence`` of the
:class:`~web.controllers.main.DataSet` controller::
session.rpc('/web/dataset/resequence', {
model: some_model,
ids: array_of_ids,
offset: 42
}).then(function (result) {
// resequence didn't error out
}, function () {
// an error occured during during call
});
.. _reference/javascript/client:
===========
Web Client
===========
Javascript module system overview
---------------------------------
A new module system (inspired from requirejs) has now been deployed.
It has many advantages over the Flectra version 8 system.
* loading order: dependencies are guaranteed to be loaded first, even if
files are not loaded in the correct order in the bundle files.
* easier to split a file into smaller logical units.
* no global variables: easier to reason.
* it is possible to examine every dependencies and dependants. This
makes refactoring much simpler, and less risky.
It has also some disadvantages:
* files are required to use the module system if they want to interact
with flectra, since the various objects are only available in the module
system, and not in global variables
* circular dependencies are not supported. It makes sense, but it means
that one needs to be careful.
This is obviously a very large change and will require everyone to
adopt new habits. For example, the variable flectra does not exist
anymore. The new way of doing things is to import explicitely the module
you need, and declaring explicitely the objects you export. Here is a
simple example::
flectra.define('addon_name.service', function (require) {
var utils = require('web.utils');
var Model = require('web.Model');
// do things with utils and Model
var something_useful = 15;
return {
something_useful: something_useful,
};
});
This snippet shows a module named ``addon_name.service``. It is defined
with the ``flectra.define`` function. ``flectra.define`` takes a name and a
function for arguments:
* The name is the concatenation of the name of the addon it is defined in
and a name describing its purpose.
* The function is the place where the javascript module is actually
defined. It takes a function ``require`` as first argument, and
returns something (or not, depending if it needs to export something).
The ``require`` function is used to get a handle on the dependencies.
In this case, it gives a handle on two javascript modules from the
``web`` addon, namely ``web.utils`` and ``web.Model``.
The idea is that you define what you need to import (by using the
``require`` function) and declare what you export (by returning
something). The web client will then make sure that your code is loaded
properly.
Modules are contained in a file, but a file can define several modules
(however, it is better to keep them in separate files).
Each module can return a deferred. In that case, the module is marked as loaded
only when the deferred is resolved, and its value is equal to the resolved value.
The module can be rejected (unloaded). This will be logged in the console as info.
* ``Missing dependencies``:
These modules do not appear in the page. It is possible that the JavaScript
file is not in the page or that the module name is wrong
* ``Failed modules``:
A javascript error is detected
* ``Rejected modules``:
The module returns a rejected deferred. It (and its dependent modules) is not
loaded.
* ``Rejected linked modules``:
Modules who depend on a rejected module
* ``Non loaded modules``:
Modules who depend on a missing or a failed module
Web client structure
--------------------
The web client files have been refactored into smaller and simpler files.
Here is a description of the current file structure:
* the ``framework/`` folder contains all basic low level modules. The
modules here are supposed to be generic. Some of them are:
* ``web.ajax`` implements rpc calls
* ``web.core`` is a generic modules. It exports various useful
objects and functions, such as ``qweb``, ``_t`` or the main bus.
* ``web.Widget`` contains the widget class
* ``web.Model`` is an abstraction over ``web.ajax`` to make
calls to the server model methods
* ``web.session`` is the former ``flectra.session``
* ``web.utils`` for useful code snippets
* ``web.time`` for every time-related generic functions
* the ``views/`` folder contains all view definitions
* ``widgets/`` is for standalone widgets
The ``js/`` folder also contains some important files:
* ``action_manager.js`` is the ActionManager class
* ``boot.js`` is the file actually implementing the module system
* ``menu.js`` is the definition of the top menu
* ``web_client.js`` is for the root widget WebClient
* ``view_manager.js`` contains the ViewManager
The two other files are ``tour.js`` for the tours and ``compatibility.js``.
The latter file is a compatibility layer bridging the old system to the
new module system. This is where every module names are exported to the
global variable ``flectra``. In theory, our addons should work without
ever using the variable ``flectra``, and the compatibility module can be
disabled safely.
Javascript conventions
----------------------
Here are some basic conventions for the javascript code:
* declare all your dependencies at the top of the module. Also, they
should be sorted alphabetically by module name. This makes it
easier to understand your module.
* declare all exports at the end.
* add the ``use strict`` statement at the beginning of every module
* always name your module properly: ``addon_name.description``.
* use capital letters for classes (for example, ``ActionManager`` is
defined in the module ``web.ActionManager``), and lowercase for
everything else (for example, ``ajax`` is defined in ``web.ajax``).
* declare one module per file
=============================
Testing in Flectra Web Client
=============================
Javascript Unit Testing
-----------------------
Flectra Web includes means to unit-test both the core code of
Flectra Web and your own javascript modules. On the javascript side,
unit-testing is based on QUnit_ with a number of helpers and
extensions for better integration with Flectra.
To see what the runner looks like, find (or start) an Flectra server
with the web client enabled, and navigate to ``/web/tests``
This will show the runner selector, which lists all modules with javascript
unit tests, and allows starting any of them (or all javascript tests in all
modules at once).
.. image:: ./images/runner.png
:align: center
Clicking any runner button will launch the corresponding tests in the
bundled QUnit_ runner:
.. image:: ./images/tests.png
:align: center
Writing a test case
-------------------
The first step is to list the test file(s). This is done through the
``test`` key of the Flectra manifest, by adding javascript files to it:
.. code-block:: python
{
'name': "Demonstration of web/javascript tests",
'category': 'Hidden',
'depends': ['web'],
'test': ['static/tests/demo.js'],
}
and to create the corresponding test file(s)
.. note::
Test files which do not exist will be ignored, if all test files
of a module are ignored (can not be found), the test runner will
consider that the module has no javascript tests.
After that, refreshing the runner selector will display the new module
and allow running all of its (0 so far) tests:
.. image:: ./images/runner2.png
:align: center
The next step is to create a test case::
flectra.testing.section('basic section', function (test) {
test('my first test', function () {
ok(false, "this test has run");
});
});
All testing helpers and structures live in the ``flectra.testing``
module. Flectra tests live in a :func:`~flectra.testing.section`,
which is itself part of a module. The first argument to a section is
the name of the section, the second one is the section body.
:func:`test <flectra.testing.case>`, provided by the
:func:`~flectra.testing.section` to the callback, is used to
register a given test case which will be run whenever the test runner
actually does its job. Flectra Web test case use standard `QUnit
assertions`_ within them.
Launching the test runner at this point will run the test and display
the corresponding assertion message, with red colors indicating the
test failed:
.. image:: ./images/tests2.png
:align: center
Fixing the test (by replacing ``false`` to ``true`` in the assertion)
will make it pass:
.. image:: ./images/tests3.png
:align: center
Assertions
----------
As noted above, Flectra Web's tests use `qunit assertions`_. They are
available globally (so they can just be called without references to
anything). The following list is available:
.. function:: ok(state[, message])
checks that ``state`` is truthy (in the javascript sense)
.. function:: strictEqual(actual, expected[, message])
checks that the actual (produced by a method being tested) and
expected values are identical (roughly equivalent to ``ok(actual
=== expected, message)``)
.. function:: notStrictEqual(actual, expected[, message])
checks that the actual and expected values are *not* identical
(roughly equivalent to ``ok(actual !== expected, message)``)
.. function:: deepEqual(actual, expected[, message])
deep comparison between actual and expected: recurse into
containers (objects and arrays) to ensure that they have the same
keys/number of elements, and the values match.
.. function:: notDeepEqual(actual, expected[, message])
inverse operation to :func:`deepEqual`
.. function:: throws(block[, expected][, message])
checks that, when called, the ``block`` throws an
error. Optionally validates that error against ``expected``.
:param Function block:
:param expected: if a regexp, checks that the thrown error's
message matches the regular expression. If an
error type, checks that the thrown error is of
that type.
:type expected: Error | RegExp
.. function:: equal(actual, expected[, message])
checks that ``actual`` and ``expected`` are loosely equal, using
the ``==`` operator and its coercion rules.
.. function:: notEqual(actual, expected[, message])
inverse operation to :func:`equal`
Getting an Flectra instance
---------------------------
The Flectra instance is the base through which most Flectra Web
modules behaviors (functions, objects, …) are accessed. As a result,
the test framework automatically builds one, and loads the module
being tested and all of its dependencies inside it. This new instance
is provided as the first positional parameter to your test
cases. Let's observe by adding javascript code (not test code) to the
test module:
.. code-block:: python
{
'name': "Demonstration of web/javascript tests",
'category': 'Hidden',
'depends': ['web'],
'js': ['static/src/js/demo.js'],
'test': ['static/tests/demo.js'],
}
::
// src/js/demo.js
flectra.web_tests_demo = function (instance) {
instance.web_tests_demo = {
value_true: true,
SomeType: instance.web.Class.extend({
init: function (value) {
this.value = value;
}
})
};
};
and then adding a new test case, which simply checks that the
``instance`` contains all the expected stuff we created in the
module::
// test/demo.js
test('module content', function (instance) {
ok(instance.web_tests_demo.value_true, "should have a true value");
var type_instance = new instance.web_tests_demo.SomeType(42);
strictEqual(type_instance.value, 42, "should have provided value");
});
DOM Scratchpad
--------------
As in the wider client, arbitrarily accessing document content is
strongly discouraged during tests. But DOM access is still needed to
e.g. fully initialize :class:`widgets <~flectra.Widget>` before
testing them.
Thus, a test case gets a DOM scratchpad as its second positional
parameter, in a jQuery instance. That scratchpad is fully cleaned up
before each test, and as long as it doesn't do anything outside the
scratchpad your code can do whatever it wants::
// test/demo.js
test('DOM content', function (instance, $scratchpad) {
$scratchpad.html('<div><span class="foo bar">ok</span></div>');
ok($scratchpad.find('span').hasClass('foo'),
"should have provided class");
});
test('clean scratchpad', function (instance, $scratchpad) {
ok(!$scratchpad.children().length, "should have no content");
ok(!$scratchpad.text(), "should have no text");
});
.. note::
The top-level element of the scratchpad is not cleaned up, test
cases can add text or DOM children but shoud not alter
``$scratchpad`` itself.
Loading templates
-----------------
To avoid the corresponding processing costs, by default templates are
not loaded into QWeb. If you need to render e.g. widgets making use of
QWeb templates, you can request their loading through the
:attr:`~TestOptions.templates` option to the :func:`test case
function <flectra.testing.case>`.
This will automatically load all relevant templates in the instance's
qweb before running the test case:
.. code-block:: python
{
'name': "Demonstration of web/javascript tests",
'category': 'Hidden',
'depends': ['web'],
'js': ['static/src/js/demo.js'],
'test': ['static/tests/demo.js'],
'qweb': ['static/src/xml/demo.xml'],
}
.. code-block:: xml
<!-- src/xml/demo.xml -->
<templates id="template" xml:space="preserve">
<t t-name="DemoTemplate">
<t t-foreach="5" t-as="value">
<p><t t-esc="value"/></p>
</t>
</t>
</templates>
::
// test/demo.js
test('templates', {templates: true}, function (instance) {
var s = instance.web.qweb.render('DemoTemplate');
var texts = $(s).find('p').map(function () {
return $(this).text();
}).get();
deepEqual(texts, ['0', '1', '2', '3', '4']);
});
Asynchronous cases
------------------
The test case examples so far are all synchronous, they execute from
the first to the last line and once the last line has executed the
test is done. But the web client is full of :ref:`asynchronous code
<reference/async>`, and thus test cases need to be async-aware.
This is done by returning a :class:`deferred <Deferred>` from the
case callback::
// test/demo.js
test('asynchronous', {
asserts: 1
}, function () {
var d = $.Deferred();
setTimeout(function () {
ok(true);
d.resolve();
}, 100);
return d;
});
This example also uses the :class:`options parameter <TestOptions>`
to specify the number of assertions the case should expect, if less or
more assertions are specified the case will count as failed.
Asynchronous test cases *must* specify the number of assertions they
will run. This allows more easily catching situations where e.g. the
test architecture was not warned about asynchronous operations.
.. note::
Asynchronous test cases also have a 2 seconds timeout: if the test
does not finish within 2 seconds, it will be considered
failed. This pretty much always means the test will not
resolve. This timeout *only* applies to the test itself, not to
the setup and teardown processes.
.. note::
If the returned deferred is rejected, the test will be failed
unless :attr:`~TestOptions.fail_on_rejection` is set to
``false``.
RPC
---
An important subset of asynchronous test cases is test cases which
need to perform (and chain, to an extent) RPC calls.
.. note::
Because they are a subset of asynchronous cases, RPC cases must
also provide a valid :attr:`assertions count
<TestOptions.asserts>`.
To enable mock RPC, set the :attr:`rpc option <TestOptions.rpc>` to
``mock``. This will add a third parameter to the test case callback:
.. function:: mock(rpc_spec, handler)
Can be used in two different ways depending on the shape of the
first parameter:
* If it matches the pattern ``model:method`` (if it contains a
colon, essentially) the call will set up the mocking of an RPC
call straight to the Flectra server (through XMLRPC) as
performed via e.g. :func:`flectra.web.Model.call`.
In that case, ``handler`` should be a function taking two
arguments ``args`` and ``kwargs``, matching the corresponding
arguments on the server side and should simply return the value
as if it were returned by the Python XMLRPC handler::
test('XML-RPC', {rpc: 'mock', asserts: 3}, function (instance, $s, mock) {
// set up mocking
mock('people.famous:name_search', function (args, kwargs) {
strictEqual(kwargs.name, 'bob');
return [
[1, "Microsoft Bob"],
[2, "Bob the Builder"],
[3, "Silent Bob"]
];
});
// actual test code
return new instance.web.Model('people.famous')
.call('name_search', {name: 'bob'}).then(function (result) {
strictEqual(result.length, 3, "shoud return 3 people");
strictEqual(result[0][1], "Microsoft Bob",
"the most famous bob should be Microsoft Bob");
});
});
* Otherwise, if it matches an absolute path (e.g. ``/a/b/c``) it
will mock a JSON-RPC call to a web client controller, such as
``/web/webclient/translations``. In that case, the handler takes
a single ``params`` argument holding all of the parameters
provided over JSON-RPC.
As previously, the handler should simply return the result value
as if returned by the original JSON-RPC handler::
test('JSON-RPC', {rpc: 'mock', asserts: 3, templates: true}, function (instance, $s, mock) {
var fetched_dbs = false, fetched_langs = false;
mock('/web/database/get_list', function () {
fetched_dbs = true;
return ['foo', 'bar', 'baz'];
});
mock('/web/session/get_lang_list', function () {
fetched_langs = true;
return [['vo_IS', 'Hopelandic / Vonlenska']];
});
// widget needs that or it blows up
instance.webclient = {toggle_bars: flectra.testing.noop};
var dbm = new instance.web.DatabaseManager({});
return dbm.appendTo($s).then(function () {
ok(fetched_dbs, "should have fetched databases");
ok(fetched_langs, "should have fetched languages");
deepEqual(dbm.db_list, ['foo', 'bar', 'baz']);
});
});
.. note::
Mock handlers can contain assertions, these assertions should be
part of the assertions count (and if multiple calls are made to a
handler containing assertions, it multiplies the effective number
of assertions).
Testing API
-----------
.. function:: flectra.testing.section(name[, options], body)
A test section, serves as shared namespace for related tests (for
constants or values to only set up once). The ``body`` function
should contain the tests themselves.
Note that the order in which tests are run is essentially
undefined, do *not* rely on it.
:param String name:
:param TestOptions options:
:param body:
:type body: Function<:func:`~flectra.testing.case`, void>
.. function:: flectra.testing.case(name[, options], callback)
Registers a test case callback in the test runner, the callback
will only be run once the runner is started (or maybe not at all,
if the test is filtered out).
:param String name:
:param TestOptions options:
:param callback:
:type callback: Function<instance, $, Function<String, Function, void>>
.. class:: TestOptions
the various options which can be passed to
:func:`~flectra.testing.section` or
:func:`~flectra.testing.case`. Except for
:attr:`~TestOptions.setup` and
:attr:`~TestOptions.teardown`, an option on
:func:`~flectra.testing.case` will overwrite the corresponding
option on :func:`~flectra.testing.section` so
e.g. :attr:`~TestOptions.rpc` can be set for a
:func:`~flectra.testing.section` and then differently set for
some :func:`~flectra.testing.case` of that
:func:`~flectra.testing.section`
.. attribute:: TestOptions.asserts
An integer, the number of assertions which should run during a
normal execution of the test. Mandatory for asynchronous tests.
.. attribute:: TestOptions.setup
Test case setup, run right before each test case. A section's
:func:`~TestOptions.setup` is run before the case's own, if
both are specified.
.. attribute:: TestOptions.teardown
Test case teardown, a case's :func:`~TestOptions.teardown`
is run before the corresponding section if both are present.
.. attribute:: TestOptions.fail_on_rejection
If the test is asynchronous and its resulting promise is
rejected, fail the test. Defaults to ``true``, set to
``false`` to not fail the test in case of rejection::
// test/demo.js
test('unfail rejection', {
asserts: 1,
fail_on_rejection: false
}, function () {
var d = $.Deferred();
setTimeout(function () {
ok(true);
d.reject();
}, 100);
return d;
});
.. attribute:: TestOptions.rpc
RPC method to use during tests, one of ``"mock"`` or
``"rpc"``. Any other value will disable RPC for the test (if
they were enabled by the suite for instance).
.. attribute:: TestOptions.templates
Whether the current module (and its dependencies)'s templates
should be loaded into QWeb before starting the test. A
boolean, ``false`` by default.
The test runner can also use two global configuration values set
directly on the ``window`` object:
* ``oe_all_dependencies`` is an ``Array`` of all modules with a web
component, ordered by dependency (for a module ``A`` with
dependencies ``A'``, any module of ``A'`` must come before ``A`` in
the array)
Running through Python
----------------------
The web client includes the means to run these tests on the
command-line (or in a CI system), but while actually running it is
pretty simple the setup of the pre-requisite parts has some
complexities.
#. Install PhantomJS_. It is a headless
browser which allows automating running and testing web
pages. QUnitSuite_ uses it to actually run the qunit_ test suite.
The PhantomJS_ website provides pre-built binaries for some
platforms, and your OS's package management probably provides it as
well.
If you're building PhantomJS_ from source, I recommend preparing
for some knitting time as it's not exactly fast (it needs to
compile both `Qt <http://qt-project.org/>`_ and `Webkit
<http://www.webkit.org/>`_, both being pretty big projects).
.. note::
Because PhantomJS_ is webkit-based, it will not be able to test
if Firefox, Opera or Internet Explorer can correctly run the
test suite (and it is only an approximation for Safari and
Chrome). It is therefore recommended to *also* run the test
suites in actual browsers once in a while.
.. note::
The version of PhantomJS_ this was build through is 1.7,
previous versions *should* work but are not actually supported
(and tend to just segfault when something goes wrong in
PhantomJS_ itself so they're a pain to debug).
#. Install a new database with all relevant modules (all modules with
a web component at least), then restart the server
.. note::
For some tests, a source database needs to be duplicated. This
operation requires that there be no connection to the database
being duplicated, but Flectra doesn't currently break
existing/outstanding connections, so restarting the server is
the simplest way to ensure everything is in the right state.
#. Launch ``oe run-tests -d $DATABASE -mweb`` with the correct
addons-path specified (and replacing ``$DATABASE`` by the source
database you created above)
.. note::
If you leave out ``-mweb``, the runner will attempt to run all
the tests in all the modules, which may or may not work.
If everything went correctly, you should now see a list of tests with
(hopefully) ``ok`` next to their names, closing with a report of the
number of tests run and the time it took:
.. literalinclude:: test-report.txt
:language: text
Congratulation, you have just performed a successful "offline" run of
the OpenERP Web test suite.
.. note::
Note that this runs all the Python tests for the ``web`` module,
but all the web tests for all of Flectra. This can be surprising.
.. _qunit: http://qunitjs.com/
.. _qunit assertions: http://api.qunitjs.com/category/assert/
.. _QUnitSuite: http://pypi.python.org/pypi/QUnitSuite/
.. _PhantomJS: http://phantomjs.org/
.. [#eventsdelegation] not all DOM events are compatible with events delegation
.. [#terminal]
with a small twist: :py:meth:`sqlalchemy.orm.query.Query.group_by` is not
terminal, it returns a query which can still be altered.
View Git Blame Copy Permalink