Configuration Reference

Category: Configuration | Updated: 2026-02-02

Complete reference for triqual.config.ts configuration with all options, TypeScript types, and examples.

---

Overview

Triqual uses a TypeScript configuration file (triqual.config.ts) for type safety, IDE autocomplete, and environment variable support.

---

Basic Configuration

Minimal Setup

import { defineConfig } from 'triqual';

export default defineConfig({
  project_id: 'my-app',
  testDir: './tests',
  baseUrl: 'http://localhost:3000',
});

Generated by /init

Run /init to auto-generate configuration based on your project structure:

/init

Creates triqual.config.ts with detected settings:

• Finds test directory
• Detects authentication strategy
• Identifies pattern conventions
• Configures MCP servers

---

Configuration Schema

Required Fields

Optional Fields

---

Authentication Configuration

Strategy: storageState (Recommended)

Use when: App supports session storage (cookies, localStorage)

export default defineConfig({
  // ... required fields ...

  auth: {
    strategy: 'storageState',
    storageState: {
      path: '.auth/user.json',
    },
  },
});

Setup:

# Generate storage state
npx playwright test --headed
# Login manually, close browser
# Storage state saved to .auth/user.json

Usage in tests:

test.use({ storageState: '.auth/user.json' });

Strategy: uiLogin

Use when: Need to login via UI for each test

export default defineConfig({
  auth: {
    strategy: 'uiLogin',
    credentials: {
      username: process.env.TEST_USERNAME || '',
      password: process.env.TEST_PASSWORD || '',
    },
    loginUrl: '/login',
    selectors: {
      username: 'data-testid=username-input',
      password: 'data-testid=password-input',
      submit: 'data-testid=login-submit',
    },
  },
});

Environment variables:

# .env
TEST_USERNAME=test@example.com
TEST_PASSWORD=secure_password

Strategy: setupProject

Use when: Complex auth requiring dedicated setup project

export default defineConfig({
  auth: {
    strategy: 'setupProject',
    setupScript: './tests/setup/auth.setup.ts',
  },
});

Setup script:

// tests/setup/auth.setup.ts
import { test as setup } from '@playwright/test';

setup('authenticate', async ({ page }) => {
  await page.goto('/login');
  await page.getByTestId('username-input').fill('test@example.com');
  await page.getByTestId('password-input').fill('password');
  await page.getByTestId('login-submit').click();

  await page.context().storageState({ path: '.auth/user.json' });
});

Playwright config:

export default defineConfig({
  projects: [
    { name: 'setup', testMatch: /auth\.setup\.ts/ },
    {
      name: 'chromium',
      use: { storageState: '.auth/user.json' },
      dependencies: ['setup'],
    },
  ],
});

Strategy: none

Use when: No authentication required (public pages)

export default defineConfig({
  auth: {
    strategy: 'none',
  },
});

---

Patterns Configuration

Selector Strategy

data-testid (Recommended):

export default defineConfig({
  patterns: {
    selectors: 'data-testid',
  },
});

Generates:

await page.getByTestId('login-button').click();

role:

export default defineConfig({
  patterns: {
    selectors: 'role',
  },
});

Generates:

await page.getByRole('button', { name: 'Login' }).click();

text:

export default defineConfig({
  patterns: {
    selectors: 'text',
  },
});

Generates:

await page.getByText('Login').click();

css:

export default defineConfig({
  patterns: {
    selectors: 'css',
  },
});

Generates:

await page.locator('.login-button').click();

Wait Strategy

networkidle (Recommended for SPAs):

export default defineConfig({
  patterns: {
    waitStrategy: 'networkidle',
  },
});

Generates:

await page.goto('/dashboard', { waitUntil: 'networkidle' });

domcontentloaded (Faster):

export default defineConfig({
  patterns: {
    waitStrategy: 'domcontentloaded',
  },
});

load:

export default defineConfig({
  patterns: {
    waitStrategy: 'load',
  },
});

---

MCP Configuration

Enable/Disable MCP Servers

export default defineConfig({
  mcp: {
    quoth: {
      enabled: true, // Pattern documentation
    },
    exolar: {
      enabled: true, // Test analytics
      projectId: 'my-app-exolar-id', // Optional
    },
  },
});

Disable All MCP

export default defineConfig({
  mcp: {
    quoth: { enabled: false },
    exolar: { enabled: false },
  },
});

Effect: Triqual works without external pattern/analytics, uses only local knowledge.md

---

Environment Variables

Using .env Files

import { defineConfig } from 'triqual';
import * as dotenv from 'dotenv';

dotenv.config();

export default defineConfig({
  project_id: process.env.PROJECT_ID || 'default',
  baseUrl: process.env.BASE_URL || 'http://localhost:3000',

  auth: {
    strategy: 'uiLogin',
    credentials: {
      username: process.env.TEST_USERNAME || '',
      password: process.env.TEST_PASSWORD || '',
    },
  },
});

.env:

PROJECT_ID=my-app-staging
BASE_URL=https://staging.example.com
TEST_USERNAME=test@example.com
TEST_PASSWORD=secure_password

Per-Environment Configs

// triqual.config.ts
import { defineConfig } from 'triqual';

const isDev = process.env.NODE_ENV === 'development';
const isCI = process.env.CI === 'true';

export default defineConfig({
  project_id: 'my-app',
  testDir: './tests',
  baseUrl: isDev
    ? 'http://localhost:3000'
    : isCI
    ? 'https://staging.example.com'
    : 'https://production.example.com',

  auth: {
    strategy: isCI ? 'storageState' : 'uiLogin',
    storageState: isCI ? { path: '.auth/ci-user.json' } : undefined,
  },
});

---

Import External Credentials

Separate Credentials File

// credentials.ts (gitignored)
export const credentials = {
  username: 'test@example.com',
  password: 'secure_password',
};

// triqual.config.ts
import { defineConfig } from 'triqual';
import { credentials } from './credentials';

export default defineConfig({
  project_id: 'my-app',
  testDir: './tests',
  baseUrl: 'http://localhost:3000',

  auth: {
    strategy: 'uiLogin',
    credentials,
  },
});

.gitignore:

credentials.ts
.env
.auth/

---

Complete Example

// triqual.config.ts
import { defineConfig } from 'triqual';
import * as dotenv from 'dotenv';

dotenv.config();

export default defineConfig({
  // Required
  project_id: process.env.PROJECT_ID || 'my-app',
  testDir: './automation/playwright/tests',
  baseUrl: process.env.BASE_URL || 'http://localhost:3000',

  // Authentication
  auth: {
    strategy: 'storageState',
    storageState: {
      path: '.auth/user.json',
    },
  },

  // Test Patterns
  patterns: {
    selectors: 'data-testid',
    waitStrategy: 'networkidle',
  },

  // MCP Configuration
  mcp: {
    quoth: {
      enabled: true,
    },
    exolar: {
      enabled: true,
      projectId: process.env.EXOLAR_PROJECT_ID,
    },
  },
});

---

TypeScript Types

Full Type Definitions

interface TriqualConfig {
  // Required
  project_id: string;
  testDir: string;
  baseUrl: string;

  // Optional
  auth?: AuthConfig;
  patterns?: PatternsConfig;
  mcp?: McpConfig;
}

interface AuthConfig {
  strategy: 'storageState' | 'uiLogin' | 'setupProject' | 'none';
  storageState?: {
    path: string;
  };
  credentials?: {
    username: string;
    password: string;
  };
  loginUrl?: string;
  selectors?: {
    username: string;
    password: string;
    submit: string;
  };
  setupScript?: string;
}

interface PatternsConfig {
  selectors?: 'data-testid' | 'role' | 'text' | 'css';
  waitStrategy?: 'networkidle' | 'domcontentloaded' | 'load';
}

interface McpConfig {
  quoth?: {
    enabled: boolean;
  };
  exolar?: {
    enabled: boolean;
    projectId?: string;
  };
}

IDE Autocomplete

TypeScript configuration provides IDE autocomplete:

import { defineConfig } from 'triqual';

export default defineConfig({
  project_id: 'my-app',
  testDir: './tests',
  baseUrl: 'http://localhost:3000',

  auth: {
    strategy: 'sto  // Autocomplete: storageState | uiLogin | setupProject | none

---

Validation

Config Validation

Triqual validates configuration on load:

/init

Valid config:

✅ Configuration valid

Invalid config:

❌ Configuration error: missing required field 'project_id'

Manual Validation

// test-config.ts
import config from './triqual.config';

console.log('Config:', config);
console.log('Valid:', config.project_id && config.testDir && config.baseUrl);

---

Related Documentation

• Installation - First-time setup
• Skills Reference - /init command
• Draft Folder - Test organization
• API Reference - TypeScript types

---

Next Steps: Run /init to generate configuration, or read Installation for setup guidance.