0
# Network Requests
1

2
Network request and cookie types for WebDriver Bidi protocol, enabling monitoring and manipulation of network traffic during browser automation.
3

4
## Capabilities
5

6
### Network Request Structure
7

8
Core network request interface for WebDriver Bidi protocol.
9

10
```typescript { .api }
11
/**
12
 * Network request during a WebDriver Bidi session
13
 */
14
interface Request {
15
  /** Unique request identifier */
16
  id?: string;
17
  /** Request URL */
18
  url: string;
19
  /** Request timestamp */
20
  timestamp: number;
21
  /** Navigation identifier */
22
  navigation?: string;
23
  /** Chain of redirect URLs */
24
  redirectChain?: string[];
25
  /** Request headers */
26
  headers: Record<string, string>;
27
  /** Request cookies */
28
  cookies?: NetworkCookie[];
29
  /** Error message if request failed */
30
  error?: string;
31
  /** Response information */
32
  response?: {
33
    /** Whether response came from cache */
34
    fromCache: boolean;
35
    /** Response headers */
36
    headers: Record<string, string>;
37
    /** Response MIME type */
38
    mimeType: string;
39
    /** HTTP status code */
40
    status: number;
41
  };
42
  /** 
43
   * List of child requests made due to the main request.
44
   * Note: the list may be incomplete and does not contain requests
45
   * made after the command has finished.
46
   * The property will be undefined if the request is not a document
47
   * request initiated by the browser.
48
   */
49
  children?: Request[];
50
}
51
```
52

53
### Network Cookie Structure
54

55
Cookie information for network requests and responses.
56

57
```typescript { .api }
58
/**
59
 * Network cookie interface
60
 */
61
interface NetworkCookie extends Extensible {
62
  /** Cookie name */
63
  name: string;
64
  /** Cookie value */
65
  value: string;
66
  /** Cookie domain */
67
  domain: string;
68
  /** Cookie path */
69
  path: string;
70
  /** Cookie size in bytes */
71
  size: number;
72
  /** Whether cookie is HTTP-only */
73
  httpOnly: boolean;
74
  /** Whether cookie requires secure connection */
75
  secure: boolean;
76
  /** SameSite attribute */
77
  sameSite: NetworkSameSite;
78
  /** Cookie expiry timestamp (optional) */
79
  expiry?: number;
80
}
81

82
/**
83
 * Cookie SameSite attribute values
84
 */
85
type NetworkSameSite = 'strict' | 'lax' | 'none';
86

87
/**
88
 * Extensible interface for additional properties
89
 */
90
type Extensible = Record<string, unknown>;
91
```
92

93
**Usage Examples:**
94

95
```typescript
96
import type { Network } from "@wdio/types";
97

98
// Network request handler
99
class NetworkMonitor {
100
  private requests: Network.Request[] = [];
101

102
  onRequest(request: Network.Request) {
103
    console.log(`Request: ${request.url}`);
104
    this.requests.push(request);
105
    
106
    // Log headers
107
    Object.entries(request.headers).forEach(([name, value]) => {
108
      console.log(`  ${name}: ${value}`);
109
    });
110
    
111
    // Log cookies
112
    if (request.cookies) {
113
      request.cookies.forEach(cookie => {
114
        console.log(`  Cookie: ${cookie.name}=${cookie.value}`);
115
      });
116
    }
117
  }
118

119
  onResponse(request: Network.Request) {
120
    if (request.response) {
121
      const { status, mimeType, fromCache } = request.response;
122
      console.log(`Response: ${status} ${mimeType} ${fromCache ? '(cached)' : ''}`);
123
      
124
      if (request.error) {
125
        console.error(`Request failed: ${request.error}`);
126
      }
127
    }
128
  }
129

130
  getRequestsByDomain(domain: string): Network.Request[] {
131
    return this.requests.filter(req => {
132
      try {
133
        return new URL(req.url).hostname.includes(domain);
134
      } catch {
135
        return false;
136
      }
137
    });
138
  }
139

140
  getFailedRequests(): Network.Request[] {
141
    return this.requests.filter(req => req.error || 
142
      (req.response && req.response.status >= 400));
143
  }
144
}
145

146
// Cookie utilities
147
class CookieManager {
148
  static createCookie(
149
    name: string, 
150
    value: string, 
151
    options: Partial<Network.NetworkCookie> = {}
152
  ): Network.NetworkCookie {
153
    return {
154
      name,
155
      value,
156
      domain: options.domain || '',
157
      path: options.path || '/',
158
      size: (name + value).length,
159
      httpOnly: options.httpOnly || false,
160
      secure: options.secure || false,
161
      sameSite: options.sameSite || 'lax',
162
      expiry: options.expiry,
163
      ...options
164
    };
165
  }
166

167
  static isExpired(cookie: Network.NetworkCookie): boolean {
168
    if (!cookie.expiry) return false;
169
    return Date.now() > cookie.expiry * 1000;
170
  }
171

172
  static matchesDomain(cookie: Network.NetworkCookie, domain: string): boolean {
173
    if (cookie.domain.startsWith('.')) {
174
      return domain.endsWith(cookie.domain.slice(1));
175
    }
176
    return domain === cookie.domain;
177
  }
178
}
179

180
// Request filtering and analysis
181
function analyzeNetworkTraffic(requests: Network.Request[]) {
182
  const stats = {
183
    total: requests.length,
184
    successful: 0,
185
    failed: 0,
186
    cached: 0,
187
    byDomain: new Map<string, number>(),
188
    byStatus: new Map<number, number>()
189
  };
190

191
  requests.forEach(request => {
192
    // Count by domain
193
    try {
194
      const domain = new URL(request.url).hostname;
195
      stats.byDomain.set(domain, (stats.byDomain.get(domain) || 0) + 1);
196
    } catch {}
197

198
    // Count by status
199
    if (request.response) {
200
      const status = request.response.status;
201
      stats.byStatus.set(status, (stats.byStatus.get(status) || 0) + 1);
202
      
203
      if (status >= 200 && status < 400) {
204
        stats.successful++;
205
      } else {
206
        stats.failed++;
207
      }
208
      
209
      if (request.response.fromCache) {
210
        stats.cached++;
211
      }
212
    } else if (request.error) {
213
      stats.failed++;
214
    }
215
  });
216

217
  return stats;
218
}
219
```