Name: citgm
Owner: Node.js Foundation
Description: Canary in the Gold Mine
Created: 2015-07-22 23:16:47.0
Updated: 2018-05-22 11:05:42.0
Pushed: 2018-05-24 06:17:12.0
Homepage: https://www.npmjs.com/package/citgm
Size: 684
Language: JavaScript
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
citgm is a simple tool for pulling down an arbitrary module from npm and testing it using a specific version of the node runtime.
The Node.js project uses citgm to smoke test our releases and controversial changes. The Jenkins job that utilizes citgm can be found on our CI.
install -g citgm
m --help
(If citgm is installed globally, you can also man citgm)
e: citgm [options] <module>
ons:
, --help output usage information
, --version output the version number
config Path to a JSON config file
, --verbose, --loglevel [level], Verbose output (silly, verbose, info, warn, error)
, --npm-loglevel [level] Verbose output (silent, error, warn, http, info, verbose, silly)
, --lookup <path> Use the lookup table provided at <path>
, --nodedir <path> Path to the node source to use when compiling native addons
, --test-path <path> Path to prepend to $PATH when running tests
, --no-color Turns off colorized output
, --su Allow running the tool as root.
, --markdown Output results in markdown
, --tap [path] Output results in tap with optional file path
, --junit [path] Output results in junit xml with optional file path
, --timeout <length> Set timeout for npm install
, --sha <commit-sha> Install module from commit-sha
, --uid <uid> Set the uid (posix only)
, --gid <uid> Set the gid (posix only)
, --append Turns on append results to file mode rather than replace
tmpDir <path> Directory to test modules in
Test the latest underscore module or a specific version:
`citgm underscore@latest` or `citgm underscore@1.3.0`
Test a local module:
`citgm ./my-module`
Test using a tar.gz from Github:
`citgm http://github.com/jasnell/activitystrea.ms/archive/master.tar.gz`
When using a JSON config file, the properties need to be the same as the
longer-form CLI options. You can also use environment variables. For example,
CITGM_TEST_PATH=$HOME/bin is the same as --test-path $HOME/bin.
The tool requires online access to the npm registry to run. If you want to point to a private npm registry, then you'll need to set that up in your npm config separately before running citgm.
By default, the tool will prevent users from running as root unless the
-s or --su CLI switch is set. If the tool is launched as root, it will
attempt to silently and automatically downgrade permissions. If it cannot
downgrade, it will print an error and exit the process.
The tool will also automatically check npm to see if there are updates
available. If a newer version has been published to npm, an info notice
will appear in the verbose output. If the -v or --verbose flag is not
set, the update notice will not be displayed.
If you want to run all the test suites for all modules found in a lookup table use citgm-all. It will automate the running of all tests and give itemized results at the end. It has all the same options as citgm except for the added markdown option which will print the results in markdown.
e: citgm-all [options]
ons:
, --help output usage information
, --version output the version number
config Path to a JSON config file
, --verbose, --loglevel [level], Verbose output (silly, verbose, info, warn, error)
, --npm-loglevel [level] Verbose output (silent, error, warn, http, info, verbose, silly)
, --lookup <path> Use the lookup table provided at <path>
, --nodedir <path> Path to the node source to use when compiling native addons
, --test-path <path> Path to prepend to $PATH when running tests
, --no-color Turns off colorized output
, --su Allow running the tool as root.
, --markdown Output results in markdown
, --tap [path] Output results in tap with optional file path
, --junit [path] Output results in junit xml with optional file path
, --timeout <length> Set timeout for npm install
, --fail-flaky Ignore flaky flags. Do not ignore any failures.
, --uid <uid> Set the uid (posix only)
, --gid <uid> Set the gid (posix only)
, --append Turns on append results to file mode rather than replace
, --parallel <number> Run tests in parallel
, --autoParallel Run tests in parallel (automatically detect core count)
tmpDir <path> Directory to test modules in
includeTags tag1 tag2 Only test modules from the lookup that contain a matching tag field
excludeTags tag1 tag2 Specify which tags to skip from the lookup (takes priority over includeTags)
Module names are automatically added as tags.
When using a JSON config file, the properties need to be the same as the
longer-form CLI options. You can also use environment variables. For example,
CITGM_TEST_PATH=$HOME/bin is the same as --test-path $HOME/bin.
You can also test your own list of modules:
m-all -l ./path/to/my_lookup.json
For syntax, see lookup.json, the available attributes are:
": true Download the module from npm instead of github
ter": true Use the master branch
fix": "v" Specify the prefix used in the module version.
ky": true Ignore failures
p": true Completely skip the module
ectFail" Expect the module to fail, error if it passes
o": "https://github.com/pugjs/jade" - Use a different github repo
pAnsi": true Strip ansi data from output stream of npm
": "<git-commit-sha>" Test against a specific commit
Var" Pass an environment variable before running
tall": ["--param1", "--param2"] - Array of extra command line parameters passed to 'npm install'
ntainers": ["user1", "user2"] - List of module maintainers to be contacted with issues
s": ["tag1", "tag2"] Specify which tags apply to the module
oreGitHead": Ignore the gitHead field if it exists and fallback to using github tags
If you want to pass options to npm, eg --registry, you can usually define an
environment variable, eg "npm_config_registry": "https://www.xyz.com".
You can run the test suite using npm
run test
This will run both a linter and a tap based unit test suite.
If you want to submit a module to be run in the Node.js CI, see the requirements.
You can identify the module to be tested using the same syntax supported by
the npm install CLI command
m activitystrea.ms@latest
m git+http://github.com/jasnell/activitystrea.ms
Quite a few modules published to npm do not have their tests included, so we end up having to go directly to github. The most reliable approach is pulling down a tar ball for a specific branch from github:
m https://github.com/caolan/async/archive/master.tar.gz
To simplify working with modules that we know need special handling, a lookup
table mechanism is provided. This mechanism allows citgm to substitute certain
known npm specs (lodash for instance) with their github tarball alternatives.
The lookup mechanism is switched on using the -l or
--lookup command line option.
m lodash@latest
There is a built in lookup.json in the lib directory that will be used by default. If you want to use an alternative lookup.json file, pass in the path:
m --lookup ../path/to/lookup.json lodash@latest
For the most part, the built in table should be sufficient for general use.
You may experience some wonkiness on Windows as the tool has not been fully tested on that platform.
The tool uses the npm and node in the PATH. To change which node and npm the tool uses, change the PATH before launching citgm
Running the tool in verbose mode (CLI switch -v silly) outputs significantly
more detail (which is likely what we'll want in a fully automated run)
If you've taken a look at the dependencies for this tool, you'll note that there are quite a few, some of which may not be strictly required. The reason for the large number of dependencies is that this is a testing tool, and many of the dependencies are broadly used. A large part of the reason for using them is to test that they'll work properly using the version of node being tested.
PRs are welcome!