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 (\fBdebian/nodejs/extlinks\fP)
if additional modules were copies during build, they will be copied into
node_module (\fBdebian/nodejs/extcopies\fP)
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 \fB/usr/share/nodejs/<module\-name>/package\.json\fP):

•: 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 \fB@types/<foo>\fP 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 \fBdebian/nodejs/root_modules\fP 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.

COPYRIGHT AND LICENSE

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;

November 2022