ping: docs, bugfix, tests

* The command line command was broken
* wrote tests for the command itself
* added documentation for both the API and CLI versions

PR-URL: https://github.com/npm/npm/pull/8800

4 files changed, 101 insertions, 1 deletions

diff --git a/doc/api/npm-ping.md b/doc/api/npm-ping.md
new file mode 100644
index 000000000..4357fe2ba
--- /dev/null
+++ b/doc/api/npm-ping.md
@@ -0,0 +1,14 @@
+npm-ping(3) -- Ping npm registry
+================================
+
+## SYNOPSIS
+
+    npm.registry.ping(registry, options, function (er, pong))
+
+## DESCRIPTION
+
+Attempts to connect to the given registry, returning a `pong`
+object with various metadata if it succeeds.
+
+This function is primarily useful for debugging connection issues
+to npm registries.
diff --git a/doc/cli/npm-ping.md b/doc/cli/npm-ping.md
new file mode 100644
index 000000000..f0e628915
--- /dev/null
+++ b/doc/cli/npm-ping.md
@@ -0,0 +1,16 @@
+npm-ping(1) -- Ping npm registry
+================================
+
+## SYNOPSIS
+
+    npm ping [--registry <registry>]
+
+## DESCRIPTION
+
+Ping the configured or given npm registry and verify authentication.
+
+## SEE ALSO
+
+* npm-config(1)
+* npm-config(7)
+* npmrc(5)
diff --git a/lib/ping.js b/lib/ping.js
index 9a07d93a5..23b18bfba 100644
--- a/lib/ping.js
+++ b/lib/ping.js
@@ -11,8 +11,10 @@ function ping (args, silent, cb) {
   }
   var registry = npm.config.get('registry')
   if (!registry) return cb(new Error('no default registry set'))
+  var auth = npm.config.getCredentialsByURI(registry)
 
-  npm.registry.ping(registry, function (er, pong) {
+  npm.registry.ping(registry, {auth: auth}, function (er, pong) {
+    if (!silent) console.log(JSON.stringify(pong))
     cb(er, er ? null : pong)
   })
 }
diff --git a/test/tap/ping.js b/test/tap/ping.js
new file mode 100644
index 000000000..13fc4bec9
--- /dev/null
+++ b/test/tap/ping.js
@@ -0,0 +1,68 @@
+var fs = require('fs')
+var path = require('path')
+
+var mkdirp = require('mkdirp')
+var mr = require('npm-registry-mock')
+var rimraf = require('rimraf')
+var test = require('tap').test
+
+var common = require('../common-tap.js')
+
+var pkg = path.resolve(__dirname, 'ping')
+var opts = { cwd: pkg }
+
+var outfile = path.join(pkg, '_npmrc')
+
+var contents = function () {
+}.toString().split('\n').slice(1, -1).join('\n')
+
+var pingResponse = {
+  host: 'registry.npmjs.org',
+  ok: true,
+  username: null,
+  peer: 'example.com'
+}
+
+function mocks (server) {
+  server.get('/-/ping?write=true').reply(200, JSON.stringify(pingResponse))
+}
+
+test('setup', function (t) {
+  cleanup()
+  setup()
+  t.end()
+})
+
+test('npm ping', function (t) {
+  mr({ port: common.port, plugin: mocks }, function (err, s) {
+    if (err) throw err
+
+    common.npm([
+      'ping',
+      '--registry', common.registry,
+      '--loglevel', 'silent',
+      '--userconfig', outfile
+    ], opts, function (err, code, stdout) {
+      s.close()
+      t.ifError(err, 'no error output')
+      t.notOk(code, 'exited OK')
+
+      t.same(JSON.parse(stdout), pingResponse)
+      t.end()
+    })
+  })
+})
+
+test('cleanup', function (t) {
+  cleanup()
+  t.end()
+})
+
+function setup () {
+  mkdirp.sync(pkg)
+  fs.writeFileSync(outfile, contents)
+}
+
+function cleanup () {
+  rimraf.sync(pkg)
+}