Test Identity

One of Spekra's core features is the ability to track tests over time, even as they're renamed, moved, or refactored. This is essential for maintaining accurate historical metrics.

The Challenge

Consider this test:

// tests/auth/login.spec.ts
describe('Authentication', () => {
  it('should allow user to log in', async () => {
    // ...
  });
});

If you rename it:

// tests/auth/login.spec.ts
describe('Auth', () => {
  it('allows user login', async () => {
    // ...
  });
});

Without test identity tracking, Spekra would see this as two different tests: one that was deleted and one that's brand new. All the historical data would be lost.

How Spekra Identifies Tests

Spekra uses a composite identity based on multiple factors:

Primary Identifiers

1. Test file path - The location of the test file
2. Suite path - The hierarchy of describe blocks
3. Test title - The it or test name

These are combined to create a unique identifier:

tests/auth/login.spec.ts > Authentication > should allow user to log in

Secondary Identifiers

When primary identifiers change, Spekra uses additional signals to match tests:

• Code similarity - Comparing test body content
• Position in file - Order relative to other tests
• Tags and annotations - Consistent metadata

Handling Changes

Renaming Tests

When you rename a test title, Spekra will:

1. Detect the old test is "missing"
2. Detect a new test with similar characteristics
3. Link them together, preserving history

Moving Tests

When you move a test to a different file:

// Before: tests/auth/login.spec.ts
// After: tests/authentication/user-login.spec.ts

Spekra tracks this by comparing test content and structure. History is preserved.

Splitting Tests

If you split one test into multiple:

// Before
it('handles login flow', async () => {
  // login
  // logout
  // error handling
});

// After
it('logs in successfully', async () => { /* ... */ });
it('logs out successfully', async () => { /* ... */ });
it('handles login errors', async () => { /* ... */ });

The original test's history is associated with the most similar new test. The others start fresh.

Best Practices

Use Stable Test IDs

For critical tests, add a stable identifier using tags:

// Playwright
test('should process payment @test-id:PAY-001', async () => {
  // ...
});

// Jest
it('should process payment', () => {
  // ...
});
// Or use a custom annotation

Avoid Mass Renames

If you need to rename many tests at once (e.g., standardizing naming conventions), do it incrementally to help Spekra track changes accurately.

Keep Test Files Focused

Large test files with many tests are harder to track. Keep files focused on related functionality.

Viewing Identity History

In the Spekra dashboard, you can view a test's identity history:

1. Navigate to any test in the Flaky Tests view
2. Click on the test name to open details
3. View the "History" tab to see identity changes

This shows:

• Previous names and locations
• When changes were detected
• Confidence level of matches

Limitations

Test identity tracking has some limitations:

• Completely rewritten tests - If both the name and content change significantly, they may not be linked
• Duplicate tests - Tests with identical names in the same file may be confused
• Very new tests - Tests need at least 2-3 runs to build identity confidence

Next Steps

• Flaky tests - Understanding flaky test detection
• Stability metrics - How metrics use identity data
• Test runs view - Viewing test results in the platform