refactor: merge emulate tools into one (#494)

Merges emulateCpu and emulateNetwork into a single tool to reduce token
consumption. Changes descriptions to be more concise.

README.md

@@ -260,9 +260,8 @@ If you run into any issues, checkout our [troubleshooting guide](./docs/troubles
   - [`new_page`](docs/tool-reference.md#new_page)
   - [`select_page`](docs/tool-reference.md#select_page)
   - [`wait_for`](docs/tool-reference.md#wait_for)
-- **Emulation** (3 tools)
-  - [`emulate_cpu`](docs/tool-reference.md#emulate_cpu)
-  - [`emulate_network`](docs/tool-reference.md#emulate_network)
+- **Emulation** (2 tools)
+  - [`emulate`](docs/tool-reference.md#emulate)
   - [`resize_page`](docs/tool-reference.md#resize_page)
 - **Performance** (3 tools)
   - [`performance_analyze_insight`](docs/tool-reference.md#performance_analyze_insight)

docs/tool-reference.md

@@ -18,9 +18,8 @@
   - [`new_page`](#new_page)
   - [`select_page`](#select_page)
   - [`wait_for`](#wait_for)
-- **[Emulation](#emulation)** (3 tools)
-  - [`emulate_cpu`](#emulate_cpu)
-  - [`emulate_network`](#emulate_network)
+- **[Emulation](#emulation)** (2 tools)
+  - [`emulate`](#emulate)
   - [`resize_page`](#resize_page)
 - **[Performance](#performance)** (3 tools)
   - [`performance_analyze_insight`](#performance_analyze_insight)
@@ -190,23 +189,14 @@
 
 ## Emulation
 
-### `emulate_cpu`
+### `emulate`
 
-**Description:** Emulates CPU throttling by slowing down the selected page's execution.
+**Description:** Emulates various features on the selected page.
 
 **Parameters:**
 
-- **throttlingRate** (number) **(required)**: The CPU throttling rate representing the slowdown factor 1-20x. Set the rate to 1 to disable throttling
-
----
-
-### `emulate_network`
-
-**Description:** Emulates network conditions such as throttling or offline mode on the selected page.
-
-**Parameters:**
-
-- **throttlingOption** (enum: "No emulation", "Offline", "Slow 3G", "Fast 3G", "Slow 4G", "Fast 4G") **(required)**: The network throttling option to emulate. Available throttling options are: No emulation, Offline, Slow 3G, Fast 3G, Slow 4G, Fast 4G. Set to "No emulation" to disable. Set to "Offline" to simulate offline network conditions.
+- **cpuThrottlingRate** (number) _(optional)_: Represents the CPU slowdown factor. Set the rate to 1 to disable throttling. If omitted, throttling remains unchanged.
+- **networkConditions** (enum: "No emulation", "Offline", "Slow 3G", "Fast 3G", "Slow 4G", "Fast 4G") _(optional)_: Throttle network. Set to "No emulation" to disable. If omitted, conditions remain unchanged.
 
 ---
 

src/tools/emulation.ts

@@ -15,73 +15,65 @@ const throttlingOptions: [string, ...string[]] = [
   ...Object.keys(PredefinedNetworkConditions),
 ];
 
-export const emulateNetwork = defineTool({
-  name: 'emulate_network',
-  description: `Emulates network conditions such as throttling or offline mode on the selected page.`,
+export const emulate = defineTool({
+  name: 'emulate',
+  description: `Emulates various features on the selected page.`,
   annotations: {
     category: ToolCategory.EMULATION,
     readOnlyHint: false,
   },
   schema: {
-    throttlingOption: zod
+    networkConditions: zod
       .enum(throttlingOptions)
+      .optional()
       .describe(
-        `The network throttling option to emulate. Available throttling options are: ${throttlingOptions.join(', ')}. Set to "No emulation" to disable. Set to "Offline" to simulate offline network conditions.`,
+        `Throttle network. Set to "No emulation" to disable. If omitted, conditions remain unchanged.`,
       ),
-  },
-  handler: async (request, _response, context) => {
-    const page = context.getSelectedPage();
-    const conditions = request.params.throttlingOption;
-
-    if (conditions === 'No emulation') {
-      await page.emulateNetworkConditions(null);
-      context.setNetworkConditions(null);
-      return;
-    }
-
-    if (conditions === 'Offline') {
-      await page.emulateNetworkConditions({
-        offline: true,
-        download: 0,
-        upload: 0,
-        latency: 0,
-      });
-      context.setNetworkConditions('Offline');
-      return;
-    }
-
-    if (conditions in PredefinedNetworkConditions) {
-      const networkCondition =
-        PredefinedNetworkConditions[
-          conditions as keyof typeof PredefinedNetworkConditions
-        ];
-      await page.emulateNetworkConditions(networkCondition);
-      context.setNetworkConditions(conditions);
-    }
-  },
-});
-
-export const emulateCpu = defineTool({
-  name: 'emulate_cpu',
-  description: `Emulates CPU throttling by slowing down the selected page's execution.`,
-  annotations: {
-    category: ToolCategory.EMULATION,
-    readOnlyHint: false,
-  },
-  schema: {
-    throttlingRate: zod
+    cpuThrottlingRate: zod
       .number()
       .min(1)
       .max(20)
+      .optional()
       .describe(
-        'The CPU throttling rate representing the slowdown factor 1-20x. Set the rate to 1 to disable throttling',
+        'Represents the CPU slowdown factor. Set the rate to 1 to disable throttling. If omitted, throttling remains unchanged.',
       ),
   },
   handler: async (request, _response, context) => {
     const page = context.getSelectedPage();
-    const {throttlingRate} = request.params;
+    const networkConditions = request.params.networkConditions;
+    const cpuThrottlingRate = request.params.cpuThrottlingRate;
 
-    await page.emulateCPUThrottling(throttlingRate);
-    context.setCpuThrottlingRate(throttlingRate);
+    if (networkConditions) {
+      if (networkConditions === 'No emulation') {
+        await page.emulateNetworkConditions(null);
+        context.setNetworkConditions(null);
+        return;
+      }
+
+      if (networkConditions === 'Offline') {
+        await page.emulateNetworkConditions({
+          offline: true,
+          download: 0,
+          upload: 0,
+          latency: 0,
+        });
+        context.setNetworkConditions('Offline');
+        return;
+      }
+
+      if (networkConditions in PredefinedNetworkConditions) {
+        const networkCondition =
+          PredefinedNetworkConditions[
+            networkConditions as keyof typeof PredefinedNetworkConditions
+          ];
+        await page.emulateNetworkConditions(networkCondition);
+        context.setNetworkConditions(networkConditions);
+      }
+    }
+
+    if (cpuThrottlingRate) {
+      await page.emulateCPUThrottling(cpuThrottlingRate);
+      context.setCpuThrottlingRate(cpuThrottlingRate);
+    }
   },
 });

tests/tools/emulation.test.ts

@@ -6,17 +6,17 @@
 import assert from 'node:assert';
 import {describe, it} from 'node:test';
 
-import {emulateCpu, emulateNetwork} from '../../src/tools/emulation.js';
+import {emulate} from '../../src/tools/emulation.js';
 import {withBrowser} from '../utils.js';
 
 describe('emulation', () => {
   describe('network', () => {
     it('emulates offline network conditions', async () => {
       await withBrowser(async (response, context) => {
-        await emulateNetwork.handler(
+        await emulate.handler(
           {
             params: {
-              throttlingOption: 'Offline',
+              networkConditions: 'Offline',
             },
           },
           response,
@@ -26,12 +26,12 @@ describe('emulation', () => {
         assert.strictEqual(context.getNetworkConditions(), 'Offline');
       });
     });
-    it('emulates network throttling when the throttling option is valid ', async () => {
+    it('emulates network throttling when the throttling option is valid', async () => {
       await withBrowser(async (response, context) => {
-        await emulateNetwork.handler(
+        await emulate.handler(
           {
             params: {
-              throttlingOption: 'Slow 3G',
+              networkConditions: 'Slow 3G',
             },
           },
           response,
@@ -44,10 +44,10 @@ describe('emulation', () => {
 
     it('disables network emulation', async () => {
       await withBrowser(async (response, context) => {
-        await emulateNetwork.handler(
+        await emulate.handler(
           {
             params: {
-              throttlingOption: 'No emulation',
+              networkConditions: 'No emulation',
             },
           },
           response,
@@ -60,10 +60,10 @@ describe('emulation', () => {
 
     it('does not set throttling when the network throttling is not one of the predefined options', async () => {
       await withBrowser(async (response, context) => {
-        await emulateNetwork.handler(
+        await emulate.handler(
           {
             params: {
-              throttlingOption: 'Slow 11G',
+              networkConditions: 'Slow 11G',
             },
           },
           response,
@@ -77,10 +77,10 @@ describe('emulation', () => {
     it('report correctly for the currently selected page', async () => {
       await withBrowser(async (response, context) => {
         await context.newPage();
-        await emulateNetwork.handler(
+        await emulate.handler(
           {
             params: {
-              throttlingOption: 'Slow 3G',
+              networkConditions: 'Slow 3G',
             },
           },
           response,
@@ -99,10 +99,10 @@ describe('emulation', () => {
   describe('cpu', () => {
     it('emulates cpu throttling when the rate is valid (1-20x)', async () => {
       await withBrowser(async (response, context) => {
-        await emulateCpu.handler(
+        await emulate.handler(
           {
             params: {
-              throttlingRate: 4,
+              cpuThrottlingRate: 4,
             },
           },
           response,
@@ -116,10 +116,10 @@ describe('emulation', () => {
     it('disables cpu throttling', async () => {
       await withBrowser(async (response, context) => {
         context.setCpuThrottlingRate(4); // Set it to something first.
-        await emulateCpu.handler(
+        await emulate.handler(
           {
             params: {
-              throttlingRate: 1,
+              cpuThrottlingRate: 1,
             },
           },
           response,
@@ -133,10 +133,10 @@ describe('emulation', () => {
     it('report correctly for the currently selected page', async () => {
       await withBrowser(async (response, context) => {
         await context.newPage();
-        await emulateCpu.handler(
+        await emulate.handler(
           {
             params: {
-              throttlingRate: 4,
+              cpuThrottlingRate: 4,
             },
           },
           response,