--- name: "pkg-js-autopkgtest" section: "7" platform: "linux" package: "pkg-js-autopkgtest" version: "0.15.23" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/pkg-js-autopkgtest" --- # pkg-js-autopkgtest(7) autopkgtest runner to automatically test Node.js packages ## 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/\/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/\** *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*\ *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/\** - • 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)](/pkg-js-tools/7.md), [autodep8(1)](/autodep8/1.md) ## COPYRIGHT AND LICENSE Copyright Yadd \ 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* ⟨http://www.gnu.org/licenses/⟩;