🔐 PCI-DSS Automation Framework

Enterprise-Grade Payment Security Testing

TypeScript · Jest · Playwright

A plug-and-play automated testing framework covering the critical, testable requirements of PCI-DSS v4.0, including API security, browser UI security, injection defences, and audit compliance. Built for QA engineers, security teams, and freelance consultants who need a portfolio-ready, reusable foundation.

Quick Start · Demo Story · Test Coverage · Architecture · Docs

---

✨ What This Framework Does

This project automates the verification of payment system security controls aligned to PCI-DSS v4.0. It includes:

• A lightweight mock payment API + checkout UI (Express + TypeScript), no third-party accounts needed
• API tests covering authentication, card data masking, access control, and audit logging
• UI tests (Playwright) verifying browser-level PCI compliance: field masking, autocomplete-off, storage leakage
• Security tests for injection attacks, security headers, and transmission controls
• A SECURE_MODE toggle that lets you demo failing vs passing tests in the same project
• An HTML test report generated automatically after every run
• A GitHub Actions CI/CD pipeline ready to go

---

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm 9+

Install

git clone https://github.com/yourusername/pci-dss-automation.git
cd pci-dss-automation
npm install
npx playwright install chromium

Run Everything (One Command)

npm run dev

This starts the mock payment server and runs the full test suite simultaneously.

Open the Payment UI

http://localhost:3000

View the Test Report

After tests complete, open:

reports/html/index.html

---

🎬 Demo Story

This framework is designed to tell a complete QA story in 3 steps. Perfect for client demos and technical interviews.

Step 1 — Run in INSECURE mode (catch the violations)

npm run demo:fail

The mock server starts with intentional PCI violations:

• Full PAN returned in API responses
• CVV leaked in payment response
• No security headers
• Server version exposed

Tests FAIL — detecting every violation.

Step 2 — Run in SECURE mode (verify fixes)

npm run demo:pass

The mock server enforces all PCI controls. Same tests now PASS.

Step 3 — Show the report

reports/html/index.html

The HTML report shows every test, which PCI requirement it maps to, and pass/fail status.

This is the QA story: find it → document it → verify the fix.

---

🧪 Test Suites

API Tests — /src/tests/api/

File	PCI Requirements	Key Scenarios
auth.test.ts	Req 8, Req 2	Valid login, token expiry, tampered JWT, brute-force lockout, default credential rejection
card-data.test.ts	Req 3	PAN masking in responses, CVV never returned, no full PAN in logs, insecure mode detection
access-control.test.ts	Req 7, Req 10	RBAC by role, horizontal privilege escalation, audit log immutability
audit-log.test.ts	Req 10	Login events logged, card access logged, log field completeness, log immutability

Security Tests — /src/tests/security/

File	PCI Requirements	Key Scenarios
headers.test.ts	Req 2, Req 6	HSTS, X-Frame-Options, CSP, nosniff, server version hidden, CORS
injection.test.ts	Req 6	SQL injection × 5 payloads, XSS × 5 payloads, oversized input, NoSQL injection
tls.test.ts	Req 4	HSTS max-age, includeSubDomains, no token in URL params, no card data in plain-text

UI Tests — /src/tests/ui/ (Playwright)

File	PCI Requirements	Key Scenarios
card-form.test.ts	Req 3, Req 6	autocomplete=off on all sensitive fields, CVV type=password, PAN not in DOM/storage, masked result display, CVV cleared on submit
session.test.ts	Req 8	Token in sessionStorage not localStorage, fresh context isolation, no card data in cookies, fields cleared on reload

---

📋 PCI-DSS Coverage

Req	Description	Status	Test Files
1	Network Security Controls	⬜ Out of scope*	—
2	Secure Configurations	✅ Covered	headers.test.ts, auth.test.ts
3	Protect Stored Account Data	✅ Covered	card-data.test.ts, card-form.test.ts
4	Transmission Security (TLS)	✅ Covered	tls.test.ts
5	Malware Protection	⬜ Out of scope*	—
6	Secure Development (OWASP)	✅ Covered	injection.test.ts, headers.test.ts
7	Access Control / RBAC	✅ Covered	access-control.test.ts
8	Authentication & Sessions	✅ Covered	auth.test.ts, session.test.ts
9	Physical Access	⬜ Out of scope*	—
10	Logging & Monitoring	✅ Covered	audit-log.test.ts
11	Regular Security Testing	✅ Partial	All security tests
12	Organizational Policies	⬜ Out of scope*	—

*Requirements 1, 5, 9, 12 cover infrastructure, endpoint, physical, and policy domains — not automatable at the application layer. See docs/PCI-DSS-REQUIREMENTS.md for detailed explanations.

Total automatable requirements covered: 7 / 8 (87.5%)

---

🏗️ Architecture

pci-dss-automation/
│
├── mock-server/                 ← Express payment server (API + UI)
│   ├── routes/
│   │   ├── auth.ts              ← POST /api/auth/login, /logout
│   │   ├── payments.ts          ← CRUD /api/payments
│   │   └── audit-logs.ts        ← GET /api/audit-logs (read-only)
│   ├── middleware/
│   │   └── auth.ts              ← JWT validation, RBAC enforcement
│   ├── data/
│   │   └── store.ts             ← In-memory users, transactions, audit logs
│   ├── public/
│   │   └── index.html           ← Payment checkout UI
│   └── index.ts                 ← Server entry point (SECURE_MODE toggle)
│
├── src/
│   ├── tests/
│   │   ├── api/                 ← Supertest API tests
│   │   ├── ui/                  ← Playwright browser tests
│   │   └── security/            ← Security header & injection tests
│   ├── helpers/
│   │   ├── api-client.ts        ← Axios wrapper with auth management
│   │   ├── token-helper.ts      ← JWT generation & manipulation
│   │   └── card-helper.ts       ← PAN masking verification, Luhn check
│   ├── fixtures/
│   │   ├── cards.ts             ← Test card numbers (fake, Luhn-valid)
│   │   └── users.ts             ← Test users by role
│   └── types/
│       └── index.ts             ← Shared TypeScript interfaces
│
├── config/
│   ├── jest.config.ts           ← Jest + HTML reporter configuration
│   └── environments.ts          ← local / staging / prod config
│
├── docs/
│   ├── PCI-DSS-REQUIREMENTS.md  ← Full requirement guide with testing notes
│   ├── API-DOCUMENTATION.md     ← API reference with CRUD samples
│   └── UI-FIELDS-REFERENCE.md   ← Payment form field PCI compliance guide
│
├── reports/html/                ← Auto-generated HTML test reports
├── .github/workflows/
│   └── pci-tests.yml            ← GitHub Actions CI/CD pipeline
└── README.md

---

⚙️ Configuration

SECURE_MODE

The key feature for demos. Controls whether the mock server enforces PCI controls.

SECURE_MODE=true npm run mock:server    # All controls enforced — tests PASS
SECURE_MODE=false npm run mock:server   # Intentional violations — tests FAIL (catch mode)

Test Environment

Point the tests at a different target:

TEST_ENV=staging npm test    # Uses staging URLs from config/environments.ts
TEST_ENV=local npm test      # Default: http://localhost:3000

Available npm Scripts

Command	Description
npm run dev	Start server + run all tests
npm run demo:fail	INSECURE mode demo — tests catch violations
npm run demo:pass	SECURE mode demo — all tests pass
npm run mock:server	Start mock server only
npm test	Run all tests (server must be running)
npm run test:api	API tests only
npm run test:ui	UI / Playwright tests only
npm run test:security	Security header + injection tests only
npm run typecheck	TypeScript type checking

---

🔌 Using As a Template

This framework is built to be reusable. To point it at a real payment API:

1. Update config/environments.ts with your API's base URL
2. Update src/fixtures/users.ts with your test user credentials
3. Update src/fixtures/cards.ts with your gateway's test card numbers
4. Adjust src/tests/api/card-data.test.ts to match your API's response shape
5. Update mock-server/public/index.html if targeting a different UI

The test helpers (card-helper.ts, token-helper.ts) are API-agnostic and require no changes.

---

📚 Documentation

Document	Description
docs/PCI-DSS-REQUIREMENTS.md	All 12 requirements explained — what they are, why they exist, whether they're automatable
docs/API-DOCUMENTATION.md	Full API reference with request/response examples, error codes, test users, and test cards
docs/UI-FIELDS-REFERENCE.md	Payment form field guide — PCI compliance properties, browser behaviour, and test coverage map

---

🛠️ Tech Stack

Tool	Version	Purpose
TypeScript	5.4	Type-safe codebase
Jest	29	Test runner and assertion library
Playwright	1.44	Browser automation (Chromium)
Supertest	7	HTTP API testing
Axios	1.6	API client helper
Express	4.19	Mock payment server
Helmet	7	Security headers middleware
express-rate-limit	7	Rate limiting (PCI Req 8 / 6)
jsonwebtoken	9	JWT generation and verification
jest-html-reporters	3.1	HTML test report generation

No Docker. No database. No cloud accounts. Just npm install and go.

---

🤝 Contributing

Contributions welcome. If you're adding tests, please:

1. Map every new test to a specific PCI-DSS requirement using the [REQ-X.X] comment format
2. Add both positive (secure) and negative (insecure/violation) test cases where applicable
3. Update docs/PCI-DSS-REQUIREMENTS.md if adding coverage for a new requirement area

---

📄 License

MIT — free to use, fork, and adapt for commercial or personal projects.

---

Built as a portfolio project demonstrating PCI-DSS QA automation expertise.
Suitable for freelance proposals, security QA roles, and as a reusable template.