Developer’s guide

Connector with batteries included (buildout)

Installing the buildout

When you want to install the Magento connector, you can either install it manually using the Installation Guide or either using our automated Buildout config. The manual installation is recommended if you need to add it on an existing installation or if you want to control your environment in your own manner.

The Buildout config is an all-in-one package which installs Odoo, the connector and provides many facilities for the developers, it is based on the Anybox Buildout Recipe. It includes developer tools such as:

  • Run the tests on the connector / Magento connector
  • Build the connector / Magento connector documentation
  • Launch the Jobs Workers (for multiprocessing)

So we highly recommend to use this configuration for development.

Here are the configuration files https://github.com/guewen/odoo-connector-magento-buildout.

Clone the repo:

$ git clone https://github.com/guewen/odoo-connector-magento-buildout.git -b 8.0 odoo-connector-magento

and follow the installation steps.

Warning

System dependencies to build the eggs: libxml2-dev libxslt1-dev that you need to install with apt-get, yum, … You can also use http://pythonhosted.org/anybox.recipe.openerp/first_steps.html#installing-build-dependencies

Head over the next sections to discover the included tools

Start Odoo

All the commands are launched from the root directory of the buildout.

In standalone mode (jobs will be threaded):

$ bin/start_openerp

With workers (multiprocessing), you need to start dedicated Connector Workers for the jobs:

$ bin/start_openerp --workers=4
$ bin/start_connector_worker --workers=2

Start with Supervisord

To start the supervisord daemon, run:

$ bin/supervisord

The default configuration starts Odoo with 4 workers and 2 Connector workers. This can be changed in the buildout.cfg file in the supervisor section.

The services can be managed on:

$ bin/supervisorctl

Run the tests

The Magento Connector and the Connector framework do not use YAML tests, but only unittest2 tests. The following command lines will run them:

$ bin/runtests --database db-name -u connector
$ bin/runtests --database db-name -u magentoerpconnect

Use the help arguments for more information about the options:

$ bin/runtests --help
$ bin/runtests --help-oe

Build the documentation

The documentation uses Sphinx, use the following lines to build them in HTML:

$ bin/sphinxbuilder_connector
$ bin/sphinxbuilder_connector_magento

They will be built in the docs directory at the root of the buildout.

Magento on Docker

If you want to develop a generic feature on the Magento Connector, we recommend to use the Magento - Odoo Connector docker image. It installs Magento 1.7 with the sample database and the Magento (PHP) part of the Connector.

The project’s page on Github describe the installation process, just follow them.

We also use this image as a reference for the data of the tests.

How to help

Mailing list

The main channel for the discussion is the mailing list, you are invited to subscribe on the list named ‘Connectors’ on: https://odoo-community.org/groups

File an Issue

When you encounter an issue or think there is a bug, you can file a bug on the project: https://github.com/OCA/connector-magento/issues

The connector uses several community modules, located in different projects (sale_automatic_workflow, sale_exceptions, …). If you know which project is concerned, please report the bug directly on it, in case of doubt, report it on the Magento Connector project and the developers will eventually move it to the right project.

Possibly, the bug is related to the connector framework, so you may want to report it on this project instead: https://github.com/OCA/connector/issues.

When you report a bug, please give all the sensible information you can provide, such as:

  • the reference of the branch of the connector that you are using, and if possible the revision numbers of that branch and the dependencies (you can use git rev-parse HEAD for that purpose)

It is very helpful if you can include:

  • the detailed steps to reproduce the issue, including any relevant action
  • in case of a crash, an extract from the server log files (possibly with a few lines before the beginning of the crash report in the log)
  • the additional modules you use with the connector if it can help

Submit Pull Requests for features or fixes

Merge proposals are much appreciated and we’ll take care to review them properly.

The PR process is the following:

  1. Fork the project on https://github.com/OCA/connector-magento
  2. Work on your branch, develop a feature or fix a bug. Please include a test (Writing tests).
  3. Ensure that the tests are green (Run the tests)
  4. Ensure that pep8 is repected
  5. Open a Pull Request on GitHub
  6. Travis will automatically test pep8 and launch the tests. If Travis fails, you will need to correct your branch before it can be merged.

Note

Check the GitHub’s help if necessary.

Improve the documentation

Helping on the documentation is extremely valuable and is an easy starting point to contribute. The documentation is located in the Magento connector’s project, so you will need to clone the repository, working on the documentation and follow the instructions in the section Submit Pull Requests for features or fixes to propose your changes.

You will also need to read this section: Build the documentation.

Translations

Currently the translations should be done directly in the .po files, follow the Submit Pull Requests for features or fixes instructions.

Writing tests

Every new feature in the connector should have tests. We use exclusively the unittest2 tests with the Odoo extensions.

The tests are located in magentoerpconnect/tests.

The tests run without any connection to Magento. They mock the API. In order to test the connector with representative data, we record real responses/requests, then use them in the tests. The reference data we use are those of the Magento demo, which are automatically installed when you install Magento using theses instructions: Magento on Docker.

Thus, in the tests folder, you will find files with only data, and the others with the tests.

In order to record data, you can proceed as follows:

In magentoerpconnect/unit/backend_adapter.py at lines 130,130:

 def _call(self, method, arguments):
     try:
         with magentolib.API(self.magento.location,
                             self.magento.username,
                             self.magento.password) as api:
             result = api.call(method, arguments)
             # Uncomment to record requests/responses in ``recorder``
             # record(method, arguments, result)
             _logger.debug("api.call(%s, %s) returned %s",
                           method, arguments, result)
             return result

Uncomment the line doing a call to record(). Then, as soon as you will start the server, all the requests and responses will be stored in global dict. Once you have recorded some exchanges, you can output them using a tool such as ERPpeek and by calling the method output_recorder:

client.MagentoBackend.get(1).output_recorder([])

A path is returned with the location of the file.

When you want to use a set of test data in a test, just use mock_api():

from .common import mock_api,
from .a_data_module import new_set_of_data

<...>
def test_new(self):
    <...>
    with mock_api(new_set_of_data):
        # do what the test needs, such as, for instance:
        import_batch(self.session, 'magento.website', backend_id)

See how to Run the tests

Useful links: