my2/tests/README.md

Testing Guide

Overview

This document describes how to run tests for my.experimenta.science and how to use test credentials.

---

Test Credentials

Test credentials are stored in environment variables to keep them out of the codebase while making them accessible for automated tests.

📖 For complete credentials and testing guide, see: docs/TESTING.md

Setup

1. Copy .env.example to .env:

   cp .env.example .env
   

2. Set test credentials in .env:

   See docs/TESTING.md for current test credentials.

   TEST_USER_EMAIL=<see-docs-TESTING-md>
   TEST_USER_PASSWORD=<see-docs-TESTING-md>
   

3. Verify configuration:

   # Start dev server
   pnpm dev
   
   # In another terminal, test the credentials endpoint
   curl http://localhost:3000/api/test/credentials
   

   Expected output:

   {
     "email": "bm@noxware.de",
     "password": "%654321qQ!"
   }
   

---

Using Test Credentials in Tests

Method 1: Via API Endpoint (Recommended for E2E tests)

// tests/e2e/example.spec.ts
import { test, expect } from '@playwright/test'

test('login flow', async ({ page }) => {
  // Fetch test credentials from API
  const response = await fetch('http://localhost:3000/api/test/credentials')

  if (!response.ok) {
    test.skip() // Skip if credentials not configured
    return
  }

  const { email, password } = await response.json()

  // Use credentials in test
  await page.goto('/auth')
  await page.fill('input[type="email"]', email)
  await page.fill('input[type="password"]', password)
  await page.click('button[type="submit"]')

  // Assert login success
  await expect(page).toHaveURL('/')
})

Method 2: Via Server Utility (For server-side tests)

// tests/unit/auth.test.ts
import { describe, it, expect } from 'vitest'
import { getTestCredentials } from '~/server/utils/test-helpers'

describe('Authentication', () => {
  it('should login with test credentials', async () => {
    const { email, password } = getTestCredentials()

    // Use credentials in test
    const response = await $fetch('/api/auth/login', {
      method: 'POST',
      body: { email, password },
    })

    expect(response.success).toBe(true)
  })
})

Method 3: Via Environment Variables (Direct access)

// For tests that need direct access
const email = process.env.TEST_USER_EMAIL
const password = process.env.TEST_USER_PASSWORD

if (!email || !password) {
  console.warn('Test credentials not configured, skipping test')
  return
}

---

Security Notes

⚠️ Important Security Considerations

1. Development Only:

   • Test credentials should ONLY be used in development/staging
   • The /api/test/credentials endpoint returns 404 in production
   • Never commit real credentials to Git

2. Environment Variables:

   • .env is in .gitignore and never committed
   • .env.example contains example/documentation only (not real passwords)
   • Each developer should create their own .env file locally

3. Production Safety:

   • The test credentials endpoint is automatically disabled in production
   • Server utility warns if used in production environment
   • Test files are excluded from production builds

4. Credential Rotation:

   • Test credentials can be changed at any time in .env
   • All tests will automatically use the updated credentials
   • No code changes required when credentials change

---

Running Tests

Unit Tests (Vitest)

# Run all unit tests
pnpm test

# Run with coverage
pnpm test:coverage

# Watch mode
pnpm test:watch

E2E Tests (Playwright)

# Run all E2E tests
pnpm test:e2e

# Run specific test file
pnpm test:e2e tests/e2e/auth-login.example.spec.ts

# Run in UI mode (visual debugger)
pnpm test:e2e --ui

# Run in headed mode (see browser)
pnpm test:e2e --headed

Before Running Tests

1. ✅ Ensure .env is configured with test credentials
2. ✅ Start the dev server: pnpm dev
3. ✅ Start database: docker-compose up -d (if using Docker)
4. ✅ Run migrations: pnpm db:migrate

---

Test Structure

tests/
├── README.md                          # This file
├── e2e/                              # End-to-end tests (Playwright)
│   └── auth-login.example.spec.ts    # Example E2E test with credentials
└── unit/                             # Unit tests (Vitest)
    └── (to be added)

---

Example Tests

See tests/e2e/auth-login.example.spec.ts for a complete example of using test credentials in E2E tests.

---

Troubleshooting

"Test credentials not configured" Error

Cause: TEST_USER_EMAIL or TEST_USER_PASSWORD not set in .env

Solution:

# 1. Check if .env exists
ls -la .env

# 2. If not, copy from example
cp .env.example .env

# 3. Edit .env and set credentials
# TEST_USER_EMAIL=bm@noxware.de
# TEST_USER_PASSWORD=%654321qQ!

# 4. Restart dev server

API Endpoint Returns 404

Cause: Server is running in production mode

Solution: Test credentials endpoint is only available in development. Set:

NODE_ENV=development

Tests Fail with "Invalid Credentials"

Possible causes:

1. Wrong credentials in .env
2. Test user doesn't exist in Cidaas
3. Cidaas staging environment is down

Solution:

• Verify credentials work manually by logging in at /auth
• Check Cidaas staging status
• Contact team lead for valid test account

---

Best Practices

1. Always check if credentials are configured:

   if (!response.ok) {
     test.skip() // Don't fail, just skip
     return
   }
   

2. Use the API endpoint for E2E tests:

   • Cleaner separation of concerns
   • Easier to mock/stub in CI/CD
   • Works across different test frameworks

3. Clean up test data:

   test.afterEach(async () => {
     // Logout after each test
     await $fetch('/api/auth/logout', { method: 'POST' })
   })
   

4. Isolate tests:

   • Each test should be independent
   • Don't rely on state from previous tests
   • Use test.beforeEach to reset state

---

CI/CD Integration

For GitLab CI/CD, add test credentials as environment variables:

# .gitlab-ci.yml
test:
  stage: test
  variables:
    TEST_USER_EMAIL: $CI_TEST_USER_EMAIL  # Set in GitLab CI/CD settings
    TEST_USER_PASSWORD: $CI_TEST_USER_PASSWORD
  script:
    - pnpm install
    - pnpm test
    - pnpm test:e2e

Set CI_TEST_USER_EMAIL and CI_TEST_USER_PASSWORD as protected variables in: GitLab → Settings → CI/CD → Variables

---

Questions?

• Check CLAUDE.md for authentication patterns
• Check docs/CIDAAS_INTEGRATION.md for Cidaas setup
• Ask in team chat or create an issue