add/improve comments

packages/driver/src/cypress/command_queue.ts

@@ -259,7 +259,8 @@ export class CommandQueue extends Queue<Command> {
  // start at 0 index if one is not already set
  let index = this.state('index') || this.state('index', 0)
 
- // if at the end of the queue in a secondary domain,
+ // if at the end of the queue when not auto-running, pause will be true
+ // but since there's nothing left in the queue to move things forward,
  // ignore and reset the pause, then let the queue finish
  if (!autoRun && pause && !this.at(index)) {
  pause = false

packages/extension/app/background.js

@@ -50,10 +50,16 @@ const connect = function (host, path, extraOpts) {
  })
 
  const listenToOnBeforeHeaders = once(() => {
+ // adds a header to the request to mark it as a request for the AUT frame
+ // itself, so the proxy can utilize that for injection purposes
  browser.webRequest.onBeforeSendHeaders.addListener((details) => {
  if (
+ // parentFrameId: 0 means the parent is the top-level, so if it isn't
+ // 0, it's nested inside the AUT and can't be the AUT itself
  details.parentFrameId !== 0
+ // isn't an iframe
  || details.type !== 'sub_frame'
+ // is the spec frame, not the AUT
  || details.url.includes('__cypress')
  ) return
 

packages/server/lib/browsers/chrome.ts

@@ -332,13 +332,13 @@ let frameTree
 
 const _onBrowserPreRequest = (client) => {
  return async (prerequest) => {
- // this gets the frame tree ahead of the Fetch.requestPaused event, because
- // the CDP is tied up during that event and can't be utilized. however,
- // we avoid the overhead if it's not possible that the request will be for
- // the AUT frame
+  // this gets the frame tree ahead of the Fetch.requestPaused event, because
+  // the CDP is tied up during that event and can't be utilized. however,
+  // we avoid the overhead if it's not possible that the request will be for
+  // the AUT frame
  if (
  prerequest.originalResourceType !== 'Document'
- || prerequest.url.includes('__cypress')
+  || prerequest.url.includes('__cypress')
  ) {
  return
  }
@@ -397,8 +397,11 @@ const _getAUTFrame = () => {
 const _handlePausedRequests = async (client) => {
  await client.send('Fetch.enable')
 
+ // adds a header to the request to mark it as a request for the AUT frame
+ // itself, so the proxy can utilize that for injection purposes
  client.on('Fetch.requestPaused', (params: Protocol.Fetch.RequestPausedEvent) => {
  if (
+ // is a script, stylesheet, image, etc
  params.resourceType !== 'Document'
  || _getAUTFrame().id !== params.frameId
  ) {

packages/server/lib/browsers/electron.js

@@ -356,10 +356,15 @@ module.exports = {
  return false
  }
 
+ // adds a header to the request to mark it as a request for the AUT frame
+ // itself, so the proxy can utilize that for injection purposes
  win.webContents.session.webRequest.onBeforeSendHeaders((details, cb) => {
  if (
+ // isn't an iframe
  details.resourceType !== 'subFrame'
+ // the top-level frame or a nested frame
  || !isFirstLevelIFrame(details.frame)
+ // is the spec frame, not the AUT
  || details.url.includes('__cypress')
  ) {
  cb({})