PKG-JS-AUTOPKGTEST

NAME

pkg-js-autopkgtest - autopkgtest runner to automatically test Node.js packages

SYNOPSIS

	•		in debian/control, insert "Testsuite: autopkgtest-pkg-nodejs"
	•		write upstream test in debian/tests/pkg-js/test (will be launched by

sh -e)

•

if some other files than "test*" and "debian/tests/test_modules/*"

and installed files are needed, write a "debian/tests/pkg-js/files" with
all needed directories/files

That’s all, other debian/tests files will be written on-the-fly by
autodep8 during autopkgtest

If you want to launch the same test during build, simply add
dh-sequence-nodejs in build dependencies

HOW IT WORKS

•

if directory debian/tests/test_modules exists, NODE_PATH will be set

to NODE_PATH=debian/tests/test_modules:node_modules

•

if additional modules were linked during build, they will be linked into

node_module (debian/nodejs/extlinks)

•

if additional modules were copies during build, they will be copied into

node_module (debian/nodejs/extcopies)

•

if package contains some other components, they will be linked into

node_module

	•	autopkgtest will launch 2 tests:
	•	a "require" test (see below)
	•	the test defined in debian/tests/pkg-js/test in a temporary dir (it

links installed files)

•

if dh-sequence-nodejs is a build dependency, dh_auto_test will

launch the same test (debian/tests/pkg\-js/test) if exists, else just a
node -e "require('.')". Note that you can override test during build
using debian/nodejs/test

•

if file debian/tests/pkg-js/require-name exists, its content will be used

as module name in "require" test (instead of using package\.json value)

FULL EXAMPLE

•

debian/control

...
Testsuite: autopkgtest-pkg-nodejs
Build-Depends: dh-sequence-nodejs
...

•

debian/tests/pkg-js/test

mocha -R spec

ADDITIONAL TEST PACKAGES OR TEST RESTRICTIONS

autodep8 allows one to add additional packages during autopkgtest (and/or
additional restrictions) by using a debian/tests/autopkgtest-pkg-nodejs.conf
file:

extra_depends=mocha, npm
extra-restrictions=needs-internet

ENABLE proto

Since version 0.15.0, pkg-js-autopkgtest launches Node.js with
--disable-proto=throw. This causes tests to fail if
Object.prototype.__proto__ property is used.

If a package can use this feature without security hole (for test for example),
it is possible to disable this nodejs option by creating an empty
debian/tests/pkg-js/enable_proto file, until Debian’s Node.js enables this
feature by default.

THE REQUIRE TEST

How it works

First, pkg\-js\-autopkgtest searches the module name.

•

if debian/tests/pkg-js/require-name exists, its content will be used as

module name

	•	else if looks at package.json "name" field:
	•	if debian/nodejs/main exists, like dh\-sequence\-nodejs, it uses the

package.json from this directory

•

else it uses ./package.json

Then pkg\-js\-autopkgtest looks at package.json fields, not using the file
mentioned above, but using the file installed by the Debian package to test
(ie /usr/share/nodejs/<module\-name>/package\.json):

	•	if type equals module, then:
	•	it builds a node_modules directory with all available dependencies of

the module

•

it builds a test.mjs file that tries to import the module to test and

launch it

•

if main isn’t defined and index.js doesn’t exist, it skip the test

(this avoids to try to test @types/<foo> modules)

•

else it simply launches a nodejs -e "require('$moduleName')"

Since version 0.10.0, pkg\-js\-autopkgtest does the same test for all other
modules installed in nodejs root directories (components installed by .br dh\-sequence\-nodejs using debian/nodejs/root_modules file). If one fail, the
whole test is marked as failed.

Returned values:

	•		0 if all tests succeed (even if some secondary modules are skipped)
	•		77 if all tests succeed but the main module test was skipped. This value

is used by autopkgtest to report a SKIP instead of a failure.

•

else, the number of failure. Then autopkgtest considers the test as FAIL

Customize require test

If you want to skip some secondary module tests, simply list them in
debian/tests/pkg-js/require-SKIP (one module per line).

If you want to skip the whole "require" test, use this:

echo require > debian/tests/pkg-js/SKIP

THE MAIN TEST

pkg\-js\-autopkgtest uses the same test than dh\-sequence\-nodejs: it
launches sh -ex debian/tests/pkg-js/test but using the files installed by
the Debian package.

How main test works

pkg\-js\-autopkgtest search for module name using the same way than "require"
test. Then it prepares the test environment:

	•		it creates a temporary directory
	•		it links all files installed in the directory corresponding to module name

/usr/share/nodejs/<module-name>

	•	it creates a node_modules directory and links into it:
	•	all modules listed in debian/nodejs/extlinks
	•	all modules present in debian/build_modules and debian/tests/test_modules
	•	all other modules installed by the Debian package in nodejs root directories

debian/nodejs/root_modules

•

it copies in node_modules directory all modules listed in

debian/nodejs/extcopies

	•	if looks at debian/tests/pkg-js/files
	•	if it exists, it copies all files/directories listed in it from source

directory to temporary one

	•	else it copies from source directory to temporary one:
	•	all test* files
	•	all Makefile like files (rollup\.config\.js, gulpfile\.js,\.\.\. )

Then it changes its directory to the temporary one launches the test using
sh -ex debian/tests/pkg-js/test.

SEE ALSO

pkg-js-tools(7), autodep8(1)

COPYRIGHT AND LICENSE

Copyright Yadd <yadd@debian.org>

This library is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.

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.

On Debian systems, the complete text of version 2 of the GNU General
Public License can be found in ‘/usr/share/common-licenses/GPL-2’.
If not, see GNU licenses;