feat: Extend navigate command with browser actions (refresh, back, forward)

- Updated handler to support new actions alongside URL navigation.
- Enhanced flags documentation to reflect the additional options.
- Added comprehensive test coverage for the new browser actions.

Author: Winify

skills/wdiox-usage/flags.md

@@ -70,10 +70,13 @@ export const config = {
 
 ## `navigate` / `goto` flags
 
-| Positional / Flag | Notes                                    |
-|-------------------|------------------------------------------|
-| `<url>`           | URL to navigate to (required)            |
-| `--session` / `-s`| Session name (default: `default`)        |
+| Positional / Flag | Notes                                                          |
+|-------------------|----------------------------------------------------------------|
+| `<url>`           | URL to navigate to                                             |
+| `refresh`         | Reload the current page (`wdiox navigate refresh`)             |
+| `back`            | Go back in browser history (`wdiox navigate back`)             |
+| `forward`         | Go forward in browser history (`wdiox navigate forward`)       |
+| `--session` / `-s`| Session name (default: `default`)                              |
 
 ## `scroll` / `swipe` flags
 

skills/wdiox-usage/navigate-scroll-steps.md

@@ -1,27 +1,35 @@
 # `navigate`, `scroll`, and `steps` — Guide
 
-## `wdiox navigate <url>` / `goto <url>`
+## `wdiox navigate <url|action>` / `goto <url>`
 
-Changes the URL of the active session without closing and reopening it. Works on both browser and mobile (deep link / intent).
+Changes the URL of the active session, or controls browser history. Works on both browser and mobile (deep link / intent).
 
 ```bash
 wdiox navigate https://example.com/dashboard
 wdiox goto https://example.com/settings      # alias
+
+# Browser history actions
+wdiox navigate refresh   # reload the current page
+wdiox navigate back      # go back in browser history
+wdiox navigate forward   # go forward in browser history
 ```
 
 **When to use over `open`:**
 - Mid-session page changes (after login, after clicking a link that fails, etc.)
 - Skipping intermediate pages in a multi-step flow to resume from a known URL
 - Mobile deep links (if the app registers the URL scheme)
 
-**Mobile note:** `navigate` on a native Appium session sends a URL intent via ADB. It works for apps that register URL schemes (deep links). For navigating within the app, use `click` on nav elements instead.
+**Mobile note:** `navigate` on a native Appium session sends a URL intent via ADB. It works for apps that register URL schemes (deep links). For navigating within the app, use `click` on nav elements instead. History actions (`refresh`, `back`, `forward`) are browser-only.
 
 ```bash
 # Browser: skip login, start from the dashboard
 wdiox open https://app.example.com/login
 wdiox fill e2 user@example.com && wdiox fill e3 "$PASSWORD" && wdiox click e4
 wdiox navigate https://app.example.com/dashboard   # jump straight to target
 wdiox snapshot
+
+# Reload after a form submission to check the result
+wdiox click e3 && wdiox navigate refresh && wdiox snapshot
 ```
 
 ---

src/commands/navigate.ts

@@ -4,36 +4,52 @@ import { attach } from 'webdriverio';
 import { buildAttachOptions, withSession } from '../session.js';
 import { appendStep } from '../steps.js';
 
-export const command = ['navigate <url>', 'goto <url>'];
-export const desc = 'Navigate to a URL in the active session';
+export const command = ['navigate [url]', 'goto [url]'];
+export const desc = 'Navigate to a URL, or run refresh / back / forward';
+
+const BROWSER_ACTIONS = ['refresh', 'back', 'forward'] as const;
+type BrowserAction = typeof BROWSER_ACTIONS[number];
 
 export const builder = (yargs: Argv) => {
   return yargs.positional('url', {
     type: 'string',
-    describe: 'URL to navigate to',
+    describe: 'URL to navigate to, or: refresh | back | forward',
   });
 };
 
 interface NavigateArgs {
-  url: string
+  url?: string;
   session: string
   _sessionsDir?: string
 }
 
 export const handler = withSession<NavigateArgs>(async (argv: ArgumentsCamelCase<NavigateArgs>, meta, sessionsDir) => {
   const startTime = Date.now();
-  const sessionName = argv.session as string;
-  const url = argv.url as string;
+  const session = argv.session;
+  const url = argv.url;
+
+  if (!url) {
+    console.error('URL or action required. Usage: wdiox navigate <url|refresh|back|forward>');
+    return;
+  }
 
   const browser = await attach(buildAttachOptions(meta));
+  const action = BROWSER_ACTIONS.includes(url as BrowserAction) ? url as BrowserAction : null;
 
   try {
-    await browser.url(url);
-    await appendStep(sessionName, 'navigate', { url }, 'ok', Date.now() - startTime, undefined, sessionsDir);
-    console.log(`Navigated to ${url}`);
+    if (action) {
+      await browser[action](); // This calls browser.refresh() or browser.back() or browser.forward() respectively
+      await appendStep(session, action, {}, 'ok', Date.now() - startTime, undefined, sessionsDir);
+      console.log(`Browser: ${action}`);
+    } else {
+      await browser.url(url);
+      await appendStep(session, 'navigate', { url }, 'ok', Date.now() - startTime, undefined, sessionsDir);
+      console.log(`Navigated to [${url}]`);
+    }
+
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    await appendStep(sessionName, 'navigate', { url }, 'error', Date.now() - startTime, msg, sessionsDir);
-    console.error(`Error navigating to ${url}: ${msg}`);
+    await appendStep(session, action ?? 'navigate', action ? {} : { url }, 'error', Date.now() - startTime, msg, sessionsDir);
+    console.error(`Error: ${msg}`);
   }
 });

tests/commands/navigate.test.ts

@@ -3,12 +3,20 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
 
-const { mockUrl } = vi.hoisted(() => ({
+const { mockUrl, mockRefresh, mockBack, mockForward } = vi.hoisted(() => ({
   mockUrl: vi.fn(),
+  mockRefresh: vi.fn(),
+  mockBack: vi.fn(),
+  mockForward: vi.fn(),
 }));
 
 vi.mock('webdriverio', () => ({
-  attach: vi.fn().mockResolvedValue({ url: mockUrl }),
+  attach: vi.fn().mockResolvedValue({
+    url: mockUrl,
+    refresh: mockRefresh,
+    back: mockBack,
+    forward: mockForward,
+  }),
 }));
 vi.mock('../../src/steps.js', () => ({
   appendStep: vi.fn().mockResolvedValue(undefined),
@@ -37,6 +45,9 @@ describe('navigate command', () => {
     logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
     errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
     mockUrl.mockClear();
+    mockRefresh.mockClear();
+    mockBack.mockClear();
+    mockForward.mockClear();
   });
 
   afterEach(async () => {
@@ -52,6 +63,30 @@ describe('navigate command', () => {
     expect(appendStep).toHaveBeenCalledWith('default', 'navigate', { url: 'https://httpbin.org' }, 'ok', expect.any(Number), undefined, expect.any(String));
   });
 
+  it('should refresh the page', async () => {
+    await handler({ url: 'refresh', session: 'default', _sessionsDir: TEST_DIR } as unknown as Parameters<typeof handler>[0]);
+    expect(mockRefresh).toHaveBeenCalled();
+    expect(mockUrl).not.toHaveBeenCalled();
+    expect(logSpy).toHaveBeenCalledWith('Browser: refresh');
+    expect(appendStep).toHaveBeenCalledWith('default', 'refresh', {}, 'ok', expect.any(Number), undefined, expect.any(String));
+  });
+
+  it('should go back', async () => {
+    await handler({ url: 'back', session: 'default', _sessionsDir: TEST_DIR } as unknown as Parameters<typeof handler>[0]);
+    expect(mockBack).toHaveBeenCalled();
+    expect(mockUrl).not.toHaveBeenCalled();
+    expect(logSpy).toHaveBeenCalledWith('Browser: back');
+    expect(appendStep).toHaveBeenCalledWith('default', 'back', {}, 'ok', expect.any(Number), undefined, expect.any(String));
+  });
+
+  it('should go forward', async () => {
+    await handler({ url: 'forward', session: 'default', _sessionsDir: TEST_DIR } as unknown as Parameters<typeof handler>[0]);
+    expect(mockForward).toHaveBeenCalled();
+    expect(mockUrl).not.toHaveBeenCalled();
+    expect(logSpy).toHaveBeenCalledWith('Browser: forward');
+    expect(appendStep).toHaveBeenCalledWith('default', 'forward', {}, 'ok', expect.any(Number), undefined, expect.any(String));
+  });
+
   it('should record error step when navigation throws', async () => {
     mockUrl.mockRejectedValueOnce(new Error('Navigation failed'));
     await handler({ url: 'https://httpbin.org', session: 'default', _sessionsDir: TEST_DIR } as unknown as Parameters<typeof handler>[0]);
@@ -61,9 +96,23 @@ describe('navigate command', () => {
     expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('Navigation failed'));
   });
 
+  it('should record error step when refresh throws', async () => {
+    mockRefresh.mockRejectedValueOnce(new Error('Refresh failed'));
+    await handler({ url: 'refresh', session: 'default', _sessionsDir: TEST_DIR } as unknown as Parameters<typeof handler>[0]);
+    expect(appendStep).toHaveBeenCalledWith(
+      'default', 'refresh', {}, 'error', expect.any(Number), 'Refresh failed', expect.any(String),
+    );
+  });
+
+  it('should error when no url provided', async () => {
+    await handler({ url: undefined, session: 'default', _sessionsDir: TEST_DIR } as unknown as Parameters<typeof handler>[0]);
+    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('URL or action required'));
+    expect(mockUrl).not.toHaveBeenCalled();
+  });
+
   it('should error when no session exists', async () => {
     await handler({ url: 'https://httpbin.org', session: 'nonexistent', _sessionsDir: TEST_DIR } as unknown as Parameters<typeof handler>[0]);
     expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('No active session'));
     expect(mockUrl).not.toHaveBeenCalled();
   });
-});
+});