diff --git a/docs/src/test-api/class-testoptions.md b/docs/src/test-api/class-testoptions.md
index 6d758201ac..0fba476d73 100644
--- a/docs/src/test-api/class-testoptions.md
+++ b/docs/src/test-api/class-testoptions.md
@@ -546,8 +546,8 @@ export default defineConfig({
 
 ## property: TestOptions.trace
 * since: v1.10
-- type: <[Object]|[TraceMode]<"off"|"on"|"retain-on-failure"|"on-first-retry"|"on-first-failure">>
-  - `mode` <[TraceMode]<"off"|"on"|"retain-on-failure"|"on-first-retry"|"on-all-retries"|"on-first-failure">> Trace recording mode.
+- type: <[Object]|[TraceMode]<"off"|"on"|"retain-on-failure"|"on-first-retry"|"retain-on-first-failure">>
+  - `mode` <[TraceMode]<"off"|"on"|"retain-on-failure"|"on-first-retry"|"on-all-retries"|"retain-on-first-failure">> Trace recording mode.
   - `attachments` ?<[boolean]> Whether to include test attachments. Defaults to true. Optional.
   - `screenshots` ?<[boolean]> Whether to capture screenshots during tracing. Screenshots are used to build a timeline preview. Defaults to true. Optional.
   - `snapshots` ?<[boolean]> Whether to capture DOM snapshot on every action. Defaults to true. Optional.
@@ -559,7 +559,7 @@ Whether to record trace for each test. Defaults to `'off'`.
 * `'retain-on-failure'`: Record trace for each test, but remove all traces from successful test runs.
 * `'on-first-retry'`: Record trace only when retrying a test for the first time.
 * `'on-all-retries'`: Record traces only when retrying for all retries.
-* `'on-first-failure'`: Record traces only when the test fails for the first time.
+* `'retain-on-first-failure'`: Record traces only when the test fails for the first time.
 
 For more control, pass an object that specifies `mode` and trace features to enable.
 
diff --git a/packages/playwright/src/program.ts b/packages/playwright/src/program.ts
index 9be1bbfe74..c204932da2 100644
--- a/packages/playwright/src/program.ts
+++ b/packages/playwright/src/program.ts
@@ -289,7 +289,7 @@ function resolveReporter(id: string) {
   return require.resolve(id, { paths: [process.cwd()] });
 }
 
-const kTraceModes: TraceMode[] = ['on', 'off', 'on-first-retry', 'on-all-retries', 'retain-on-failure', 'on-first-failure'];
+const kTraceModes: TraceMode[] = ['on', 'off', 'on-first-retry', 'on-all-retries', 'retain-on-failure', 'retain-on-first-failure'];
 
 const testOptions: [string, string][] = [
   ['--browser <browser>', `Browser to use for tests, one of "all", "chromium", "firefox" or "webkit" (default: "chromium")`],
diff --git a/packages/playwright/src/worker/testTracing.ts b/packages/playwright/src/worker/testTracing.ts
index 80949da792..bdd73369a3 100644
--- a/packages/playwright/src/worker/testTracing.ts
+++ b/packages/playwright/src/worker/testTracing.ts
@@ -54,7 +54,7 @@ export class TestTracing {
     if (this._options?.mode === 'retain-on-failure') capture = true;
     if (this._options?.mode === 'on-first-retry' && this._testInfo.retry === 1) capture = true;
     if (this._options?.mode === 'on-all-retries' && this._testInfo.retry > 0) capture = true;
-    if (this._options?.mode === 'on-first-failure' && this._testInfo.retry === 0) capture = true;
+    if (this._options?.mode === 'retain-on-first-failure' && this._testInfo.retry === 0) capture = true;
 
     return capture && !process.env.PW_TEST_DISABLE_TRACING;
   }
@@ -120,7 +120,7 @@ export class TestTracing {
       return;
 
     const testFailed = this._testInfo.status !== this._testInfo.expectedStatus;
-    const shouldAbandonTrace = !testFailed && (this._options.mode === 'retain-on-failure' || this._options.mode === 'on-first-failure');
+    const shouldAbandonTrace = !testFailed && (this._options.mode === 'retain-on-failure' || this._options.mode === 'retain-on-first-failure');
 
     if (shouldAbandonTrace) {
       for (const file of this._temporaryTraceFiles)
diff --git a/packages/playwright/types/test.d.ts b/packages/playwright/types/test.d.ts
index 477191564a..cc46e14f50 100644
--- a/packages/playwright/types/test.d.ts
+++ b/packages/playwright/types/test.d.ts
@@ -5637,7 +5637,7 @@ export interface PlaywrightWorkerOptions {
 }
 
 export type ScreenshotMode = 'off' | 'on' | 'only-on-failure';
-export type TraceMode = 'off' | 'on' | 'retain-on-failure' | 'on-first-retry' | 'on-all-retries' | 'on-first-failure';
+export type TraceMode = 'off' | 'on' | 'retain-on-failure' | 'on-first-retry' | 'on-all-retries' | 'retain-on-first-failure';
 export type VideoMode = 'off' | 'on' | 'retain-on-failure' | 'on-first-retry';
 
 /**
diff --git a/tests/page/pageTestApi.ts b/tests/page/pageTestApi.ts
index 53efd741ad..15eb8fffca 100644
--- a/tests/page/pageTestApi.ts
+++ b/tests/page/pageTestApi.ts
@@ -27,7 +27,7 @@ export type PageWorkerFixtures = {
   headless: boolean;
   channel: string;
   screenshot: ScreenshotMode | { mode: ScreenshotMode } & Pick<PageScreenshotOptions, 'fullPage' | 'omitBackground'>;
-  trace: 'off' | 'on' | 'retain-on-failure' | 'on-first-retry' | 'on-first-failure' | 'on-all-retries' | /** deprecated */ 'retry-with-trace';
+  trace: 'off' | 'on' | 'retain-on-failure' | 'on-first-retry' | 'retain-on-first-failure' | 'on-all-retries' | /** deprecated */ 'retry-with-trace';
   video: VideoMode | { mode: VideoMode, size: ViewportSize };
   browserName: 'chromium' | 'firefox' | 'webkit';
   browserVersion: string;
diff --git a/tests/playwright-test/playwright.artifacts.spec.ts b/tests/playwright-test/playwright.artifacts.spec.ts
index 561f58ed5a..709c027a9a 100644
--- a/tests/playwright-test/playwright.artifacts.spec.ts
+++ b/tests/playwright-test/playwright.artifacts.spec.ts
@@ -338,11 +338,11 @@ test('should work with trace: on-all-retries', async ({ runInlineTest }, testInf
   ]);
 });
 
-test('should work with trace: on-first-failure', async ({ runInlineTest }, testInfo) => {
+test('should work with trace: retain-on-first-failure', async ({ runInlineTest }, testInfo) => {
   const result = await runInlineTest({
     ...testFiles,
     'playwright.config.ts': `
-      module.exports = { use: { trace: 'on-first-failure' } };
+      module.exports = { use: { trace: 'retain-on-first-failure' } };
     `,
   }, { workers: 1, retries: 2 });
 
diff --git a/tests/playwright-test/playwright.trace.spec.ts b/tests/playwright-test/playwright.trace.spec.ts
index 27e6884962..1c74e39599 100644
--- a/tests/playwright-test/playwright.trace.spec.ts
+++ b/tests/playwright-test/playwright.trace.spec.ts
@@ -401,7 +401,7 @@ test('should respect PW_TEST_DISABLE_TRACING', async ({ runInlineTest }, testInf
   expect(fs.existsSync(testInfo.outputPath('test-results', 'a-test-1', 'trace.zip'))).toBe(false);
 });
 
-for (const mode of ['off', 'retain-on-failure', 'on-first-retry', 'on-all-retries', 'on-first-failure']) {
+for (const mode of ['off', 'retain-on-failure', 'on-first-retry', 'on-all-retries', 'retain-on-first-failure']) {
   test(`trace:${mode} should not create trace zip artifact if page test passed`, async ({ runInlineTest }) => {
     const result = await runInlineTest({
       'a.spec.ts': `
@@ -1034,7 +1034,7 @@ test('should attribute worker fixture teardown to the right test', async ({ runI
   ]);
 });
 
-test('trace:on-first-failure should create trace but only on first failure', async ({ runInlineTest }) => {
+test('trace:retain-on-first-failure should create trace but only on first failure', async ({ runInlineTest }) => {
   const result = await runInlineTest({
     'a.spec.ts': `
       import { test, expect } from '@playwright/test';
@@ -1043,7 +1043,7 @@ test('trace:on-first-failure should create trace but only on first failure', asy
         expect(true).toBe(false);
       });
     `,
-  }, { trace: 'on-first-failure', retries: 1 });
+  }, { trace: 'retain-on-first-failure', retries: 1 });
 
   const retryTracePath = test.info().outputPath('test-results', 'a-fail-retry1', 'trace.zip');
   const retryTraceExists = fs.existsSync(retryTracePath);
@@ -1055,7 +1055,7 @@ test('trace:on-first-failure should create trace but only on first failure', asy
   expect(result.failed).toBe(1);
 });
 
-test('trace:on-first-failure should create trace if context is closed before failure in the test', async ({ runInlineTest }) => {
+test('trace:retain-on-first-failure should create trace if context is closed before failure in the test', async ({ runInlineTest }) => {
   const result = await runInlineTest({
     'a.spec.ts': `
       import { test, expect } from '@playwright/test';
@@ -1065,14 +1065,14 @@ test('trace:on-first-failure should create trace if context is closed before fai
         expect(1).toBe(2);
       });
     `,
-  }, { trace: 'on-first-failure' });
+  }, { trace: 'retain-on-first-failure' });
   const tracePath = test.info().outputPath('test-results', 'a-fail', 'trace.zip');
   const trace = await parseTrace(tracePath);
   expect(trace.apiNames).toContain('page.goto');
   expect(result.failed).toBe(1);
 });
 
-test('trace:on-first-failure should create trace if context is closed before failure in afterEach', async ({ runInlineTest }) => {
+test('trace:retain-on-first-failure should create trace if context is closed before failure in afterEach', async ({ runInlineTest }) => {
   const result = await runInlineTest({
     'a.spec.ts': `
       import { test, expect } from '@playwright/test';
@@ -1084,14 +1084,14 @@ test('trace:on-first-failure should create trace if context is closed before fai
         expect(1).toBe(2);
       });
     `,
-  }, { trace: 'on-first-failure' });
+  }, { trace: 'retain-on-first-failure' });
   const tracePath = test.info().outputPath('test-results', 'a-fail', 'trace.zip');
   const trace = await parseTrace(tracePath);
   expect(trace.apiNames).toContain('page.goto');
   expect(result.failed).toBe(1);
 });
 
-test('trace:on-first-failure should create trace if request context is disposed before failure', async ({ runInlineTest, server }) => {
+test('trace:retain-on-first-failure should create trace if request context is disposed before failure', async ({ runInlineTest, server }) => {
   const result = await runInlineTest({
     'a.spec.ts': `
       import { test, expect } from '@playwright/test';
@@ -1101,7 +1101,7 @@ test('trace:on-first-failure should create trace if request context is disposed
         expect(1).toBe(2);
       });
     `,
-  }, { trace: 'on-first-failure' });
+  }, { trace: 'retain-on-first-failure' });
   const tracePath = test.info().outputPath('test-results', 'a-fail', 'trace.zip');
   const trace = await parseTrace(tracePath);
   expect(trace.apiNames).toContain('apiRequestContext.get');
diff --git a/utils/generate_types/overrides-test.d.ts b/utils/generate_types/overrides-test.d.ts
index 86d8afd287..8cd43a6750 100644
--- a/utils/generate_types/overrides-test.d.ts
+++ b/utils/generate_types/overrides-test.d.ts
@@ -248,7 +248,7 @@ export interface PlaywrightWorkerOptions {
 }
 
 export type ScreenshotMode = 'off' | 'on' | 'only-on-failure';
-export type TraceMode = 'off' | 'on' | 'retain-on-failure' | 'on-first-retry' | 'on-all-retries' | 'on-first-failure';
+export type TraceMode = 'off' | 'on' | 'retain-on-failure' | 'on-first-retry' | 'on-all-retries' | 'retain-on-first-failure';
 export type VideoMode = 'off' | 'on' | 'retain-on-failure' | 'on-first-retry';
 
 export interface PlaywrightTestOptions {