@epsilon-asi/actors 0.0.1 → 0.0.3

package/tests/unit/core/ActorRunner.test.ts

@@ -1,370 +0,0 @@
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { describe, expect, it } from 'vitest';
-import type { LoginFlowDefinition } from '../../../src/auth/LoginFlow.types.js';
-import { BrowserFactory } from '../../../src/browser/BrowserFactory.js';
-import { BrowserSession } from '../../../src/browser/BrowserSession.js';
-import type { RuntimeConfig } from '../../../src/browser/RuntimeConfig.js';
-import { defineActor } from '../../../src/core/defineActor.js';
-import { ActorRunner, ActorSequenceRunner } from '../../../src/core/ActorRunner.js';
-import { defineFormTask } from '../../../src/core/Actor.js';
-import { AutomationError } from '../../../src/errors/AutomationError.js';
-import { PuppeteerPageAdapter } from '../../../src/interaction/PageAdapter.js';
-import { MemoryLogger } from '../../../src/logging/MemoryLogger.js';
-import { FakeHumanInteractor } from '../../fixtures/FakeCursor.js';
-import { FakeBrowser, FakePage } from '../../fixtures/FakePage.js';
-
-class StaticBrowserFactory extends BrowserFactory {
-  launchCalls = 0;
-
-  constructor(private readonly session: BrowserSession) {
-    super();
-  }
-
-  override async launch(): Promise<BrowserSession> {
-    this.launchCalls += 1;
-    return this.session;
-  }
-}
-
-class FakeLoginFlow {
-  ensureAuthenticatedCalls: LoginFlowDefinition[] = [];
-
-  async ensureAuthenticated(_context: unknown, definition: LoginFlowDefinition): Promise<void> {
-    this.ensureAuthenticatedCalls.push(definition);
-  }
-}
-
-function createConfig(closeBrowserOnFinish = true): RuntimeConfig {
-  const userDataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'paf-runner-'));
-  fs.mkdirSync(path.join(userDataDir, 'Default'));
-  return {
-    browser: {
-      mode: 'existing-profile',
-      userDataDir,
-      profileDirectory: 'Default',
-      headless: false,
-      closeBrowserOnFinish
-    }
-  };
-}
-
-function createRemoteConfig(options: { closeBrowserOnFinish?: boolean; disconnectOnFinish?: boolean } = {}): RuntimeConfig {
-  return {
-    browser: {
-      mode: 'remote-debugging',
-      browserURL: 'http://127.0.0.1:9222',
-      ...options
-    }
-  };
-}
-
-function createRunnerParts(closeBrowserOnFinish = true, overrideConfig?: RuntimeConfig): {
-  runner: ActorRunner;
-  page: FakePage;
-  browser: FakeBrowser;
-  browserFactory: StaticBrowserFactory;
-  loginFlow: FakeLoginFlow;
-  interactor: FakeHumanInteractor;
-} {
-  const config = overrideConfig ?? createConfig(closeBrowserOnFinish);
-  const page = new FakePage();
-  const browser = new FakeBrowser([page]);
-  const session = new BrowserSession(browser, browser.context, page, config.browser, config.browser.mode === 'remote-debugging' ? 'connected' : 'launched');
-  const browserFactory = new StaticBrowserFactory(session);
-  const loginFlow = new FakeLoginFlow();
-  const interactor = new FakeHumanInteractor();
-  const runner = new ActorRunner({
-    config,
-    browserFactory,
-    loginFlow: loginFlow as never,
-    logger: new MemoryLogger(),
-    interactorFactory: () => interactor,
-    pageAdapterFactory: pageLike => new PuppeteerPageAdapter(pageLike)
-  });
-  return { runner, page, browser, browserFactory, loginFlow, interactor };
-}
-
-function createSequenceRunnerParts(closeBrowserOnFinish = true, overrideConfig?: RuntimeConfig): {
-  runner: ActorSequenceRunner;
-  page: FakePage;
-  browser: FakeBrowser;
-  browserFactory: StaticBrowserFactory;
-  loginFlow: FakeLoginFlow;
-} {
-  const config = overrideConfig ?? createConfig(closeBrowserOnFinish);
-  const page = new FakePage();
-  const browser = new FakeBrowser([page]);
-  const session = new BrowserSession(browser, browser.context, page, config.browser, config.browser.mode === 'remote-debugging' ? 'connected' : 'launched');
-  const browserFactory = new StaticBrowserFactory(session);
-  const loginFlow = new FakeLoginFlow();
-  const runner = new ActorSequenceRunner({
-    config,
-    browserFactory,
-    loginFlow: loginFlow as never,
-    logger: new MemoryLogger(),
-    interactorFactory: () => new FakeHumanInteractor(),
-    pageAdapterFactory: pageLike => new PuppeteerPageAdapter(pageLike)
-  });
-  return { runner, page, browser, browserFactory, loginFlow };
-}
-
-describe('ActorRunner', () => {
-  const auth = {
-    loginUrl: '/login',
-    selectors: {
-      username: '#email',
-      password: '#password',
-      submit: '#submit',
-      loggedInSignal: '#account'
-    },
-    credentials: { id: 'example' }
-  } satisfies LoginFlowDefinition;
-
-  it('creates actor context and runs the selected task', async () => {
-    const { runner, browserFactory, browser } = createRunnerParts();
-    const actor = defineActor({
-      id: 'example',
-      baseUrl: 'https://example.com',
-      tasks: {
-        hello: async context => ({ actorId: context.actor.id, url: context.page.url() })
-      }
-    });
-
-    const result = await runner.run(actor, 'hello');
-
-    expect(result).toEqual({ actorId: 'example', url: 'about:blank' });
-    expect(browserFactory.launchCalls).toBe(1);
-    expect(browser.closeCalls).toHaveLength(1);
-  });
-
-  it('runs auth when the actor defines a login flow', async () => {
-    const { runner, loginFlow } = createRunnerParts();
-    const actor = defineActor({
-      id: 'example',
-      baseUrl: 'https://example.com',
-      auth,
-      tasks: {
-        scrape: async () => 'done'
-      }
-    });
-
-    await expect(runner.run(actor, 'scrape')).resolves.toBe('done');
-    expect(loginFlow.ensureAuthenticatedCalls).toEqual([auth]);
-  });
-
-  it('runs generated form tasks against actor context services', async () => {
-    const { runner, page, interactor } = createRunnerParts();
-    page
-      .setSelector('#name')
-      .setSelector('#email')
-      .setSelector('#submit');
-
-    const actor = defineActor({
-      id: 'example',
-      baseUrl: 'https://example.com',
-      tasks: {
-        submitContact: defineFormTask<{ name: string; email: string }, { submitted: string }>({
-          url: '/contact',
-          fields: [
-            { selector: '#name', inputKey: 'name' },
-            { selector: '#email', inputKey: 'email' }
-          ],
-          submit: {
-            selector: '#submit',
-            waitForNavigation: true
-          },
-          onComplete: (_context, input) => ({ submitted: input.email })
-        })
-      }
-    });
-
-    const result = await runner.run(actor, 'submitContact', {
-      name: 'Jane Doe',
-      email: 'jane@example.com'
-    });
-
-    expect(result).toEqual({ submitted: 'jane@example.com' });
-    expect(page.gotos[0]?.url).toBe('https://example.com/contact');
-    expect(interactor.typed).toEqual([
-      { selector: '#name', value: 'Jane Doe', options: { required: true } },
-      { selector: '#email', value: 'jane@example.com', options: { required: true } }
-    ]);
-    expect(interactor.clicks).toEqual([{ selector: '#submit' }]);
-    expect(page.waitedNavigations).toHaveLength(1);
-  });
-
-  it('disconnects a launched browser without closing when closeBrowserOnFinish is false', async () => {
-    const { runner, browser } = createRunnerParts(false);
-    const actor = defineActor({
-      id: 'example',
-      baseUrl: 'https://example.com',
-      tasks: {
-        noop: async () => undefined
-      }
-    });
-
-    await runner.run(actor, 'noop');
-
-    expect(browser.closeCalls).toHaveLength(0);
-    expect(browser.disconnectCalls).toHaveLength(1);
-  });
-
-  it('disconnects from a shared connected browser by default without closing Chrome', async () => {
-    const { runner, browser } = createRunnerParts(true, createRemoteConfig());
-    const actor = defineActor({
-      id: 'example',
-      baseUrl: 'https://example.com',
-      tasks: {
-        noop: async () => undefined
-      }
-    });
-
-    await runner.run(actor, 'noop');
-
-    expect(browser.disconnectCalls).toHaveLength(1);
-    expect(browser.closeCalls).toHaveLength(0);
-  });
-
-  it('can close the connected browser when explicitly configured', async () => {
-    const { runner, browser } = createRunnerParts(true, createRemoteConfig({ closeBrowserOnFinish: true, disconnectOnFinish: false }));
-    const actor = defineActor({
-      id: 'example',
-      baseUrl: 'https://example.com',
-      tasks: {
-        noop: async () => undefined
-      }
-    });
-
-    await runner.run(actor, 'noop');
-
-    expect(browser.closeCalls).toHaveLength(1);
-    expect(browser.disconnectCalls).toHaveLength(0);
-  });
-
-  it('wraps task failures with actor metadata and still closes the browser', async () => {
-    const { runner, browser } = createRunnerParts();
-    const actor = defineActor({
-      id: 'example',
-      baseUrl: 'https://example.com',
-      tasks: {
-        explode: async () => {
-          throw new Error('boom');
-        }
-      }
-    });
-
-    await expect(runner.run(actor, 'explode')).rejects.toMatchObject({
-      name: 'AutomationError',
-      actorId: 'example',
-      taskName: 'explode'
-    } satisfies Partial<AutomationError>);
-    expect(browser.closeCalls).toHaveLength(1);
-  });
-
-  it('calls actor hooks around task execution', async () => {
-    const calls: string[] = [];
-    const { runner } = createRunnerParts();
-    const actor = defineActor({
-      id: 'example',
-      baseUrl: 'https://example.com',
-      hooks: {
-        beforeRun: () => { calls.push('before'); },
-        afterRun: () => { calls.push('after'); }
-      },
-      tasks: {
-        task: async () => 'ok'
-      }
-    });
-
-    await runner.run(actor, 'task');
-
-    expect(calls).toEqual(['before', 'after']);
-  });
-});
-
-describe('ActorSequenceRunner', () => {
-  const auth = {
-    loginUrl: '/login',
-    selectors: {
-      username: '#email',
-      password: '#password',
-      submit: '#submit',
-      loggedInSignal: '#account'
-    },
-    credentials: { id: 'example' }
-  } satisfies LoginFlowDefinition;
-
-  it('runs a series of tasks in a single browser session', async () => {
-    const calls: string[] = [];
-    const { runner, browserFactory, browser } = createSequenceRunnerParts();
-    const actor = defineActor({
-      id: 'example',
-      baseUrl: 'https://example.com',
-      tasks: {
-        first: async () => {
-          calls.push('first');
-          return 'one';
-        },
-        second: async () => {
-          calls.push('second');
-          return 'two';
-        }
-      }
-    });
-
-    const result = await runner.runSequence(actor, ['first', 'second']);
-
-    expect(result).toEqual(['one', 'two']);
-    expect(calls).toEqual(['first', 'second']);
-    expect(browserFactory.launchCalls).toBe(1);
-    expect(browser.closeCalls).toHaveLength(1);
-  });
-
-  it('runs authentication once before the first sequence step', async () => {
-    const { runner, loginFlow } = createSequenceRunnerParts();
-    const actor = defineActor({
-      id: 'example',
-      baseUrl: 'https://example.com',
-      auth,
-      tasks: {
-        a: async () => 'a',
-        b: async () => 'b'
-      }
-    });
-
-    await runner.runSequence(actor, ['a', 'b']);
-
-    expect(loginFlow.ensureAuthenticatedCalls).toEqual([auth]);
-  });
-
-  it('calls hooks for each step and wraps errors with the failing task name', async () => {
-    const calls: string[] = [];
-    const { runner, browser } = createSequenceRunnerParts();
-    const actor = defineActor({
-      id: 'example',
-      baseUrl: 'https://example.com',
-      hooks: {
-        beforeRun: (_context, taskName) => { calls.push(`before:${taskName}`); },
-        afterRun: (_context, taskName) => { calls.push(`after:${taskName}`); },
-        onError: (_context, taskName) => { calls.push(`error:${taskName}`); }
-      },
-      tasks: {
-        first: async () => 'ok',
-        second: async () => {
-          throw new Error('boom');
-        }
-      }
-    });
-
-    await expect(runner.runSequence(actor, ['first', 'second'])).rejects.toMatchObject({
-      name: 'AutomationError',
-      actorId: 'example',
-      taskName: 'second'
-    } satisfies Partial<AutomationError>);
-
-    expect(calls).toEqual(['before:first', 'after:first', 'before:second', 'error:second']);
-    expect(browser.closeCalls).toHaveLength(1);
-  });
-});

package/tests/unit/core/defineActor.test.ts

@@ -1,112 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { ActorRegistry } from '../../../src/core/ActorRegistry.js';
-import { defineActor } from '../../../src/core/defineActor.js';
-import { defineFormFillerTask, defineFormTask } from '../../../src/core/Actor.js';
-import { ConfigError } from '../../../src/errors/ConfigError.js';
-import { makeContext } from '../../fixtures/makeContext.js';
-
-describe('defineActor and ActorRegistry', () => {
-  it('preserves actor definitions and registers them by id', () => {
-    const actor = defineActor({
-      id: 'example',
-      baseUrl: 'https://example.com',
-      tasks: {
-        test: async () => 'ok'
-      }
-    });
-
-    const registry = new ActorRegistry().register(actor);
-
-    expect(registry.get('example')).toBe(actor);
-    expect(registry.list()).toEqual([actor]);
-  });
-
-  it('rejects duplicate actor ids', () => {
-    const actor = defineActor({
-      id: 'example',
-      baseUrl: 'https://example.com',
-      tasks: {}
-    });
-    const registry = new ActorRegistry().register(actor);
-
-    expect(() => registry.register(actor)).toThrow(ConfigError);
-  });
-});
-
-describe('defineFormTask', () => {
-  it('creates a task that fills listed fields and submits the form from input data', async () => {
-    const { context, fakePage, fakeInteractor } = makeContext();
-    fakePage
-      .setSelector('#name')
-      .setSelector('#email')
-      .setSelector('#submit');
-
-    const task = defineFormTask<{ name: string; email: string }, { submittedEmail: string }>({
-      url: '/contact',
-      fields: [
-        { selector: '#name', inputKey: 'name' },
-        { selector: '#email', inputKey: 'email' }
-      ],
-      submit: {
-        selector: '#submit',
-        waitForNavigation: true
-      },
-      onComplete: (_ctx, input) => ({ submittedEmail: input.email })
-    });
-
-    const result = await task(context, {
-      name: 'Jane Doe',
-      email: 'jane@example.com'
-    });
-
-    expect(result).toEqual({ submittedEmail: 'jane@example.com' });
-    expect(fakePage.gotos[0]?.url).toBe('https://example.com/contact');
-    expect(fakeInteractor.typed).toEqual([
-      { selector: '#name', value: 'Jane Doe', options: { required: true } },
-      { selector: '#email', value: 'jane@example.com', options: { required: true } }
-    ]);
-    expect(fakeInteractor.clicks).toEqual([{ selector: '#submit' }]);
-    expect(fakePage.waitedNavigations).toHaveLength(1);
-  });
-
-  it('supports literal/resolved field values and the defineFormFillerTask alias', async () => {
-    const { context, fakePage, fakeInteractor } = makeContext();
-    fakePage
-      .setSelector('#first')
-      .setSelector('#last')
-      .setSelector('#submit');
-
-    const task = defineFormFillerTask<{ firstName: string; lastName: string }>({
-      fields: [
-        { selector: '#first', inputKey: 'firstName' },
-        { selector: '#last', value: input => input.lastName.toUpperCase() }
-      ],
-      submit: { selector: '#submit' }
-    });
-
-    await task(context, {
-      firstName: 'Jane',
-      lastName: 'Doe'
-    });
-
-    expect(fakeInteractor.typed).toEqual([
-      { selector: '#first', value: 'Jane', options: { required: true } },
-      { selector: '#last', value: 'DOE', options: { required: true } }
-    ]);
-    expect(fakeInteractor.clicks).toEqual([{ selector: '#submit' }]);
-  });
-
-  it('throws when a required field has no input value', async () => {
-    const { context, fakePage } = makeContext();
-    fakePage
-      .setSelector('#name')
-      .setSelector('#submit');
-
-    const task = defineFormTask<{ name?: string }>({
-      fields: [{ selector: '#name', inputKey: 'name' }],
-      submit: { selector: '#submit' }
-    });
-
-    await expect(task(context, {})).rejects.toThrow('missing a value');
-  });
-});

package/tests/unit/extraction/Extractor.test.ts

@@ -1,48 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { Extractor } from '../../../src/extraction/Extractor.js';
-import { PuppeteerPageAdapter } from '../../../src/interaction/PageAdapter.js';
-import { FakePage } from '../../fixtures/FakePage.js';
-
-describe('Extractor', () => {
-  it('extracts single text and text lists', async () => {
-    const fakePage = new FakePage()
-      .setSelector('#title', { textContent: ' Title ' })
-      .setTextList('.row', [' One ', 'Two', '   ']);
-    const extractor = new Extractor(new PuppeteerPageAdapter(fakePage));
-
-    await expect(extractor.text('#title')).resolves.toBe('Title');
-    await expect(extractor.textList('.row')).resolves.toEqual(['One', 'Two']);
-  });
-
-  it('extracts attributes and href lists', async () => {
-    const fakePage = new FakePage()
-      .setSelector('#link', { attributes: { href: '/single' } });
-    fakePage.selectorLists.set('a', [
-      { attributes: { href: '/a' } },
-      { attributes: { href: '/b' } },
-      { attributes: {} }
-    ]);
-    const extractor = new Extractor(new PuppeteerPageAdapter(fakePage));
-
-    await expect(extractor.attr('#link', 'href')).resolves.toBe('/single');
-    await expect(extractor.hrefs('a')).resolves.toEqual(['/a', '/b']);
-  });
-
-  it('extracts table rows into objects', async () => {
-    const fakePage = new FakePage().setSelector('table', {
-      attributes: {
-        __headers: 'Name|Amount',
-        __rows: 'Alice|10\nBob|20'
-      }
-    });
-    const extractor = new Extractor(new PuppeteerPageAdapter(fakePage));
-
-    await expect(extractor.table('table')).resolves.toEqual({
-      headers: ['Name', 'Amount'],
-      rows: [
-        { Name: 'Alice', Amount: '10' },
-        { Name: 'Bob', Amount: '20' }
-      ]
-    });
-  });
-});

package/tests/unit/extraction/Pagination.test.ts

@@ -1,54 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { Pagination } from '../../../src/extraction/Pagination.js';
-import { PuppeteerPageAdapter } from '../../../src/interaction/PageAdapter.js';
-import { FakeHumanInteractor } from '../../fixtures/FakeCursor.js';
-import { FakePage } from '../../fixtures/FakePage.js';
-
-describe('Pagination', () => {
-  it('collects pages until the next selector is missing', async () => {
-    const fakePage = new FakePage().setSelector('#next');
-    const interactor = new FakeHumanInteractor();
-    const pagination = new Pagination(new PuppeteerPageAdapter(fakePage), interactor);
-    let pageNumber = 0;
-
-    const result = await pagination.collectPages({
-      nextSelector: '#next',
-      extractPage: async () => {
-        pageNumber += 1;
-        if (pageNumber === 2) fakePage.removeSelector('#next');
-        return [`page-${pageNumber}`];
-      }
-    });
-
-    expect(result).toEqual(['page-1', 'page-2']);
-    expect(interactor.clicks.map(click => click.selector)).toEqual(['#next']);
-  });
-
-  it('respects maxPages', async () => {
-    const fakePage = new FakePage().setSelector('#next');
-    const interactor = new FakeHumanInteractor();
-    const pagination = new Pagination(new PuppeteerPageAdapter(fakePage), interactor);
-
-    const result = await pagination.collectPages({
-      nextSelector: '#next',
-      maxPages: 2,
-      extractPage: async () => ['item']
-    });
-
-    expect(result).toEqual(['item', 'item']);
-    expect(interactor.clicks).toHaveLength(1);
-  });
-
-  it('deduplicates collected items when configured', async () => {
-    const fakePage = new FakePage();
-    const pagination = new Pagination(new PuppeteerPageAdapter(fakePage), new FakeHumanInteractor());
-
-    const result = await pagination.collectPages({
-      nextSelector: '#next',
-      extractPage: async () => [{ id: '1' }, { id: '1' }],
-      dedupeBy: item => item.id
-    });
-
-    expect(result).toEqual([{ id: '1' }]);
-  });
-});

package/tests/unit/interaction/FieldClearer.test.ts

@@ -1,29 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { clearField } from '../../../src/interaction/FieldClearer.js';
-import { FakePage } from '../../fixtures/FakePage.js';
-
-describe('clearField', () => {
-  it('selects field contents and presses Backspace before typing', async () => {
-    const page = new FakePage().setSelector('#email', { value: 'old@example.com' });
-
-    await clearField(page, '#email');
-
-    const state = page.selectors.get('#email');
-    expect(state?.focused).toBe(true);
-    expect(state?.selected).toBe(true);
-    expect(page.keyboard.pressed).toEqual([{ key: 'Backspace' }]);
-    expect(state?.value).toBe('');
-    expect(state?.events).toEqual(expect.arrayContaining(['select', 'input', 'change']));
-  });
-
-  it('supports direct DOM clearing for callers that explicitly request it', async () => {
-    const page = new FakePage().setSelector('#email', { value: 'old@example.com' });
-
-    await clearField(page, '#email', { strategy: 'dom-value' });
-
-    const state = page.selectors.get('#email');
-    expect(page.keyboard.pressed).toEqual([]);
-    expect(state?.value).toBe('');
-    expect(state?.events).toEqual(expect.arrayContaining(['input', 'change']));
-  });
-});

package/tests/unit/interaction/Forms.test.ts

@@ -1,35 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { SelectorError } from '../../../src/errors/SelectorError.js';
-import { FormFiller } from '../../../src/interaction/Forms.js';
-import { PuppeteerPageAdapter } from '../../../src/interaction/PageAdapter.js';
-import { FakeHumanInteractor } from '../../fixtures/FakeCursor.js';
-import { FakePage } from '../../fixtures/FakePage.js';
-
-describe('FormFiller', () => {
-  it('fills text through the configured human interactor', async () => {
-    const page = new FakePage().setSelector('#email');
-    const interactor = new FakeHumanInteractor();
-    const form = new FormFiller(new PuppeteerPageAdapter(page), interactor);
-
-    await form.fillText('#email', 'me@example.com', { delayMs: 10 });
-
-    expect(interactor.typed).toEqual([{ selector: '#email', value: 'me@example.com', options: { delayMs: 10 } }]);
-  });
-
-  it('throws SelectorError for a missing required field', async () => {
-    const page = new FakePage();
-    const form = new FormFiller(new PuppeteerPageAdapter(page), new FakeHumanInteractor());
-
-    await expect(form.fillText('#missing', 'value')).rejects.toBeInstanceOf(SelectorError);
-  });
-
-  it('skips missing optional fields', async () => {
-    const page = new FakePage();
-    const interactor = new FakeHumanInteractor();
-    const form = new FormFiller(new PuppeteerPageAdapter(page), interactor);
-
-    await form.fillText('#missing', 'value', { required: false });
-
-    expect(interactor.typed).toHaveLength(0);
-  });
-});