From 235cd10a4310604a50328f0947cab711a7bf1157 Mon Sep 17 00:00:00 2001
From: Yury Semikhatsky <yurys@chromium.org>
Date: Fri, 15 Oct 2021 12:03:26 -0700
Subject: [PATCH] fix(runner): clarify where test.use() can be called (#9486)

---
 docs/src/test-api/class-test.md          |  2 +-
 packages/playwright-test/src/testType.ts |  2 +-
 packages/playwright-test/types/test.d.ts |  3 ++-
 tests/playwright-test/test-use.spec.ts   | 16 ++++++++++++++++
 4 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/docs/src/test-api/class-test.md b/docs/src/test-api/class-test.md
index 90b70c6a4c..6db4e3bfee 100644
--- a/docs/src/test-api/class-test.md
+++ b/docs/src/test-api/class-test.md
@@ -954,7 +954,7 @@ Step body.
 
 ## method: Test.use
 
-Specifies options or fixtures to use in a single test file or a [`method: Test.describe`] group. Most useful to set an option, for example set `locale` to configure `context` fixture.
+Specifies options or fixtures to use in a single test file or a [`method: Test.describe`] group. Most useful to set an option, for example set `locale` to configure `context` fixture. `test.use` can be called either in the global scope or inside `test.describe`, it's is an error to call it within `beforeEach` or `beforeAll`.
 
 ```js js-flavor=js
 const { test, expect } = require('@playwright/test');
diff --git a/packages/playwright-test/src/testType.ts b/packages/playwright-test/src/testType.ts
index 1fcc1164c7..5e05d1a38f 100644
--- a/packages/playwright-test/src/testType.ts
+++ b/packages/playwright-test/src/testType.ts
@@ -178,7 +178,7 @@ export class TestTypeImpl {
   private _use(location: Location, fixtures: Fixtures) {
     const suite = currentlyLoadingFileSuite();
     if (!suite)
-      throw errorWithLocation(location, `test.use() can only be called in a test file`);
+      throw errorWithLocation(location, `test.use() can only be called in a test file and can only be nested in test.describe()`);
     suite._use.push({ fixtures, location });
   }
 
diff --git a/packages/playwright-test/types/test.d.ts b/packages/playwright-test/types/test.d.ts
index 0f144b83e8..0421aed84a 100644
--- a/packages/playwright-test/types/test.d.ts
+++ b/packages/playwright-test/types/test.d.ts
@@ -2219,7 +2219,8 @@ export interface TestType<TestArgs extends KeyValue, WorkerArgs extends KeyValue
   /**
    * Specifies options or fixtures to use in a single test file or a
    * [test.describe(title, callback)](https://playwright.dev/docs/api/class-test#test-describe) group. Most useful to set an
-   * option, for example set `locale` to configure `context` fixture.
+   * option, for example set `locale` to configure `context` fixture. `test.use` can be called either in the global scope or
+   * inside `test.describe`, it's is an error to call it within `beforeEach` or `beforeAll`.
    *
    * ```ts
    * import { test, expect } from '@playwright/test';
diff --git a/tests/playwright-test/test-use.spec.ts b/tests/playwright-test/test-use.spec.ts
index b8fa8b1854..53df09d122 100644
--- a/tests/playwright-test/test-use.spec.ts
+++ b/tests/playwright-test/test-use.spec.ts
@@ -163,3 +163,19 @@ test('should use options from the config', async ({ runInlineTest }) => {
   expect(result.exitCode).toBe(0);
   expect(result.passed).toBe(2);
 });
+
+test('test.use() should throw if called from beforeAll ', async ({ runInlineTest }) => {
+  const result = await runInlineTest({
+    'a.test.ts': `
+      const test = pwt.test;
+      test.beforeAll(() => {
+        test.use({});
+      });
+      test('should work', async () => {
+      });
+    `,
+  });
+  expect(result.exitCode).toBe(1);
+  expect(result.output).toContain('test.use() can only be called in a test file and can only be nested in test.describe()');
+});
+