TAEssentials.API.TSPlaywright

A comprehensive TypeScript-based API testing framework built with Playwright, designed for testing the LittleBugShop API with professional-grade test organization, reporting, and maintainability.

🎯 Overview

This project demonstrates enterprise-level API testing practices using TypeScript and Playwright Test, featuring:

• Structured test organization by authorization levels (admin, regular user, unauthorized)
• Factory pattern for test data generation with Faker.js
• Fluent URL builder for endpoint construction
• Comprehensive test reporting with Allure integration
• Type-safe utilities for API interactions and response validation
• Self-documenting tests with meaningful assertions and step-by-step reporting

🏗️ Architecture

TAEssentials.API.TSPlaywright/
├── tests/
│ └── api/
│ ├── admin/ # Admin-level operation tests
│ ├── regular/ # Regular user authorization tests
│ └── unauthorized/ # Unauthenticated/public endpoint tests
├── utils/
│ ├── factories/ # Test data generators (ProductFactory, UserFactory)
│ ├── urlBuilders/ # Fluent API for endpoint URLs
│ ├── apiClient.ts # HTTP client wrapper
│ ├── logger.ts # Winston-based logging
│ ├── responseValidator.ts # Response validation utilities
│ └── testDecorators.ts # Unified test metadata for Playwright + Allure
├── models/ # TypeScript interfaces for requests/responses
└── config/ # Configuration files

✨ Features

Test Organization

• Role-based directory structure: Separate test suites for admin, regular users, and unauthenticated scenarios
• Test case naming convention: TC ###P for positive tests, TC ###N for negative tests
• Minimal redundancy: Authorization tests focus on access control, not data validation

Factory Pattern

// Generate realistic test dataconstproduct=ProductFactory.generateProduct();constinvalidProduct=ProductFactory.generateProductWithNegativePrice();constuser=UserFactory.generateUser();

URL Builder

// Fluent, type-safe endpoint constructionawaitapiClient.post(LittleBugShop().Controllers.Products.create,{ data });awaitapiClient.post(LittleBugShop().Controllers.Users.register,{ data });

Test Decorators

// Unified metadata for Playwright and AllureTestDecorators.setupTestDescribe({suite: 'Product Management API Tests',epic: 'Product Management',feature: 'Product Creation'});awaitTestDecorators.setupTest({description: 'Validate successful product creation',owner: 'Farum',severity: Severity.CRITICAL});

Meaningful Assertions

Every assertion includes a descriptive error message:

expect(response.status(),'Product creation should return 201 Created status').toBe(201);expect(result.id,'Product ID should be a positive number').toBeGreaterThan(0);expect(response.status(),'Regular user should be forbidden from creating products (403 Forbidden)').toBe(403);

🛠️ Tech Stack

• TypeScript 5.3.0: Type-safe test development
• Playwright Test 1.40.0: Modern API testing framework
• Faker.js 10.1.0: Realistic test data generation
• Allure 2.10.0: Rich test reporting
• Winston 3.11.0: Structured logging
• date-fns 2.30.0: Date formatting utilities

🔧 Prerequisites

• Node.js (v18 or higher recommended)
• npm or yarn
• LittleBugShop API running on http://localhost:5052

📦 Installation

# Clone the repository
git clone https://github.com/farum12/TAEssentials.API.TSPlaywright.git
cd TAEssentials.API.TSPlaywright
# Install dependencies
npm install

🧪 Running Tests

# Run all tests
npx playwright test# Run tests in UI mode
npx playwright test --ui
# Run specific test suite
npx playwright test tests/api/admin/
# Run tests with specific tag
npx playwright test --grep @critical
# Generate Allure report
npm run report:generate
npm run report:open

📊 Test Coverage

Product Management API

• Admin Tests (tests/api/admin/productPostAdmin.spec.ts):

  • ✅ TC 001P: Successful product creation with valid data
  • ✅ TC 002P: Product creation with minimal required fields
  • ❌ TC 003N: Rejection of invalid data (empty name)
  • ❌ TC 004N: Rejection of negative price
  • ❌ TC 005N: Rejection of zero price
  • ❌ TC 006N: Invalid ISBN format handling
  • ❌ TC 007N: Rejection of empty fields
  • ✅ TC 008P: Response structure validation

• Authorization Tests (tests/api/regular/productPostRegular.spec.ts):

  • ❌ TC 001N: Regular user forbidden from creating products (403)

• Authentication Tests (tests/api/unauthorized/productPostUnauthorized.spec.ts):

  • ❌ TC 001N: Unauthenticated requests rejected (401)

User Management API

• User Registration (tests/api/unauthorized/userRegisterPostUnauthorized.spec.ts):
  • ✅ TC 001P: Successful registration with valid data
  • ✅ TC 002P: Registration without optional fields
  • ❌ TC 003N: Duplicate username rejection
  • ❌ TC 004N: Duplicate email rejection
  • ❌ TC 005N: Required field validation (username)
  • ❌ TC 006N: Required field validation (password)
  • ❌ TC 007N: Required field validation (email)
  • ❌ TC 008N: Email format validation
  • ❌ TC 009N: Password strength requirements
  • ❌ TC 010N: Empty string values rejection
  • ❌ TC 011N: Special characters in username handling
  • ✅ TC 012P: Response structure validation

⚙️ Configuration

The framework is pre-configured for LittleBugShop API:

• Base URL: http://localhost:5052
• Admin Credentials: username: admin, password: admin123
• Regular User Credentials: username: User, password: qazwsxedcrfv12345

📖 Documentation

• TESTING_STANDARDS.md: Comprehensive guide to coding standards, naming conventions, and best practices

🎓 Best Practices Demonstrated

1. Self-Documenting Tests: Clear test names, descriptive step labels, and meaningful assertion messages
2. DRY Principle: Factory pattern eliminates hardcoded test data
3. Type Safety: Full TypeScript integration with interfaces and generics
4. Separation of Concerns: Utilities, factories, and tests are clearly separated
5. Test Organization: Role-based directory structure for scalability
6. Fail Fast, Fail Clear: Detailed error messages pinpoint exact failure reasons

🤝 Contributing

Contributions are welcome! Please follow the standards outlined in TESTING_STANDARDS.md to maintain consistency.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Follow the coding standards in TESTING_STANDARDS.md
4. Add tests with proper TC naming (TC ###P/TC ###N)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📝 License

This project is part of the Test Automation Essentials series.

👤 Author

Farum

• GitHub: @farum12

🙏 Acknowledgments

• Built for testing the LittleBugShop API
• Inspired by enterprise API testing best practices
• Powered by the Playwright Test framework

---

Note: Ensure the LittleBugShop API is running on http://localhost:5052 before executing tests.

See URL Builder Documentation for complete API reference.

UserFactory

Generate realistic user test data using Faker:

import{UserFactory}from'../../utils/userFactory';// Generate complete user with all fieldsconstuser=UserFactory.generateUser();// Generate user with only required fieldsconstminimalUser=UserFactory.generateMinimalUser();// Generate user with custom fieldsconstcustomUser=UserFactory.generateUser({
## 📖Documentation-**[TESTING_STANDARDS.md](TESTING_STANDARDS.md)**: Comprehensiveguidetocodingstandards,namingconventions,andbestpractices
## 🎓BestPracticesDemonstrated1.**Self-DocumentingTests**: Cleartestnames,descriptivesteplabels,andmeaningfulassertionmessages2.**DRYPrinciple**: Factorypatterneliminateshardcodedtestdata3.**TypeSafety**: FullTypeScriptintegrationwithinterfacesandgenerics4.**SeparationofConcerns**: Utilities, factories,andtestsareclearlyseparated5.**TestOrganization**: Role-baseddirectorystructureforscalability6.**FailFast,FailClear**: Detailederrormessagespinpointexactfailurereasons
## 🤝ContributingContributionsarewelcome!Pleasefollowthestandardsoutlinedin`TESTING_STANDARDS.md`tomaintainconsistency.1.Forktherepository2.Createafeaturebranch(`git checkout -b feature/amazing-feature`)3.Followthecodingstandardsin`TESTING_STANDARDS.md`4.AddtestswithproperTCnaming(TC ###P/TC ###N)5.Commityourchanges(`git commit -m 'Add amazing feature'`)6.Pushtothebranch(`git push origin feature/amazing-feature`)7.OpenaPullRequest
## 📝LicenseThisproject is partoftheTestAutomationEssentialsseries.
## 👤Author**Farum**-GitHub: [@farum12](https://github.com/farum12)
## 🙏Acknowledgments-BuiltfortestingtheLittleBugShopAPI-InspiredbyenterpriseAPItestingbestpractices-PoweredbythePlaywrightTestframework---**Note**: EnsuretheLittleBugShopAPI is runningon`http://localhost:5052`beforeexecutingtests.