apn-test

1.3.1 verified Fri May 01 auth: no javascript maintenance

apn-test (v1.3.1) is a CLI tool and Node.js library to quickly send a test push notification to an iOS device via Apple Push Notification service (APNs). It simplifies testing by requiring only a device token, certificate, and key. The package supports both single and multiple device tokens, payload customization, and production/development environments. It is lightweight, with no runtime dependencies, and offers a simple API. Maintenance is low; the last release was in 2017.

Common errors

error Error: ENOENT: no such file or directory, open 'cert.pem' ↓

cause Default certificate file not found; must specify path via options or CLI.

fix

Provide absolute or relative path to cert.pem via --cert option.

error Error: socket hang up ↓

cause APNs server connection failure due to network or invalid credentials.

fix

Check cert/key files, ensure proper permissions, verify network.

error Response code: 400, body: {"reason":"BadDeviceToken"} ↓

cause Provided device token is invalid or not for the selected environment.

fix

Verify token correctness and use appropriate environment (development/production).

Warnings

gotcha CLI uses 'apn' not 'apn-test' as the command name. ↓

fix Run CLI with `apn` instead of `apn-test`.

gotcha The 'token' option in CLI accepts a comma-separated list, but JavaScript API expects a single token string. ↓

fix For multiple tokens, call apnTest multiple times or use the CLI.

breaking Node.js engine requirement >=0.10.0; may not work on very old or very new Node versions. ↓

fix Use Node >=0.10.0 and <=12.x (best effort).

Install

npm install apn-test

yarn add apn-test

pnpm add apn-test

Imports

apnTest
wrong
```
import apnTest from 'apn-test';
```
correct
```
var apnTest = require('apn-test');
```
This package does not support ES modules; use CommonJS.
CLI command 'apn'
wrong
```
apn-test "Hello" --token=DEVICE_TOKEN
```
correct
```
apn "Hello" --token=DEVICE_TOKEN --cert=cert.pem --key=key.pem
```
The CLI command is 'apn', not 'apn-test'. Install globally and run via terminal.
Default export
wrong
```
var apnTest = require('apn-test').default;
```
correct
```
var apnTest = require('apn-test');
```
The package exports a single function directly, not as a property.

Quickstart

Send a test push notification to a device token using certificate and key files.

var apnTest = require('apn-test');

var message = 'Hello, iOS!';
var options = {
  cert: '/path/to/cert.pem',
  key: '/path/to/key.pem',
  token: 'uney4jcnvvw5bc2vlvazog4au1xa0zbcbsjwlfgaj1pi9blcdltgktncfxfwhs5'
};

apnTest(message, options, function(err, response) {
  if (err) {
    console.error('Failed:', err);
  } else {
    console.log('Success:', response);
  }
});