HACKING

The Developer's Guide to the MusicBrainz Server
===============================================

Testing
-------

We use standard Perl tools for unit testing. Tests are located in the t/
directory. The preferred way to run them is to use the `prove` program from
Test::Harness. For example, to run all tests use:

 $ prove -l t/

If you're using Carton, you should instead run:

 $ carton exec -Ilib -- prove t/

The bulk of tests will run from the single tests.t file, which can take a while
to complete. If you are only interested in running a single test, you can pass
the --tests option. For example if you want to run a controller test such as
t::MusicBrainz::Server::Controller::WS::2::LookupArtist you can use:

 $ carton exec -Ilib -- prove t/tests.t :: --tests WS::2::LookupArtist

The --tests argument takes a regular expression to match against the test
name. For example, run multiple tests you can use regular expression groups:

 $ carton exec -Ilib -- prove t/tests.t :: --tests '(Data::URL|Entity::URL)'

While to run all Data:: tests you can do the following:

 $ carton exec -Ilib -- prove t/tests.t :: --tests 'Data::'

Cover art archive development
-----------------------------

The Cover Art features in musicbrainz are provided by
coverartarchive.org.  To add cover art support to your development set
up, see HACKING-CAA.md


JavaScript and Selenium tests
-----------------------------

The tests in t/ also include interface tests, these will be skipped
unless you have SeleniumRC running.  Similarly we have a set of
javascript unittests (using QUnit), which we run using phantomjs,
these will be skipped if phantomjs isn't found.

Selenium tests
---------------

We're using Selenium to run interface tests, to run these tests you
can use a regular development server and the Selenium IDE.  Log in
with a user account with permission to make edits before you start a
test.

Ofcourse a normal development server will have a different data set
compared to the test environment.  When debugging selenium tests it
may be useful to run the musicbrainz server in the test environment
instead, to do that run the following commands:

  $ script/setup_test_db_for_selenium.pl
  $ MUSICBRAINZ_USE_TEST_DATABASE=1 carton exec script/musicbrainz_server.pl -- -r

We also use pgtap to test the PostgreSQL database itself to ensure triggers are
firing corrcetly. If you want to run these tests you will need to install pgtap
(http://pgtap.org) into the TEST database. You can then run tests with:

 $ pg_prove -U <user> -d <test database> t/pgtap/*

(Replacing <user> and <test database> as appropriate)

To do headless testing with selenium, it may be useful to create a
separate "selenium" user.  This way your personal browser settings /
plugins will not affect the tests, and the tests will run in a clean
environment.  This user needs to have a browser configured to connect
through a proxy (localhost:4444).  In theory the proxy configuration
is taken care of by selenium, but that doesn't seem to work on linux.

To install selenium:

  $ mkdir --parents ~/opt/selenium
  $ cd ~/opt/selenium
  ~/opt/selenium$ wget http://selenium.googlecode.com/files/selenium-server-standalone-2.0b2.jar

To run it, first configure some proxy servers, then run the server:

  ~/opt/selenium$ export http_proxy=localhost:4444
  ~/opt/selenium$ xvfb-run java -jar selenium-server-standalone-2.0b2.jar -forcedBrowserModeRestOfLine '*custom /usr/bin/chromium-browser'

This will use chromium as the browser (and chromium will use the proxy
set in the environment).

If some test is working in Selenium IDE but failing on Selenium RC, I
recommend starting the server as follows, this way you can see what's
happening in the browser:

  ~/opt/selenium$ java -jar selenium-server-standalone-2.0b2.jar -singleWindow -browserSessionReuse -forcedBrowserModeRestOfLine '*custom /usr/bin/chromium-browser'


Javascript
----------

Currently we have a single QUnit test file to run javascript tests.
It can be tested inside the browser by visiting
http://test.musicbrainz.org/static/scripts/tests/all.html (or
http://localhost:3000/static/scripts/tests/all.html on your local
development checkout).

It is more fun to be able to run those tests on the commandline, this
can be done with phantomjs.

To install phantomjs:

  $ sudo apt-get install libqt4-dev libqt4-webkit     # on debian
  $ sudo apt-get install libqtwebkit-dev              # on ubuntu
  $ sudo apt-get install xvfb
  $ cd ~/opt
  ~/opt$ git clone git://github.com/ariya/phantomjs.git
  ~/opt$ cd phantomjs
  ~/opt/phantomjs$ qmake
  ~/opt/phantomjs$ make

Now you should be able to use it to run QUnit tests.  A testrunner is
available in root/static/scripts/tests:

  $ xvfb-run ~/opt/phantomjs/bin/phantomjs root/static/scripts/tests/phantom-qunit.js http://localhost:3000/static/scripts/tests/all.html


Cache
-----

Keys:

 * at:INT -- artist type by ID
 * ac:INT -- artist credit by ID
 * artist:INT -- artist by ID
 * artist:UUID -- artist ID by MBID (you need to do another lookup by ID)
 * blog:entries -- The lastest entries from blog.musicbrainz.org
 * cat:INT -- cover art type by ID
 * c:INT -- country by ID
 * g:INT -- gender by ID
 * label:INT -- label by ID
 * label:UUID -- label by MBID (you need to do another lookup by ID)
 * lng:INT -- language by ID
 * lt:INT -- label type by ID
 * link:INT -- link by ID
 * linktype:INT -- link type by ID
 * linkattrtype:INT -- link attribute type by ID
 * mf:INT -- medium format by ID
 * rgt:INT -- release group type by ID
 * rs:INT -- release status by ID
 * rp:INT -- release packaging by ID
 * scr:INT -- script by ID
 * stats:* -- various different statistics
 * tag:INT -- tag by ID
 * wikidoc:TEXT-INT -- wikidocs by page title and revision
 * wikidoc-index -- wikidocs index page
 * wizard_session:INT:INT:<MIXED> -- release editor (wizard) 
   sessions by catalyst session ID, RE (random) session ID, and other specifics
 * wt:INT -- work type by ID

Debug information
-----------------

If you have CATALYST_DEBUG set to true, in DBDefs, the built in server
(script/musicbrainz_server.pl) will run in a development environment. This will
cause debug information to be generated on every page, and all HTML pages will
have debug panels available to view this information. To get to these panels,
simply click the "?" icon in the top right of each page.