chore: http credentials send immeidately/unauthorized enum

Reference https://github.com/microsoft/playwright-internal/issues/205
Reference https://github.com/microsoft/playwright/issues/30534

docs/src/api/params.md

@@ -571,7 +571,7 @@ Whether to emulate network being offline. Defaults to `false`. Learn more about
   - `username` <[string]>
   - `password` <[string]>
   - `origin` ?<[string]> Restrain sending http credentials on specific origin (scheme://host:port).
-  - `sendImmediately` ?<[boolean]> Whether to send `Authorization` header with the first API request. By default, the credentials are sent only when 401 (Unauthorized) response with `WWW-Authenticate` header is received. This option does not affect requests sent from the browser.
+  - `send` ?<[WhenToSend]<"unauthorized"|"immediately">> This option only applies to the requests sent from corresponding [APIRequestContext] and does not affect requests sent from the browser. `'immediately'` - `Authorization` header with basic authentication credentials will be sent with the first API request. `'unauthorized` - the credentials are only sent when 401 (Unauthorized) response with `WWW-Authenticate` header is received. Defaults to `'unauthorized'`.
 
 Credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication).
 If no origin is specified, the username and password are sent to any servers upon unauthorized responses.

packages/playwright-core/src/protocol/validator.ts

@@ -334,7 +334,7 @@ scheme.PlaywrightNewRequestParams = tObject({
     username: tString,
     password: tString,
     origin: tOptional(tString),
-    sendImmediately: tOptional(tBoolean),
+    send: tOptional(tEnum(['immediately', 'unauthorized'])),
   })),
   proxy: tOptional(tObject({
     server: tString,
@@ -548,7 +548,7 @@ scheme.BrowserTypeLaunchPersistentContextParams = tObject({
     username: tString,
     password: tString,
     origin: tOptional(tString),
-    sendImmediately: tOptional(tBoolean),
+    send: tOptional(tEnum(['immediately', 'unauthorized'])),
   })),
   deviceScaleFactor: tOptional(tNumber),
   isMobile: tOptional(tBoolean),
@@ -627,7 +627,7 @@ scheme.BrowserNewContextParams = tObject({
     username: tString,
     password: tString,
     origin: tOptional(tString),
-    sendImmediately: tOptional(tBoolean),
+    send: tOptional(tEnum(['immediately', 'unauthorized'])),
   })),
   deviceScaleFactor: tOptional(tNumber),
   isMobile: tOptional(tBoolean),
@@ -689,7 +689,7 @@ scheme.BrowserNewContextForReuseParams = tObject({
     username: tString,
     password: tString,
     origin: tOptional(tString),
-    sendImmediately: tOptional(tBoolean),
+    send: tOptional(tEnum(['immediately', 'unauthorized'])),
   })),
   deviceScaleFactor: tOptional(tNumber),
   isMobile: tOptional(tBoolean),
@@ -2478,7 +2478,7 @@ scheme.AndroidDeviceLaunchBrowserParams = tObject({
     username: tString,
     password: tString,
     origin: tOptional(tString),
-    sendImmediately: tOptional(tBoolean),
+    send: tOptional(tEnum(['immediately', 'unauthorized'])),
   })),
   deviceScaleFactor: tOptional(tNumber),
   isMobile: tOptional(tBoolean),

packages/playwright-core/src/server/fetch.ts

@@ -159,7 +159,7 @@ export abstract class APIRequestContext extends SdkObject {
     }
 
     const credentials = this._getHttpCredentials(requestUrl);
-    if (credentials?.sendImmediately)
+    if (credentials?.send === 'immediately')
       setBasicAuthorizationHeader(headers, credentials);
 
     const method = params.method?.toUpperCase() || 'GET';

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

@@ -13383,11 +13383,12 @@ export interface BrowserType<Unused = {}> {
       origin?: string;
 
       /**
-       * Whether to send `Authorization` header with the first API request. By default, the credentials are sent only when
-       * 401 (Unauthorized) response with `WWW-Authenticate` header is received. This option does not affect requests sent
-       * from the browser.
+       * This option only applies to the requests sent from corresponding {@link APIRequestContext} and does not affect
+       * requests sent from the browser. `'immediately'` - `Authorization` header with basic authentication credentials will
+       * be sent with the first API request. `'unauthorized` - the credentials are only sent when 401 (Unauthorized)
+       * response with `WWW-Authenticate` header is received. Defaults to `'unauthorized'`.
        */
-      sendImmediately?: boolean;
+      send?: "unauthorized"|"immediately";
     };
 
     /**
@@ -14920,11 +14921,12 @@ export interface AndroidDevice {
       origin?: string;
 
       /**
-       * Whether to send `Authorization` header with the first API request. By default, the credentials are sent only when
-       * 401 (Unauthorized) response with `WWW-Authenticate` header is received. This option does not affect requests sent
-       * from the browser.
+       * This option only applies to the requests sent from corresponding {@link APIRequestContext} and does not affect
+       * requests sent from the browser. `'immediately'` - `Authorization` header with basic authentication credentials will
+       * be sent with the first API request. `'unauthorized` - the credentials are only sent when 401 (Unauthorized)
+       * response with `WWW-Authenticate` header is received. Defaults to `'unauthorized'`.
        */
-      sendImmediately?: boolean;
+      send?: "unauthorized"|"immediately";
     };
 
     /**
@@ -15651,11 +15653,12 @@ export interface APIRequest {
       origin?: string;
 
       /**
-       * Whether to send `Authorization` header with the first API request. By default, the credentials are sent only when
-       * 401 (Unauthorized) response with `WWW-Authenticate` header is received. This option does not affect requests sent
-       * from the browser.
+       * This option only applies to the requests sent from corresponding {@link APIRequestContext} and does not affect
+       * requests sent from the browser. `'immediately'` - `Authorization` header with basic authentication credentials will
+       * be sent with the first API request. `'unauthorized` - the credentials are only sent when 401 (Unauthorized)
+       * response with `WWW-Authenticate` header is received. Defaults to `'unauthorized'`.
        */
-      sendImmediately?: boolean;
+      send?: "unauthorized"|"immediately";
     };
 
     /**
@@ -16808,11 +16811,12 @@ export interface Browser extends EventEmitter {
       origin?: string;
 
       /**
-       * Whether to send `Authorization` header with the first API request. By default, the credentials are sent only when
-       * 401 (Unauthorized) response with `WWW-Authenticate` header is received. This option does not affect requests sent
-       * from the browser.
+       * This option only applies to the requests sent from corresponding {@link APIRequestContext} and does not affect
+       * requests sent from the browser. `'immediately'` - `Authorization` header with basic authentication credentials will
+       * be sent with the first API request. `'unauthorized` - the credentials are only sent when 401 (Unauthorized)
+       * response with `WWW-Authenticate` header is received. Defaults to `'unauthorized'`.
        */
-      sendImmediately?: boolean;
+      send?: "unauthorized"|"immediately";
     };
 
     /**
@@ -17705,11 +17709,12 @@ export interface Electron {
       origin?: string;
 
       /**
-       * Whether to send `Authorization` header with the first API request. By default, the credentials are sent only when
-       * 401 (Unauthorized) response with `WWW-Authenticate` header is received. This option does not affect requests sent
-       * from the browser.
+       * This option only applies to the requests sent from corresponding {@link APIRequestContext} and does not affect
+       * requests sent from the browser. `'immediately'` - `Authorization` header with basic authentication credentials will
+       * be sent with the first API request. `'unauthorized` - the credentials are only sent when 401 (Unauthorized)
+       * response with `WWW-Authenticate` header is received. Defaults to `'unauthorized'`.
        */
-      sendImmediately?: boolean;
+      send?: "unauthorized"|"immediately";
     };
 
     /**
@@ -20373,11 +20378,12 @@ export interface HTTPCredentials {
   origin?: string;
 
   /**
-   * Whether to send `Authorization` header with the first API request. By default, the credentials are sent only when
-   * 401 (Unauthorized) response with `WWW-Authenticate` header is received. This option does not affect requests sent
-   * from the browser.
+   * This option only applies to the requests sent from corresponding {@link APIRequestContext} and does not affect
+   * requests sent from the browser. `'immediately'` - `Authorization` header with basic authentication credentials will
+   * be sent with the first API request. `'unauthorized` - the credentials are only sent when 401 (Unauthorized)
+   * response with `WWW-Authenticate` header is received. Defaults to `'unauthorized'`.
    */
-  sendImmediately?: boolean;
+  send?: "unauthorized"|"immediately";
 }
 
 export interface Geolocation {

packages/protocol/src/channels.ts

@@ -578,7 +578,7 @@ export type PlaywrightNewRequestParams = {
     username: string,
     password: string,
     origin?: string,
-    sendImmediately?: boolean,
+    send?: 'immediately' | 'unauthorized',
   },
   proxy?: {
     server: string,
@@ -602,7 +602,7 @@ export type PlaywrightNewRequestOptions = {
     username: string,
     password: string,
     origin?: string,
-    sendImmediately?: boolean,
+    send?: 'immediately' | 'unauthorized',
   },
   proxy?: {
     server: string,
@@ -959,7 +959,7 @@ export type BrowserTypeLaunchPersistentContextParams = {
     username: string,
     password: string,
     origin?: string,
-    sendImmediately?: boolean,
+    send?: 'immediately' | 'unauthorized',
   },
   deviceScaleFactor?: number,
   isMobile?: boolean,
@@ -1032,7 +1032,7 @@ export type BrowserTypeLaunchPersistentContextOptions = {
     username: string,
     password: string,
     origin?: string,
-    sendImmediately?: boolean,
+    send?: 'immediately' | 'unauthorized',
   },
   deviceScaleFactor?: number,
   isMobile?: boolean,
@@ -1140,7 +1140,7 @@ export type BrowserNewContextParams = {
     username: string,
     password: string,
     origin?: string,
-    sendImmediately?: boolean,
+    send?: 'immediately' | 'unauthorized',
   },
   deviceScaleFactor?: number,
   isMobile?: boolean,
@@ -1199,7 +1199,7 @@ export type BrowserNewContextOptions = {
     username: string,
     password: string,
     origin?: string,
-    sendImmediately?: boolean,
+    send?: 'immediately' | 'unauthorized',
   },
   deviceScaleFactor?: number,
   isMobile?: boolean,
@@ -1261,7 +1261,7 @@ export type BrowserNewContextForReuseParams = {
     username: string,
     password: string,
     origin?: string,
-    sendImmediately?: boolean,
+    send?: 'immediately' | 'unauthorized',
   },
   deviceScaleFactor?: number,
   isMobile?: boolean,
@@ -1320,7 +1320,7 @@ export type BrowserNewContextForReuseOptions = {
     username: string,
     password: string,
     origin?: string,
-    sendImmediately?: boolean,
+    send?: 'immediately' | 'unauthorized',
   },
   deviceScaleFactor?: number,
   isMobile?: boolean,
@@ -4479,7 +4479,7 @@ export type AndroidDeviceLaunchBrowserParams = {
     username: string,
     password: string,
     origin?: string,
-    sendImmediately?: boolean,
+    send?: 'immediately' | 'unauthorized',
   },
   deviceScaleFactor?: number,
   isMobile?: boolean,
@@ -4536,7 +4536,7 @@ export type AndroidDeviceLaunchBrowserOptions = {
     username: string,
     password: string,
     origin?: string,
-    sendImmediately?: boolean,
+    send?: 'immediately' | 'unauthorized',
   },
   deviceScaleFactor?: number,
   isMobile?: boolean,

packages/protocol/src/protocol.yml

@@ -456,7 +456,11 @@ ContextOptions:
         username: string
         password: string
         origin: string?
-        sendImmediately: boolean?
+        send:
+          type: enum?
+          literals:
+          - immediately
+          - unauthorized
     deviceScaleFactor: number?
     isMobile: boolean?
     hasTouch: boolean?
@@ -674,7 +678,11 @@ Playwright:
             username: string
             password: string
             origin: string?
-            sendImmediately: boolean?
+            send:
+              type: enum?
+              literals:
+              - immediately
+              - unauthorized
         proxy:
           type: object?
           properties:

tests/library/browsercontext-fetch.spec.ts

@@ -435,10 +435,10 @@ it('should return error with wrong credentials', async ({ context, server }) =>
   expect(response2.status()).toBe(401);
 });
 
-it('should support HTTPCredentials.sendImmediately', async ({ contextFactory, server }) => {
+it('should support HTTPCredentials.sendImmediately for newContext', async ({ contextFactory, server }) => {
   it.info().annotations.push({ type: 'issue', description: 'https://github.com/microsoft/playwright/issues/30534' });
   const context = await contextFactory({
-    httpCredentials: { username: 'user', password: 'pass', origin: server.PREFIX.toUpperCase(), sendImmediately: true }
+    httpCredentials: { username: 'user', password: 'pass', origin: server.PREFIX.toUpperCase(), send: 'immediately' }
   });
   {
     const [serverRequest, response] = await Promise.all([
@@ -459,6 +459,31 @@ it('should support HTTPCredentials.sendImmediately', async ({ contextFactory, se
   }
 });
 
+it('should support HTTPCredentials.sendImmediately for browser.newPage', async ({ contextFactory, server, browser }) => {
+  it.info().annotations.push({ type: 'issue', description: 'https://github.com/microsoft/playwright/issues/30534' });
+  const page = await browser.newPage({
+    httpCredentials: { username: 'user', password: 'pass', origin: server.PREFIX.toUpperCase(), send: 'immediately' }
+  });
+  {
+    const [serverRequest, response] = await Promise.all([
+      server.waitForRequest('/empty.html'),
+      page.request.get(server.EMPTY_PAGE)
+    ]);
+    expect(serverRequest.headers.authorization).toBe('Basic ' + Buffer.from('user:pass').toString('base64'));
+    expect(response.status()).toBe(200);
+  }
+  {
+    const [serverRequest, response] = await Promise.all([
+      server.waitForRequest('/empty.html'),
+      page.request.get(server.CROSS_PROCESS_PREFIX + '/empty.html')
+    ]);
+    // Not sent to another origin.
+    expect(serverRequest.headers.authorization).toBe(undefined);
+    expect(response.status()).toBe(200);
+  }
+  await page.close();
+});
+
 it('delete should support post data', async ({ context, server }) => {
   const [request, response] = await Promise.all([
     server.waitForRequest('/simple.json'),

tests/library/global-fetch.spec.ts

@@ -157,7 +157,7 @@ it('should support WWW-Authenticate: Basic', async ({ playwright, server }) => {
 it('should support HTTPCredentials.sendImmediately', async ({ playwright, server }) => {
   it.info().annotations.push({ type: 'issue', description: 'https://github.com/microsoft/playwright/issues/30534' });
   const request = await playwright.request.newContext({
-    httpCredentials: { username: 'user', password: 'pass', origin: server.PREFIX.toUpperCase(), sendImmediately: true }
+    httpCredentials: { username: 'user', password: 'pass', origin: server.PREFIX.toUpperCase(), send: 'immediately' }
   });
   {
     const [serverRequest, response] = await Promise.all([