ACP Agentic Checkout Test CLI

Test and validate your ACP Agentic Checkout implementation

A CLI tool for testing ACP (Agentic Commerce Protocol) Agentic Checkout API endpoints against OpenAI's official specification. Perfect for merchants building AI-native checkout experiences for ChatGPT and other AI platforms.

Features

✅ Comprehensive Testing

• Full API Coverage: Tests all 5 ACP Checkout endpoints (CREATE, UPDATE, COMPLETE, CANCEL, GET)
• 151 Test Cases: Production-grade test suite covering happy paths, edge cases, and error scenarios
• Spec Compliance: Validates responses against OpenAI's official OpenAPI schema

🎯 Smart Validation

• Automatic Schema Validation: Ensures your API responses match the ACP specification
• Totals Calculation Checks: Validates monetary calculations (subtotal, tax, fees, totals)
• State Management Testing: Verifies correct checkout session state transitions
• Idempotency Verification: Tests retry safety for CREATE and COMPLETE operations

📊 Developer-Friendly Output

• Clear Test Reports: See exactly what passed and what needs fixing
• Error Details: Detailed messages showing what went wrong and why
• Fast Execution: Runs 151 tests in seconds

🔧 Flexible Configuration

• Config File: Use acp.config.yaml for persistent settings
• CLI Arguments: Override config with command-line flags
• Interactive Mode: Prompts for missing required fields

Installation

Prerequisites

• Node.js 20.0.0 or higher
• npm or yarn

Install via npm

npm install -g @nekuda/acp-test

Install from source

git clone <repo-url>
cd acp-test-cli
npm install
npm run build
npm link

Quick Start

1. Initialize Configuration

Create a config file with your API details:

acp-test init

This creates acp.config.yaml:

checkoutUrl: https://your-api.com
apiKey: your_api_key_here
apiVersion: '2025-09-29'

2. Run Tests

Run the full test suite against your API:

acp-test run

Or specify options directly:

acp-test run \
  --checkout-url https://your-api.com \
  --api-key your_key_here \
  --api-version 2025-09-29

3. Review Results

The CLI will show you test results in real-time:

✓ should create checkout session with items (125ms)
✓ should update session with shipping address (89ms)
✓ should select fulfillment option (76ms)
✓ should complete checkout with payment (152ms)

Test Files  1 passed (1)
     Tests  151 passed (151)

Usage

Commands

init

Create or update your ACP test configuration file.

acp-test init

run

Execute the full ACP compliance test suite.

acp-test run [options]

Options:

• -u, --checkout-url <url> - Your ACP Checkout API base URL
• -k, --api-key <key> - API key for authentication
• -v, --api-version <version> - ACP API version (default: 2025-09-29)
• -c, --config <path> - Path to config file (default: acp.config.yaml)

validate

Validate your ACP API implementation.

acp-test validate [options]

Same options as run command.

Configuration File

Create acp.config.yaml in your project root:

# Required: Your ACP Checkout API endpoint
checkoutUrl: https://api.yourstore.com

# Required: Authentication key
apiKey: sk_test_abc123

# Optional: API version (defaults to latest)
apiVersion: '2025-09-29'

# Optional: Request timeout in milliseconds
timeout: 30000

What Gets Tested

Core Checkout Flow

• ✅ Session creation with/without addresses
• ✅ Updating items, quantities, and customer details
• ✅ Shipping address validation and fulfillment options
• ✅ Fulfillment selection and cost calculation
• ✅ Payment token handling
• ✅ Session completion and order confirmation
• ✅ Session cancellation

Validation & Error Handling

• ✅ Missing required fields (missing error code)
• ✅ Invalid data formats (invalid error code)
• ✅ Out of stock scenarios (out_of_stock error code)
• ✅ Payment declines (payment_declined error code)
• ✅ Proper HTTP status codes (200, 201, 400, 409)

Data Integrity

• ✅ Currency format validation (ISO 4217)
• ✅ Address format validation (ISO 3166)
• ✅ Monetary calculations (amounts in minor units)
• ✅ Totals formula: total = subtotal - discount + fulfillment + tax + fee
• ✅ Line item calculations: total = subtotal + tax, subtotal = base_amount - discount

Advanced Features

• ✅ Idempotency key handling
• ✅ Request ID tracing
• ✅ API versioning
• ✅ Webhook payload validation
• ✅ Links (ToS, Privacy Policy)

Example Test Output

PASS  src/tests/checkout.test.ts (4.2s)
  Checkout Session Management
    ✓ should create session with single item
    ✓ should create session with multiple items
    ✓ should update session with buyer info
    ✓ should add shipping address
    ✓ should retrieve fulfillment options
    ✓ should select shipping method
    ✓ should complete checkout with payment

  Idempotency
    ✓ should return same session for duplicate CREATE with same key
    ✓ should return 409 for same key with different body
    ✓ should return same result for duplicate COMPLETE

  Error Scenarios
    ✓ should handle missing items field (400)
    ✓ should handle invalid postal code
    ✓ should handle out of stock items
    ✓ should handle payment declined

✓ 151 tests passed

Testing Against OpenAI ChatGPT

Before going live with ChatGPT Instant Checkout:

1. Run Full Test Suite: Ensure all 151 tests pass
2. Review Error Handling: Verify all error codes are implemented
3. Check Totals: Confirm monetary calculations are accurate
4. Test Idempotency: Verify safe retry behavior
5. Validate Webhooks: Ensure order events are emitted correctly

Development

Build

npm run build

Outputs compiled CLI to dist/cli.js with TypeScript declarations.

Type Checking

npm run typecheck

Linting

npm run lint
npm run format

Run Tests

npm test

Project Structure

acp-test-cli/
├── src/
│   ├── cli.ts                 # Main CLI entry point
│   ├── commands/              # CLI command implementations
│   │   ├── init.ts
│   │   ├── run.ts
│   │   └── validate.ts
│   ├── config/                # Configuration handling
│   ├── tests/                 # ACP test suite (151 tests)
│   │   ├── checkout.test.ts
│   │   ├── error-scenarios.test.ts
│   │   ├── idempotency.test.ts
│   │   └── totals-validation.test.ts
│   └── types/                 # TypeScript definitions
├── spec/                      # OpenAPI schema
├── package.json
└── tsup.config.ts             # Build configuration

Resources

• ACP Documentation: https://agenticcommerce.dev/
• OpenAI Commerce Docs: https://developers.openai.com/commerce
• Apply for ChatGPT Merchants: https://chatgpt.com/merchants
• ACP GitHub: https://github.com/agentic-commerce-protocol/agentic-commerce-protocol

Contributing

If you're interested in collaborating or contributing, get in touch at [email protected].

License

Licensed under the Apache 2.0 License.