Hacker’s guide to NAV¶

Python boilerplate headers¶

We will generally only accept code into NAV if it is licensed under GPL v2, but we may make individual exceptions for code licensed under compatible licenses. Each Python source code file should contain the following boilerplate at the top:

#
# Copyright (C) 2008,2009 Somebody
#
# This file is part of Network Administration Visualized (NAV).
#
# NAV is free software: you can redistribute it and/or modify it under the
# terms of the GNU General Public License version 2 as published by the Free
# Software Foundation.
#
# This program is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
# more details.  You should have received a copy of the GNU General Public
# License along with NAV. If not, see <http://www.gnu.org/licenses/>.
#

If a file uses non-ASCII characters, it must be encoded as UTF-8, and an encoding statement should be inserted at the top:

# -*- coding: utf-8 -*-

Javascript¶

When writing Javascript code, try to focus on modules, not pages. If the code is HTML-related, it should take selectors or objects as input and concern itself solely about those. This makes for much easier testing and reuse. And of course - write the tests first.

When the module is done you write a controller for the page that plugs the needed plugins to the page elements. This should fail gracefully if the needed elements are not present.

NAV’s Javascript uses RequireJS - use this to create modules and specify dependencies.

Pro tip is to create require_config.dev.js in htdocs/js/` and add the following configuration to RequireJS:

require.urlArgs = "bust=" +  (new Date()).getTime();

This makes sure your not using cached resources in your browser when developing, something browsers love to do! See config-urlArgs in the RequireJS documentation for details. require_config.dev.js is listed in the repository .gitignore file.

Connecting to the database (Python)¶

import nav.db
# Get a connection to the NAV database
connection = nav.db.getConnection('default')

Changing the schema¶

The baseline schema is located in sql/baseline/ - the navsyncdb program is responsible for running this when creating a new database. To make a schema change, you do not change the baseline, but go to the sql/changes/ directory and create a new schema change script there.

Schema change scripts as numbered, using the following pattern:

sc.<major>.<minor>.<point>.sql

The <major> and <minor> numbers usually correspond to the major and minor number of the next NAV release. The <point> number is a sequence id - pick the next free number when creating a schema change script.

Remember these points when creating a schema change script:

• Create separate change scripts for unrelated schema changes.
• Remember to write SQL to migrate existing data, if necessary.
• Do not use transactional statements - navsyncdb will take care of that.

To apply your change scripts, just run navsyncdb. It will look inside the schema_change_log table to see which change scripts have already been applied, and it will detect your new change script and apply this to the database.

Push access¶

Push access to the official repositories is limited to developers employed or commissioned by Uninett.

Running tests¶

We use pytest to run the test suite. A bundled version is included as runtests.py in the python/ subdirectory, and is used to run the unit tests only when a make check command is issued in the python/ subdirectory.

There’s also a script to produce an entire test environment as a Docker image and to run the entire test suite inside a Docker container created from that image. This is actually the same method employed by our Jenkins build servers to run the test suite. Take a look in the tests/docker/ directory.

Javascript testing¶

Testing javascript in NAV is straightforward. We use Karma as a testrunner, Mocha as testing framework and Chai as assertion library.

cd htdocs/static/js

# Install required libs, you need npm installed
npm install

# Run tests. This will start browsers. Karma will make sure that tests will
# run on changes in js-files.
./node_modules/karma/bin/karma start test/karma.conf.js

All tests are located under htdocs/statis/js/test/. Create new tests there. For syntax, assertions and related stuff take a look at the tests already there and the relevant documentation linked above.

Jenkins¶

We use Jenkins (formerly Hudson) for Continuous Integration testing of NAV. All the automated tests are run each time new changesets are pushed to the official NAV repositories. Jenkins also runs pylint to create stats on code quality.

Our Jenkins installation is available on https://ci.nav.uninett.no/ .

Make fixtures for integration testing¶

from django.core import serializers
from nav.models.manage import Netbox

fixtures = serializers.serialize("xml", Netbox.objects.all()[:2])

Fixtures can so be used in your integration tests by extending the test case DjangoTransactionTestCase in nav.tests.cases.

See nav.tests.integration.l2trace_test for an example on applying fixtures for your particular test case.

See https://docs.djangoproject.com/en/1.7/topics/serialization/