cosmos-explorer/test/E2E-SETUP.md

# E2E Testing Setup for Cosmos DB Explorer

This document describes the pre-flight setup process for running end-to-end tests in the Cosmos DB Explorer project.

## Overview

The testing setup includes:
1. Azure CLI authentication
2. Subscription selection
3. Test account configuration
4. Token generation for NoSQL container operations
5. Browser storage state setup for Playwright

## Prerequisites

Before running tests, ensure you have:

- [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) installed and updated
- PowerShell execution policy set to allow script execution
- Access to the Azure subscription: `074d02eb-4d74-486a-b299-b262264d1536`
- Access to the resource group: `bchoudhury-e2e-testing`
- Required Azure resources with prefix: `bchoudhury-e2e-`

## Automatic Setup (Recommended)

The setup runs automatically when you start Playwright tests:

```bash
npm run test:e2e
```

or

```bash
npx playwright test
```

The global setup script (`test/global-setup.ts`) will:
1. Check if you're logged in to Azure CLI
2. If not logged in, prompt for authentication
3. Set the correct subscription
4. Run the PowerShell configuration script
5. Generate required access tokens
6. Set up browser authentication state

## Manual Setup

If you need to run the setup independently:

```bash
npm run test:e2e:setup
```

or directly:

```bash
node setup-tests.js
```

## Manual Step-by-Step Setup

If you prefer to run each step manually:

### 1. Azure CLI Login
```bash
az login --scope https://management.core.windows.net//.default
```

### 2. Set Subscription
```bash
az account set --subscription "074d02eb-4d74-486a-b299-b262264d1536"
```

### 3. Configure Test Accounts
```powershell
.\test\scripts\set-test-accounts.ps1 -ResourceGroup "bchoudhury-e2e-testing" -Subscription "074d02eb-4d74-486a-b299-b262264d1536" -ResourcePrefix "bchoudhury-e2e-"
```

### 4. Set NoSQL Container Token
```bash
$ENV:NOSQL_CONTAINERCOPY_TESTACCOUNT_TOKEN=$(az account get-access-token --scope "https://bchoudhury-e2e-sqlcontainercopyonly.documents.azure.com/.default" -o tsv --query accessToken)
```

## Environment Variables

The setup process configures these environment variables:

- `DE_TEST_RESOURCE_GROUP`: The Azure resource group for testing
- `DE_TEST_SUBSCRIPTION_ID`: The Azure subscription ID
- `DE_TEST_ACCOUNT_PREFIX`: The prefix used for test resources
- `NOSQL_CONTAINERCOPY_TESTACCOUNT_TOKEN`: Access token for NoSQL operations

## Storage State

Browser authentication state is saved to:
```
playwright/.auth/user.json
```

This file is automatically generated and excluded from version control.

## Troubleshooting

### Common Issues

1. **Azure CLI not found**
   - Install Azure CLI: https://docs.microsoft.com/en-us/cli/azure/install-azure-cli

2. **PowerShell execution policy error**
   ```powershell
   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
   ```

3. **Authentication expired**
   ```bash
   az logout
   az login --scope https://management.core.windows.net//.default
   ```

4. **Resource not found**
   - Verify you have access to the subscription and resource group
   - Check that resources exist with the expected prefix

### Debug Mode

For verbose output during setup, you can run:

```bash
DEBUG=1 npm run test:e2e:setup
```

## File Structure

```
test/
├── global-setup.ts          # Main global setup script
├── scripts/
│   ├── set-test-accounts.ps1 # PowerShell test account setup
│   ├── check-test-accounts.ps1
│   └── clean-test-accounts.ps1
└── ...

playwright/
└── .auth/
    └── user.json            # Browser storage state (generated)

setup-tests.js               # Manual setup runner
playwright.config.ts         # Playwright config with global setup
```

## Configuration

The setup is configured in:
- `playwright.config.ts`: Playwright configuration with global setup
- `test/global-setup.ts`: Main setup logic
- `setup-tests.js`: Manual setup runner

## Notes

- The setup only needs to run once per session
- Browser storage state persists between test runs
- Azure tokens are refreshed automatically by the Azure CLI
- The setup is idempotent - safe to run multiple times