external-services-automation/README.md

External services automation library for Playwright and Cucumber

# External Services Automation Library

A TypeScript library for test automation with Playwright, focused on integrations with external services like Kinde (authentication) and Stripe (payments).

## Installation

Install the package via npm:

```bash
npm install external-services-automation
```

## Setup

### Configure Your Test Framework

The library can be used with any test framework. Here's an example for Playwright:

```typescript
// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  use: {
    baseURL: process.env.BASE_URL || 'https://your-app.com',
  },
});
```

## Usage

### Import Components

```typescript
import { 
  ExternalServicesWorld,
  LoginPage,
  RegisterPage,
  KindeAuthService,
  StripeService,
  GuerrillaMailClient
} from 'external-services-automation';
```

### Use Services and Page Objects

```typescript
// Authentication with Kinde
const authService = new KindeAuthService();
await authService.login(email, password);

// Payment processing with Stripe
const stripeService = new StripeService();
await stripeService.upgradeSubscription(planType);

// Page interactions
const loginPage = new LoginPage(page);
await loginPage.fillCredentials(email, password);
```

## Available Components

### Services

#### KindeAuthService
- `login(email: string, password: string)` - Authenticates user with Kinde
- `register(email: string, firstName: string, lastName: string)` - Creates new account
- `verifyEmail(code: string)` - Verifies email with confirmation code

#### StripeService
- `upgradeSubscription(planType: string)` - Upgrades subscription to specified plan
- `updatePaymentMethod(cardDetails: object)` - Updates payment method
- `getCurrentSubscription()` - Retrieves current subscription details

### Page Objects

#### Kinde Pages
- **LoginPage** - Handles login form interactions
- **RegisterPage** - Manages account registration
- **ConfirmCodePage** - Email verification code entry
- **PasswordSetupPage** - Password creation and setup

#### Stripe Pages
- **CurrentSubscriptionPage** - Displays current subscription details
- **UpdateSubscriptionPage** - Subscription plan selection
- **UpdatePaymentMethodPage** - Payment method management
- **ConfirmUpdatePage** - Confirmation dialogs
- **LeftPanelPage** - Navigation and sidebar interactions

### Utilities
- **GuerrillaMailClient** - Temporary email handling for account verification
  - `createTempEmail()` - Creates temporary email address
  - `getVerificationCode()` - Retrieves verification emails
  - `cleanup()` - Cleans up temporary email resources

### World Extension
- **ExternalServicesWorld** - Shared state management for test scenarios

## Example Implementation

```typescript
// In your test files
import { test, expect } from '@playwright/test';
import { KindeAuthService, StripeService, GuerrillaMailClient } from 'external-services-automation';

test.describe('External Services Integration', () => {
  let authService: KindeAuthService;
  let stripeService: StripeService;
  let tempEmail: GuerrillaMailClient;

  test.beforeEach(async () => {
    authService = new KindeAuthService();
    stripeService = new StripeService();
  });

  test('should create account and upgrade subscription', async () => {
    // Create temporary email for account verification
    tempEmail = new GuerrillaMailClient();
    const email = await tempEmail.createTempEmail();
    
    // Register new account
    await authService.register(email, 'John', 'Doe');
    
    // Verify email
    const verificationCode = await tempEmail.getVerificationCode();
    await authService.verifyEmail(verificationCode);
    
    // Upgrade subscription
    await stripeService.upgradeSubscription('premium');
    
    // Verify subscription status
    const subscription = await stripeService.getCurrentSubscription();
    expect(subscription.status).toBe('active');
    
    // Cleanup
    await tempEmail.cleanup();
  });

  test('should handle login with existing account', async () => {
    const result = await authService.login('user@example.com', 'password123');
    expect(result.success).toBe(true);
  });
});
```

## Updates

To update to the latest version:

```bash
npm update external-services-automation
```

## CI/CD

### Bitbucket Pipelines

```yaml
script:
  - npm install
  - npm test
```

## Dependencies

The library requires the following peer dependencies to be installed in your project:

```bash
npm install @playwright/test axios-cookiejar-support dotenv tough-cookie
```

Version requirements:
- `@playwright/test` ^1.40.0
- `axios-cookiejar-support` ^6.0.2
- `dotenv` ^16.4.5
- `tough-cookie` ^5.1.2

## Troubleshooting

### Package Not Found
```bash
npm install external-services-automation
```

### Import Errors
Make sure you're importing from the correct package name:
```typescript
import { KindeAuthService } from 'external-services-automation';
```

### Missing Peer Dependencies
```bash
npm install @playwright/test axios-cookiejar-support dotenv tough-cookie
```

## Development

For contributors working on this library:

```bash
git clone https://bitbucket.org/connectist/external-services-automation.git
cd external-services-automation
npm install
npm run build
```

## Links

- **NPM Package**: https://www.npmjs.com/package/external-services-automation
- **Repository**: https://bitbucket.org/connectist/external-services-automation