Revert "chore: hide setup, store, TestProject.setupMatch, storageStat… (#19756)

…eName (#19442)"

This reverts commit 92dd734.

Author: yury-s

docs/src/test-api/class-testoptions.md

@@ -205,6 +205,14 @@ Learn more about [automatic screenshots](../test-configuration.md#automatic-scre
 ## property: TestOptions.storageState = %%-js-python-context-option-storage-state-%%
 * since: v1.10
 
+## property: TestOptions.storageStateName
+* since: v1.29
+- type: <[string]>
+
+Name of the [TestStore] entry that should be used to initialize [`property: TestOptions.storageState`]. The value must be
+written to the test storage before creation of a browser context that uses it (usually in [`property: TestProject.setupMatch`]). If both
+this property and [`property: TestOptions.storageState`] are specified, this property will always take precedence.
+
 ## property: TestOptions.testIdAttribute
 * since: v1.27
 

docs/src/test-api/class-testproject.md

@@ -146,7 +146,7 @@ Filter to only run tests with a title matching one of the patterns. For example,
 * since: v1.10
 - type: ?<[RegExp]|[Array]<[RegExp]>>
 
-Filter to only run tests with a title **not** matching one of the patterns. This is the opposite of [`property: TestProject.grep`]. Also available globally and in the [command line](../test-cli.md) with the `--grep-invert` option.
+Filter to only run tests with a title **not** matching one of the patterns. This is the opposite of [`property: TestProject.grep`]. Also available globally and in the [command line](../test-cli.md) with the `--grep-invert` option. This filter and its command line counterpart also applies to the setup files. If all [`property: TestProject.setupMatch`] tests match the filter Playwright **will** run all setup files before running the matching tests.
 
 `grepInvert` option is also useful for [tagging tests](../test-annotations.md#tag-tests).
 
@@ -162,6 +162,18 @@ Metadata that will be put directly to the test report serialized as JSON.
 
 Project name is visible in the report and during test execution.
 
+## property: TestProject.setupMatch
+* since: v1.29
+- type: ?<[string]|[RegExp]|[Array]<[string]|[RegExp]>>
+
+Project setup files that will be executed before all tests in the project.
+
+**Details**
+
+If project setup fails the tests in this project will be skipped. All project setup files will run in every shard if the project is sharded. [`property: TestProject.grep`] and [`property: TestProject.grepInvert`] and their command line counterparts also apply to the setup files. If such filters match only tests in the project, Playwright will run **all** setup files before running the matching tests.
+
+If there is a file that matches both [`property: TestProject.setupMatch`] and [`property: TestProject.testMatch`] filters an error will be thrown.
+
 ## property: TestProject.snapshotDir
 * since: v1.10
 - type: ?<[string]>

docs/src/test-api/class-teststore.md

@@ -0,0 +1,56 @@
+# class: TestStore
+* since: v1.29
+* langs: js
+
+Playwright Test provides a global `store` object for passing values between project setup and tests. It is
+an error to call store methods outside of setup and tests.
+
+```js tab=js-js
+const { setup, store } = require('@playwright/test');
+
+setup('sign in', async ({ page, context }) => {
+  // Save signed-in state to an entry named 'github-test-user'.
+  const contextState = await context.storageState();
+  await store.set('test-user', contextState)
+});
+```
+
+```js tab=js-ts
+import { setup, store } from '@playwright/test';
+
+setup('sign in', async ({ page, context }) => {
+  // Save signed-in state to an entry named 'github-test-user'.
+  const contextState = await context.storageState();
+  await store.set('test-user', contextState)
+});
+```
+
+## async method: TestStore.get
+* since: v1.29
+- returns: <[any]>
+
+Get named item from the store. Returns undefined if there is no value with given name.
+
+### param: TestStore.get.name
+* since: v1.29
+- `name` <[string]>
+
+Item name.
+
+## async method: TestStore.set
+* since: v1.29
+
+Set value to the store.
+
+### param: TestStore.set.name
+* since: v1.29
+- `name` <[string]>
+
+Item name.
+
+### param: TestStore.set.value
+* since: v1.29
+- `value` <[any]>
+
+Item value. The value must be serializable to JSON. Passing `undefined` deletes the entry with given name.
+

packages/playwright-test/src/index.ts

@@ -27,7 +27,7 @@ import { rootTestType, _setProjectSetup } from './testType';
 export { expect } from './expect';
 export { addRunnerPlugin as _addRunnerPlugin } from './plugins';
 export const _baseTest: TestType<{}, {}> = rootTestType.test;
-export const _store = _baseStore;
+export const store = _baseStore;
 
 if ((process as any)['__pw_initiator__']) {
   const originalStackTraceLimit = Error.stackTraceLimit;
@@ -47,7 +47,6 @@ type TestFixtures = PlaywrightTestArgs & PlaywrightTestOptions & {
   _reuseContext: boolean,
   _setupContextOptionsAndArtifacts: void;
   _contextFactory: (options?: BrowserContextOptions) => Promise<BrowserContext>;
-  _storageStateName: string | undefined;
 };
 type WorkerFixtures = PlaywrightWorkerArgs & PlaywrightWorkerOptions & {
   _browserOptions: LaunchOptions;
@@ -144,7 +143,7 @@ const playwrightFixtures: Fixtures<TestFixtures, WorkerFixtures> = ({
   permissions: [({ contextOptions }, use) => use(contextOptions.permissions), { option: true }],
   proxy: [({ contextOptions }, use) => use(contextOptions.proxy), { option: true }],
   storageState: [({ contextOptions }, use) => use(contextOptions.storageState), { option: true }],
-  _storageStateName: [undefined, { option: true }],
+  storageStateName: [undefined, { option: true }],
   timezoneId: [({ contextOptions }, use) => use(contextOptions.timezoneId), { option: true }],
   userAgent: [({ contextOptions }, use) => use(contextOptions.userAgent), { option: true }],
   viewport: [({ contextOptions }, use) => use(contextOptions.viewport === undefined ? { width: 1280, height: 720 } : contextOptions.viewport), { option: true }],
@@ -174,7 +173,7 @@ const playwrightFixtures: Fixtures<TestFixtures, WorkerFixtures> = ({
     permissions,
     proxy,
     storageState,
-    _storageStateName,
+    storageStateName,
     viewport,
     timezoneId,
     userAgent,
@@ -213,10 +212,10 @@ const playwrightFixtures: Fixtures<TestFixtures, WorkerFixtures> = ({
       options.permissions = permissions;
     if (proxy !== undefined)
       options.proxy = proxy;
-    if (_storageStateName !== undefined) {
-      const value = await _store.get(_storageStateName);
+    if (storageStateName !== undefined) {
+      const value = await store.get(storageStateName);
       if (!value)
-        throw new Error(`Cannot find value in the _store for _storageStateName: "${_storageStateName}"`);
+        throw new Error(`Cannot find value in the store for storageStateName: "${storageStateName}"`);
       options.storageState = value as any;
     } else if (storageState !== undefined) {
       options.storageState = storageState;
@@ -629,7 +628,7 @@ function normalizeScreenshotMode(screenshot: PlaywrightWorkerOptions['screenshot
 const kTracingStarted = Symbol('kTracingStarted');
 
 export const test = _baseTest.extend<TestFixtures, WorkerFixtures>(playwrightFixtures);
-export const _setup = _baseTest.extend<TestFixtures, WorkerFixtures>(playwrightFixtures);
-_setProjectSetup(_setup, true);
+export const setup = _baseTest.extend<TestFixtures, WorkerFixtures>(playwrightFixtures);
+_setProjectSetup(setup, true);
 
 export default test;

packages/playwright-test/src/loader.ts

@@ -275,7 +275,7 @@ export class Loader {
     const outputDir = takeFirst(projectConfig.outputDir, config.outputDir, path.join(throwawayArtifactsPath, 'test-results'));
     const snapshotDir = takeFirst(projectConfig.snapshotDir, config.snapshotDir, testDir);
     const name = takeFirst(projectConfig.name, config.name, '');
-    const _setupMatch = takeFirst((projectConfig as any)._setupMatch, []);
+    const _setupMatch = takeFirst(projectConfig.setupMatch, []);
 
     const defaultSnapshotPathTemplate = '{snapshotDir}/{testFileDir}/{testFileName}-snapshots/{arg}{-projectName}{-snapshotSuffix}{ext}';
     const snapshotPathTemplate = takeFirst(projectConfig.snapshotPathTemplate, config.snapshotPathTemplate, defaultSnapshotPathTemplate);
@@ -614,7 +614,7 @@ function validateProject(file: string, project: Project, title: string) {
       throw errorWithFile(file, `${title}.testDir must be a string`);
   }
 
-  for (const prop of ['testIgnore', 'testMatch'] as const) {
+  for (const prop of ['testIgnore', 'testMatch', 'setupMatch'] as const) {
     if (prop in project && project[prop] !== undefined) {
       const value = project[prop];
       if (Array.isArray(value)) {

packages/playwright-test/src/runner.ts

@@ -258,13 +258,13 @@ export class Runner {
         if (!isTest && !isSetup)
           return false;
         if (isSetup && isTest)
-          throw new Error(`File "${file}" matches both '_setup' and 'testMatch' filters in project "${project.name}"`);
+          throw new Error(`File "${file}" matches both 'setup' and 'testMatch' filters in project "${project.name}"`);
         if (fileToProjectName.has(file)) {
           if (isSetup) {
             if (!setupFiles.has(file))
-              throw new Error(`File "${file}" matches '_setup' filter in project "${project.name}" and 'testMatch' filter in project "${fileToProjectName.get(file)}"`);
+              throw new Error(`File "${file}" matches 'setup' filter in project "${project.name}" and 'testMatch' filter in project "${fileToProjectName.get(file)}"`);
           } else if (setupFiles.has(file)) {
-            throw new Error(`File "${file}" matches '_setup' filter in project "${fileToProjectName.get(file)}" and 'testMatch' filter in project "${project.name}"`);
+            throw new Error(`File "${file}" matches 'setup' filter in project "${fileToProjectName.get(file)}" and 'testMatch' filter in project "${project.name}"`);
           }
         }
         fileToProjectName.set(file, project.name);

packages/playwright-test/src/store.ts

@@ -16,10 +16,11 @@
 
 import fs from 'fs';
 import path from 'path';
+import type { TestStore } from '../types/test';
 import { currentTestInfo } from './globals';
 import { sanitizeForFilePath, trimLongString } from './util';
 
-class JsonStore {
+class JsonStore implements TestStore {
   private _toFilePath(name: string) {
     const testInfo = currentTestInfo();
     if (!testInfo)

packages/playwright-test/src/testType.ts

@@ -84,14 +84,14 @@ export class TestTypeImpl {
       if (this._projectSetup)
         addFatalError(`${title} is called in a file which is not a part of project setup.`, location);
       else
-        addFatalError(`${title} is called in a project setup file (use '_setup' instead of 'test').`, location);
+        addFatalError(`${title} is called in a project setup file (use 'setup' instead of 'test').`, location);
     }
     return suite;
   }
 
   private _createTest(type: 'default' | 'only' | 'skip' | 'fixme', location: Location, title: string, fn: Function) {
     throwIfRunningInsideJest();
-    const suite = this._currentSuite(location, this._projectSetup ? '_setup()' : 'test()');
+    const suite = this._currentSuite(location, this._projectSetup ? 'setup()' : 'test()');
     if (!suite)
       return;
     const test = new TestCase(title, fn, this, location);
@@ -150,15 +150,15 @@ export class TestTypeImpl {
   }
 
   private _hook(name: 'beforeEach' | 'afterEach' | 'beforeAll' | 'afterAll', location: Location, fn: Function) {
-    const suite = this._currentSuite(location, `${this._projectSetup ? '_setup' : 'test'}.${name}()`);
+    const suite = this._currentSuite(location, `${this._projectSetup ? 'setup' : 'test'}.${name}()`);
     if (!suite)
       return;
     suite._hooks.push({ type: name, fn, location });
   }
 
   private _configure(location: Location, options: { mode?: 'parallel' | 'serial', retries?: number, timeout?: number }) {
     throwIfRunningInsideJest();
-    const suite = this._currentSuite(location, `${this._projectSetup ? '_setup' : 'test'}.describe.configure()`);
+    const suite = this._currentSuite(location, `${this._projectSetup ? 'setup' : 'test'}.describe.configure()`);
     if (!suite)
       return;
 
@@ -225,7 +225,7 @@ export class TestTypeImpl {
   }
 
   private _use(location: Location, fixtures: Fixtures) {
-    const suite = this._currentSuite(location, `${this._projectSetup ? '_setup' : 'test'}.use()`);
+    const suite = this._currentSuite(location, `${this._projectSetup ? 'setup' : 'test'}.use()`);
     if (!suite)
       return;
     suite._use.push({ fixtures, location });
@@ -234,7 +234,7 @@ export class TestTypeImpl {
   private async _step<T>(location: Location, title: string, body: () => Promise<T>): Promise<T> {
     const testInfo = currentTestInfo();
     if (!testInfo) {
-      addFatalError(`${this._projectSetup ? '_setup' : 'test'}.step() can only be called from a test`, location);
+      addFatalError(`${this._projectSetup ? 'setup' : 'test'}.step() can only be called from a test`, location);
       return undefined as any;
     }
     const step = testInfo._addStep({

packages/playwright-test/types/test.d.ts

@@ -193,7 +193,10 @@ export interface FullProject<TestArgs = {}, WorkerArgs = {}> {
   /**
    * Filter to only run tests with a title **not** matching one of the patterns. This is the opposite of
    * [testProject.grep](https://playwright.dev/docs/api/class-testproject#test-project-grep). Also available globally
-   * and in the [command line](https://playwright.dev/docs/test-cli) with the `--grep-invert` option.
+   * and in the [command line](https://playwright.dev/docs/test-cli) with the `--grep-invert` option. This filter and its command line
+   * counterpart also applies to the setup files. If all
+   * [testProject.setupMatch](https://playwright.dev/docs/api/class-testproject#test-project-setup-match) tests match
+   * the filter Playwright **will** run all setup files before running the matching tests.
    *
    * `grepInvert` option is also useful for [tagging tests](https://playwright.dev/docs/test-annotations#tag-tests).
    */
@@ -2826,6 +2829,35 @@ type ConnectOptions = {
   timeout?: number;
 };
 
+/**
+ * Playwright Test provides a global `store` object for passing values between project setup and tests. It is an error
+ * to call store methods outside of setup and tests.
+ *
+ * ```js
+ * import { setup, store } from '@playwright/test';
+ *
+ * setup('sign in', async ({ page, context }) => {
+ *   // Save signed-in state to an entry named 'github-test-user'.
+ *   const contextState = await context.storageState();
+ *   await store.set('test-user', contextState)
+ * });
+ * ```
+ *
+ */
+export interface TestStore {
+  /**
+   * Get named item from the store. Returns undefined if there is no value with given name.
+   * @param name Item name.
+   */
+  get<T>(name: string): Promise<T | undefined>;
+  /**
+   * Set value to the store.
+   * @param name Item name.
+   * @param value Item value. The value must be serializable to JSON. Passing `undefined` deletes the entry with given name.
+   */
+  set<T>(name: string, value: T | undefined): Promise<void>;
+}
+
 /**
  * Playwright Test provides many options to configure test environment, [Browser], [BrowserContext] and more.
  *
@@ -3062,6 +3094,16 @@ export interface PlaywrightTestOptions {
    * Either a path to the file with saved storage, or an object with the following fields:
    */
   storageState: StorageState | undefined;
+  /**
+   * Name of the [TestStore] entry that should be used to initialize
+   * [testOptions.storageState](https://playwright.dev/docs/api/class-testoptions#test-options-storage-state). The value
+   * must be written to the test storage before creation of a browser context that uses it (usually in
+   * [testProject.setupMatch](https://playwright.dev/docs/api/class-testproject#test-project-setup-match)). If both this
+   * property and
+   * [testOptions.storageState](https://playwright.dev/docs/api/class-testoptions#test-options-storage-state) are
+   * specified, this property will always take precedence.
+   */
+  storageStateName: string | undefined;
   /**
    * Changes the timezone of the context. See
    * [ICU's metaZones.txt](https://cs.chromium.org/chromium/src/third_party/icu/source/data/misc/metaZones.txt?rcl=faee8bc70570192d82d2978a71e2a615788597d1)
@@ -3345,6 +3387,7 @@ export default test;
 
 export const _baseTest: TestType<{}, {}>;
 export const expect: Expect;
+export const store: TestStore;
 
 // This is required to not export everything by default. See https://github.com/Microsoft/TypeScript/issues/19545#issuecomment-340490459
 export {};
@@ -4639,7 +4682,10 @@ interface TestProject {
   /**
    * Filter to only run tests with a title **not** matching one of the patterns. This is the opposite of
    * [testProject.grep](https://playwright.dev/docs/api/class-testproject#test-project-grep). Also available globally
-   * and in the [command line](https://playwright.dev/docs/test-cli) with the `--grep-invert` option.
+   * and in the [command line](https://playwright.dev/docs/test-cli) with the `--grep-invert` option. This filter and its command line
+   * counterpart also applies to the setup files. If all
+   * [testProject.setupMatch](https://playwright.dev/docs/api/class-testproject#test-project-setup-match) tests match
+   * the filter Playwright **will** run all setup files before running the matching tests.
    *
    * `grepInvert` option is also useful for [tagging tests](https://playwright.dev/docs/test-annotations#tag-tests).
    */
@@ -4655,6 +4701,24 @@ interface TestProject {
    */
   name?: string;
 
+  /**
+   * Project setup files that will be executed before all tests in the project.
+   *
+   * **Details**
+   *
+   * If project setup fails the tests in this project will be skipped. All project setup files will run in every shard
+   * if the project is sharded. [testProject.grep](https://playwright.dev/docs/api/class-testproject#test-project-grep)
+   * and [testProject.grepInvert](https://playwright.dev/docs/api/class-testproject#test-project-grep-invert) and their
+   * command line counterparts also apply to the setup files. If such filters match only tests in the project,
+   * Playwright will run **all** setup files before running the matching tests.
+   *
+   * If there is a file that matches both
+   * [testProject.setupMatch](https://playwright.dev/docs/api/class-testproject#test-project-setup-match) and
+   * [testProject.testMatch](https://playwright.dev/docs/api/class-testproject#test-project-test-match) filters an error
+   * will be thrown.
+   */
+  setupMatch?: string|RegExp|Array<string|RegExp>;
+
   /**
    * The base directory, relative to the config file, for snapshot files created with `toMatchSnapshot`. Defaults to
    * [testProject.testDir](https://playwright.dev/docs/api/class-testproject#test-project-test-dir).