Postman ESLint

A CLI tool to lint JavaScript scripts in Postman collections using ESLint.

Installation

Install globally to use from anywhere:

npm install -g postman-eslint

Or use locally in your project:

npm install --save-dev postman-eslint

Usage

Run postman-eslint from your project directory (where your eslint.config.js is located):

postman-eslint --collection <collection-id> --api-key <your-api-key>

Or run without installing using npx:

npx postman-eslint --collection <collection-id> --api-key <your-api-key>

Options

• -c, --collection <id> (required): Postman collection ID
• -k, --api-key <key> (optional): Postman API key (can also use POSTMAN_API_KEY environment variable)

Configuration

The tool uses ESLint's flat config format (eslint.config.js) from your project root. ESLint will automatically discover this file when running.

A sample eslint.config.js is included with this package that has Postman-specific globals like pm already configured.

If You Don't Have an ESLint Config

If you don't have an eslint.config.js in your project, you can:

1. Copy the included sample config:

   If installed locally:

   cp node_modules/postman-eslint/eslint.config.js ./

   If installed globally:

   cp "$(npm root -g)/postman-eslint/eslint.config.js" ./

2. Create your own eslint.config.js:

   module.exports = [
     {
       languageOptions: {
         ecmaVersion: 'latest',
         globals: {
           pm: 'readonly',
           console: 'readonly'
         }
       },
       rules: {
         'semi': ['error', 'always'],
         'quotes': ['warn', 'single']
       }
     }
   ];

3. Or install and use a preset like @eslint/js:

   npm install --save-dev @eslint/js

   Then create eslint.config.js:

   const js = require('@eslint/js');
   
   module.exports = [
     js.configs.recommended,
     {
       languageOptions: {
         globals: { pm: 'readonly' }
       }
     }
   ];

How It Works

1. Fetches the collection from Postman API using the provided collection ID and API key
2. Parses the collection using the official Postman Collection SDK
3. Extracts all JavaScript scripts from:
   • Collection-level pre-request scripts
   • Collection-level test scripts
   • Folder-level pre-request scripts
   • Folder-level test scripts
   • Request-level pre-request scripts
   • Request-level test scripts
4. Runs ESLint against each script using your local ESLint configuration
5. Reports any errors or warnings found

Getting Your Collection ID

1. Open your collection in Postman
2. Click the "..." menu on the collection
3. Select "Share Collection"
4. The collection ID is in the URL: https://www.postman.com/collections/{collection-id}

Alternatively, you can find it in the collection's info section.

Getting Your API Key

1. Go to Postman API Keys
2. Click "Generate API Key"
3. Give it a name and copy the key

Development

Running Tests

npm test                # Run all tests
npm run test:watch      # Run tests in watch mode
npm run test:coverage   # Run tests with coverage report

The project includes comprehensive tests for all modules:

• test/postman.test.js - Tests for Postman API client
• test/extract.test.js - Tests for script extraction logic
• test/eslint.test.js - Tests for ESLint runner

Exit Codes

• 0: No errors found
• 1: Errors found or execution failed

Example Output

Fetching collection abc123...
Extracting scripts...
Found 3 script(s). Running ESLint...

================================================================================
My Collection > Login Request [prerequest]
================================================================================
   1 | const username = "admin"
   2 | const password = "secret123"
   3 | pm.environment.set("username", username)
   4 | console.log("Setting credentials")

--------------------------------------------------------------------------------
Lint Results:
--------------------------------------------------------------------------------
  1:18  warning  Strings must use singlequote  quotes
  2:18  warning  Strings must use singlequote  quotes
  3:1   error    Missing semicolon  semi
  4:1   error    Missing semicolon  semi

================================================================================
My Collection > Login Request [test]
================================================================================
   1 | pm.test("Status code is 200", function () {
   2 |   pm.response.to.have.status(200);
   3 | });

✓ No issues found

================================================================================
SUMMARY
================================================================================
Total scripts: 3
Scripts with issues: 1
Total errors: 2
Total warnings: 2

✖ 2 error(s), 2 warning(s) found

Disclaimer

This is a community project and not an official Postman product.