ChekovChekov

Best Practices

Learn how to write effective, maintainable, and reliable tests with Chekov.

Writing Clear Instructions

The quality of your test automation depends heavily on how well you communicate with Chekov's AI. Here are some guidelines for writing effective instructions:

1
// ❌ Unclear instructions
2
await ai('click it', { page });
3
await ai('type something', { page });
4


5
// ✅ Clear, specific instructions
6
await ai('Click the "Sign Up" button in the header', { page });
7
await ai('Type "test@example.com" in the email input field', { page });

Organizing Tests

Structure your tests logically and use descriptive names for better maintainability:

1
// tests/auth/login.spec.ts
2
import { test } from '@playwright/test';
3
import { ai } from '@chekov/core';
4


5
test.describe('Authentication', () => {
6
  test('successful login', async ({ page }) => {
7
    await page.goto('/login');
8
    
9
    await ai([
10
      'Type "user@example.com" in the email field',
11
      'Type "password123" in the password field',
12
      'Click the Login button'
13
    ], { page });
14
    
15
    await ai('Verify we are redirected to the dashboard', { page });
16
  });
17
  
18
  test('invalid credentials', async ({ page }) => {
19
    await page.goto('/login');
20
    
21
    await ai([
22
      'Type "invalid@example.com" in the email field',
23
      'Type "wrongpassword" in the password field',
24
      'Click the Login button'
25
    ], { page });
26
    
27
    await ai('Verify the error message "Invalid credentials" is shown', { page });
28
  });
29
});

Optimizing Performance

Parallel Actions

Use parallel execution for independent actions to speed up your tests:

1
test('parallel verifications', async ({ page }) => {
2
  await page.goto('/dashboard');
3
  
4
  // Run multiple checks in parallel
5
  await ai([
6
    'Verify the user profile section is visible',
7
    'Verify the sidebar navigation is present',
8
    'Verify the notifications panel exists',
9
    'Verify the search bar is accessible'
10
  ], {
11
    page,
12
    parallelism: 4  // Execute all checks simultaneously
13
  });
14
});

Reusable Functions

Create helper functions for common sequences of actions:

1
// helpers/auth.ts
2
export async function login(page, email: string, password: string) {
3
  await page.goto('/login');
4
  
5
  await ai([
6
    `Type "${email}" in the email field`,
7
    `Type "${password}" in the password field`,
8
    'Click the Login button'
9
  ], { page });
10
  
11
  await ai('Verify we are redirected to the dashboard', { page });
12
}
13


14
// tests/profile.spec.ts
15
test('update profile', async ({ page }) => {
16
  await login(page, 'user@example.com', 'password123');
17
  
18
  await ai([
19
    'Click the Profile Settings button',
20
    'Update the display name to "John Doe"',
21
    'Click Save Changes'
22
  ], { page });
23
});

Error Handling

Implement robust error handling to make your tests more reliable:

1
test('handle dynamic content', async ({ page }) => {
2
  await page.goto('/dashboard');
3
  
4
  try {
5
    // Try to dismiss any popups that might appear
6
    await ai('Click the "Accept Cookies" button if present', {
7
      page,
8
      timeout: 2000
9
    });
10
  } catch {
11
    // Continue if no popup found
12
  }
13
  
14
  try {
15
    await ai('Click the Settings button', { page });
16
  } catch (error) {
17
    console.error('Failed to access settings:', error);
18
    
19
    // Try an alternative approach
20
    await ai('Click the user menu', { page });
21
    await ai('Click Settings in the dropdown menu', { page });
22
  }
23
});

Test Data Management

Keep your test data organized and maintainable:

1
// fixtures/users.ts
2
export const testUsers = {
3
  admin: {
4
    email: 'admin@example.com',
5
    password: 'admin123',
6
    role: 'admin'
7
  },
8
  customer: {
9
    email: 'customer@example.com',
10
    password: 'customer123',
11
    role: 'customer'
12
  }
13
};
14


15
// tests/admin.spec.ts
16
import { testUsers } from '../fixtures/users';
17


18
test('admin features', async ({ page }) => {
19
  const { email, password } = testUsers.admin;
20
  await login(page, email, password);
21
  
22
  await ai([
23
    'Verify the Admin Dashboard is accessible',
24
    'Verify the User Management section is visible',
25
    'Verify the System Settings are available'
26
  ], { page });
27
});

Key Takeaways

  • Write clear, specific instructions for the AI
  • Organize tests logically and use descriptive names
  • Leverage parallel execution for better performance
  • Create reusable helper functions
  • Implement robust error handling
  • Manage test data effectively

Next Steps