.TH "PKG\-JS\-AUTOPKGTEST" "" "October 2022" "" ""
.SH "NAME"
\fBpkg-js-autopkgtest\fR \- autopkgtest runner to automatically test Node\.js packages
.P
[[_TOC_]]
.SH SYNOPSIS
.RS 0
.IP \(bu 2
in debian/control, insert "Testsuite: autopkgtest\-pkg\-nodejs"
.IP \(bu 2
write upstream test in debian/tests/pkg\-js/test (will be launched by
\fBsh \-e\fP)
.IP \(bu 2
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

.RE
.P
That's all, other debian/tests files will be written on\-the\-fly by
autodep8 during autopkgtest
.P
If you want to launch the same test during build, simply add
\fBdh\-sequence\-nodejs\fP in build dependencies
.SH HOW IT WORKS
.RS 0
.IP \(bu 2
if directory \fBdebian/tests/test_modules\fP exists, \fBNODE_PATH\fP will be set
to \fBNODE_PATH=debian/tests/test_modules:node_modules\fP
.IP \(bu 2
if additional modules were linked during build, they will be linked into
\fBnode_module\fP \fI(\fBdebian/nodejs/extlinks\fP)\fR
.IP \(bu 2
if additional modules were copies during build, they will be copied into
\fBnode_module\fP \fI(\fBdebian/nodejs/extcopies\fP)\fR
.IP \(bu 2
if package contains some other components, they will be linked into
\fBnode_module\fP
.IP \(bu 2
autopkgtest will launch 2 tests:
.RS
.IP \(bu 2
a "require" test \fI(see below)\fR
.IP \(bu 2
the test defined in debian/tests/pkg\-js/test in a temporary dir (it
links installed files)

.RE
.IP \(bu 2
if \fBdh\-sequence\-nodejs\fP is a build dependency, \fBdh_auto_test\fP will
launch the same test \fI(debian/tests/pkg\-js/test)\fR if exists, else just a
\fBnode \-e "require('\.')"\fP\|\. Note that you can override test during build
using \fBdebian/nodejs/test\fP
.IP \(bu 2
if file \fBdebian/tests/pkg\-js/require\-name\fP exists, its content will be used
as module name in "require" test \fI(instead of using package\.json value)\fR

.RE
.SH FULL EXAMPLE
.RS 0
.IP \(bu 2
debian/control

.RE
.P
.RS 2
.nf
\|\.\.\.
Testsuite: autopkgtest\-pkg\-nodejs
Build\-Depends: dh\-sequence\-nodejs
\|\.\.\.
.fi
.RE
.RS 0
.IP \(bu 2
debian/tests/pkg\-js/test

.RE
.P
.RS 2
.nf
mocha \-R spec
.fi
.RE
.SH ADDITIONAL TEST PACKAGES OR TEST RESTRICTIONS
.P
autodep8 allows one to add additional packages during autopkgtest (and/or
additional restrictions) by using a \fBdebian/tests/autopkgtest\-pkg\-nodejs\.conf\fP
file:
.P
.RS 2
.nf
extra_depends=mocha, npm
extra\-restrictions=needs\-internet
.fi
.RE
.SH ENABLE \fBproto\fR
.P
Since version 0\.15\.0, pkg\-js\-autopkgtest launches Node\.js with
\fB\-\-disable\-proto=throw\fP\|\. This causes tests to fail if
\fBObject\.prototype\.__proto__\fP property is used\.
.P
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
\fBdebian/tests/pkg\-js/enable_proto\fP file, until Debian's Node\.js enables this
feature by default\.
.SH THE "REQUIRE" TEST
.SS How it works
.P
First, \fBpkg\-js\-autopkgtest\fR searches the module name\.
.RS 0
.IP \(bu 2
if \fBdebian/tests/pkg\-js/require\-name\fP exists, its content will be used as
module name
.IP \(bu 2
else if looks at \fBpackage\.json\fP "name" field:
.RS
.IP \(bu 2
if \fBdebian/nodejs/main\fP exists, like \fBdh\-sequence\-nodejs\fR, it uses the
\fBpackage\.json\fP from this directory
.IP \(bu 2
else it uses \fB\|\./package\.json\fP

.RE

.RE
.P
Then \fBpkg\-js\-autopkgtest\fR looks at package\.json fields, not using the file
mentioned above, but using the file installed by the Debian package to test
\fI(ie \fB/usr/share/nodejs/<module\-name>/package\.json\fP)\fR:
.RS 0
.IP \(bu 2
if \fBtype\fR equals \fBmodule\fP, then:
.RS
.IP \(bu 2
it builds a \fBnode_modules\fP directory with all available dependencies of
the module
.IP \(bu 2
it builds a test\.mjs file that tries to import the module to test and
launch it

.RE
.IP \(bu 2
if \fBmain\fR isn't defined and \fBindex\.js\fP doesn't exist, it skip the test
\fI(this avoids to try to test \fB@types/<foo>\fP modules)\fR
.IP \(bu 2
else it simply launches a \fBnodejs \-e "require('$moduleName')"\fP

.RE
.P
Since version 0\.10\.0, \fBpkg\-js\-autopkgtest\fR does the same test for all other
modules installed in nodejs root directories \fI(components installed by
dh\-sequence\-nodejs using \fBdebian/nodejs/root_modules\fP file)\fR\|\. If one fail, the
whole test is marked as failed\.
.P
Returned values:
.RS 0
.IP \(bu 2
0 if all tests succeed \fI(even if some secondary modules are skipped)\fR
.IP \(bu 2
77 if all tests succeed but the main module test was skipped\. This value
is used by autopkgtest to report a \fBSKIP\fR instead of a failure\.
.IP \(bu 2
else, the number of failure\. Then autopkgtest considers the test as \fBFAIL\fR

.RE
.SS Customize require test
.P
If you want to skip some secondary module tests, simply list them in
\fBdebian/tests/pkg\-js/require\-SKIP\fP \fI(one module per line)\fR\|\.
.P
If you want to skip the whole "require" test, use this:
.P
.RS 2
.nf
echo require > debian/tests/pkg\-js/SKIP
.fi
.RE
.SH THE MAIN TEST
.P
\fBpkg\-js\-autopkgtest\fR uses the same test than \fBdh\-sequence\-nodejs\fR: it
launches \fBsh \-ex debian/tests/pkg\-js/test\fP but using the files installed by
the Debian package\.
.SS How it works
.P
\fBpkg\-js\-autopkgtest\fR search for module name using the same way than "require"
test\. Then it prepares the test environment:
.RS 0
.IP \(bu 2
it creates a temporary directory
.IP \(bu 2
it links all files installed in the directory corresponding to module name
\fI(/usr/share/nodejs/<module\-name>)\fR
.IP \(bu 2
it creates a \fBnode_modules\fP directory and links into it:
.RS
.IP \(bu 2
all modules listed in \fBdebian/nodejs/extlinks\fP
.IP \(bu 2
all modules present in \fBdebian/build_modules\fP and \fBdebian/tests/test_modules\fP
.IP \(bu 2
all other modules installed by the Debian package in nodejs root directories
\fI(\fBdebian/nodejs/root_modules\fP)\fR

.RE
.IP \(bu 2
it copies in \fBnode_modules\fP directory all modules listed in
\fBdebian/nodejs/extcopies\fP
.IP \(bu 2
if looks at \fBdebian/tests/pkg\-js/files\fP
.RS
.IP \(bu 2
if it exists, it copies all files/directories listed in it from source
directory to temporary one
.IP \(bu 2
else it copies from source directory to temporary one:
.RS
.IP \(bu 2
all \fBtest*\fP files
.IP \(bu 2
all \fBMakefile\fP like files \fI(rollup\.config\.js, gulpfile\.js,\.\.\. )\fR

.RE

.RE

.RE
.P
Then it changes its directory to the temporary one launches the test using
\fBsh \-ex debian/tests/pkg\-js/test\fP\|\.
.SH SEE ALSO
.P
pkg\-js\-tools(7), autodep8(1)
.SH COPYRIGHT AND LICENSE
.P
Copyright Yadd <yadd@debian\.org>
.P
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\.
.P
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\.
.P
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 \fIhttp://www\.gnu\.org/licenses/\fR;