@epsilon-asi/actors 0.0.1

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

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest';
+import { GhostCursorAdapter } from '../../../src/interaction/GhostCursorAdapter.js';
+import { FakeGhostCursor } from '../../fixtures/FakeCursor.js';
+import { FakePage } from '../../fixtures/FakePage.js';
+
+describe('GhostCursorAdapter', () => {
+  it('delegates clicks to ghost-cursor after waiting for the selector', async () => {
+    const page = new FakePage().setSelector('#button');
+    const cursor = new FakeGhostCursor();
+    const adapter = new GhostCursorAdapter(page, { cursor });
+
+    await adapter.click('#button', { cursorOptions: { waitForClick: 100 } });
+
+    expect(page.waitedSelectors[0]?.selector).toBe('#button');
+    expect(cursor.clicks).toEqual([{ selector: '#button', options: { waitForClick: 100 } }]);
+  });
+
+  it('delegates moves to ghost-cursor', async () => {
+    const page = new FakePage().setSelector('#target');
+    const cursor = new FakeGhostCursor();
+    const adapter = new GhostCursorAdapter(page, { cursor });
+
+    await adapter.move('#target', { cursorOptions: { moveSpeed: 700 } });
+
+    expect(cursor.moves).toEqual([{ selector: '#target', options: { moveSpeed: 700 } }]);
+  });
+
+  it('types by clicking, selecting/deleting existing content, then sending keys one by one', async () => {
+    const page = new FakePage().setSelector('#email', { value: 'old' });
+    const cursor = new FakeGhostCursor();
+    const sleeps: number[] = [];
+    const adapter = new GhostCursorAdapter(page, {
+      cursor,
+      random: () => 0.5,
+      sleep: async ms => { sleeps.push(ms); },
+      typing: { intervalJitterMs: 0 }
+    });
+
+    await adapter.type('#email', 'new', { delayMs: 5 });
+
+    expect(cursor.clicks.map(click => click.selector)).toContain('#email');
+    expect(page.keyboard.pressed).toEqual([{ key: 'Backspace' }]);
+    expect(page.keyboard.typed).toEqual([
+      { text: 'n', options: { delay: 5 } },
+      { text: 'e', options: { delay: 5 } },
+      { text: 'w', options: { delay: 5 } }
+    ]);
+    expect(sleeps).toEqual([185, 185]);
+  });
+
+  it('can disable human typing and send the whole value at once', async () => {
+    const page = new FakePage().setSelector('#email', { value: 'old' });
+    const cursor = new FakeGhostCursor();
+    const adapter = new GhostCursorAdapter(page, { cursor });
+
+    await adapter.type('#email', 'new@example.com', { delayMs: 5, typing: { enabled: false } });
+
+    expect(page.keyboard.typed).toEqual([{ text: 'new@example.com', options: { delay: 5 } }]);
+  });
+
+  it('scrolls an element into view', async () => {
+    const page = new FakePage().setSelector('#item');
+    const cursor = new FakeGhostCursor();
+    const adapter = new GhostCursorAdapter(page, { cursor });
+
+    await expect(adapter.scrollIntoView('#item')).resolves.toBeUndefined();
+  });
+});

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

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+import {
+  characterIntervalMsForWordsPerMinute,
+  HumanTyper,
+  jitteredIntervalMs,
+  normalizeHumanTypingOptions
+} from '../../../src/interaction/HumanTyping.js';
+import { FakeKeyboard } from '../../fixtures/FakePage.js';
+
+describe('HumanTyper', () => {
+  it('computes the 65 WPM cadence using five-character words', () => {
+    expect(characterIntervalMsForWordsPerMinute(65, 5)).toBeCloseTo(184.615, 3);
+  });
+
+  it('types key-by-key and waits between characters at approximately 65 WPM', async () => {
+    const keyboard = new FakeKeyboard();
+    const sleeps: number[] = [];
+    const typer = new HumanTyper({
+      random: () => 0.5,
+      sleep: async ms => { sleeps.push(ms); }
+    });
+
+    await typer.type(keyboard, 'abcd', { intervalJitterMs: 0 });
+
+    expect(keyboard.typed.map(record => record.text)).toEqual(['a', 'b', 'c', 'd']);
+    expect(sleeps).toEqual([185, 185, 185]);
+  });
+
+  it('applies small symmetric jitter to the inter-key interval', () => {
+    const base = characterIntervalMsForWordsPerMinute(65, 5);
+
+    expect(jitteredIntervalMs(base, 18, 20, () => 0)).toBe(167);
+    expect(jitteredIntervalMs(base, 18, 20, () => 0.5)).toBe(185);
+    expect(jitteredIntervalMs(base, 18, 20, () => 1)).toBe(203);
+  });
+
+  it('can fall back to bulk Puppeteer typing when human typing is disabled', async () => {
+    const keyboard = new FakeKeyboard();
+    const sleeps: number[] = [];
+    const typer = new HumanTyper({
+      sleep: async ms => { sleeps.push(ms); }
+    });
+
+    await typer.type(keyboard, 'hello', { enabled: false }, 7);
+
+    expect(keyboard.typed).toEqual([{ text: 'hello', options: { delay: 7 } }]);
+    expect(sleeps).toEqual([]);
+  });
+
+  it('validates typing configuration', () => {
+    expect(() => normalizeHumanTypingOptions({ targetWordsPerMinute: 0 })).toThrow(RangeError);
+    expect(() => normalizeHumanTypingOptions({ intervalJitterMs: -1 })).toThrow(RangeError);
+  });
+});

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

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { NativePuppeteerInteractor } from '../../../src/interaction/NativePuppeteerInteractor.js';
+import { FakePage } from '../../fixtures/FakePage.js';
+
+describe('NativePuppeteerInteractor', () => {
+  it('uses the same key-by-key typing and select-delete clear behavior without ghost-cursor', async () => {
+    const page = new FakePage().setSelector('#field', { value: 'old' });
+    const sleeps: number[] = [];
+    const interactor = new NativePuppeteerInteractor(page, {
+      random: () => 0.5,
+      sleep: async ms => { sleeps.push(ms); },
+      typing: { intervalJitterMs: 0 }
+    });
+
+    await interactor.type('#field', 'ok');
+
+    expect(page.clicked).toEqual(['#field']);
+    expect(page.keyboard.pressed).toEqual([{ key: 'Backspace' }]);
+    expect(page.keyboard.typed.map(record => record.text)).toEqual(['o', 'k']);
+    expect(sleeps).toEqual([185]);
+  });
+});

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

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+import { PuppeteerPageAdapter } from '../../../src/interaction/PageAdapter.js';
+import { FakePage } from '../../fixtures/FakePage.js';
+
+describe('PuppeteerPageAdapter', () => {
+  it('normalizes text content', async () => {
+    const fakePage = new FakePage().setSelector('#title', { textContent: '  Hello\n   World  ' });
+    const page = new PuppeteerPageAdapter(fakePage);
+
+    await expect(page.text('#title')).resolves.toBe('Hello World');
+  });
+
+  it('returns false when exists times out', async () => {
+    const page = new PuppeteerPageAdapter(new FakePage());
+
+    await expect(page.exists('#missing')).resolves.toBe(false);
+  });
+
+  it('reads attributes', async () => {
+    const fakePage = new FakePage().setSelector('a', { attributes: { href: '/x' } });
+    const page = new PuppeteerPageAdapter(fakePage);
+
+    await expect(page.attr('a', 'href')).resolves.toBe('/x');
+  });
+});

package/tests/unit/logging/redact.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import { redact } from '../../../src/utils/redact.js';
+
+describe('redact', () => {
+  it('redacts nested sensitive values without mutating the original object', () => {
+    const input = {
+      username: 'alice',
+      password: 'secret',
+      nested: {
+        authorization: 'Bearer token',
+        safe: 'value'
+      },
+      items: [
+        { sessionCookie: 'abc123' },
+        { name: 'visible' }
+      ]
+    };
+
+    const output = redact(input);
+
+    expect(output).toEqual({
+      username: 'alice',
+      password: '[REDACTED]',
+      nested: {
+        authorization: '[REDACTED]',
+        safe: 'value'
+      },
+      items: [
+        { sessionCookie: '[REDACTED]' },
+        { name: 'visible' }
+      ]
+    });
+    expect(input.password).toBe('secret');
+    expect(input.nested.authorization).toBe('Bearer token');
+  });
+});

package/tests/unit/sites/myvistage-com.actor.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { myvistageComActor } from '../../../src/sites/myvistage-com/myvistage-com.actor.js';
+
+describe('myvistageComActor', () => {
+  it('has expected metadata', () => {
+    expect(myvistageComActor.id).toBe('myvistage-com');
+    expect(myvistageComActor.baseUrl).toBe('https://myvistage.com');
+  });
+
+  it('ping task returns ok with null echo by default', async () => {
+    const output = await myvistageComActor.tasks.ping({} as never, {});
+    expect(output).toEqual({ ok: true, echo: null });
+  });
+
+  it('ping task echoes provided message', async () => {
+    const output = await myvistageComActor.tasks.ping({} as never, { message: 'hello' });
+    expect(output).toEqual({ ok: true, echo: 'hello' });
+  });
+});

package/tests/unit/sites/myvistage-com.login.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { myvistageComActor } from '../../../src/sites/myvistage-com/myvistage-com.actor.js';
+import { myvistageComSelectors } from '../../../src/sites/myvistage-com/myvistage-com.selectors.js';
+
+describe('myvistage-com actor login flow', () => {
+  it('uses a one-page username/password login definition', () => {
+    const auth = myvistageComActor.auth;
+
+    expect(auth).toBeDefined();
+    expect(auth?.loginUrl).toBe('https://myvistage.com');
+    expect(auth?.credentials).toEqual({ id: 'myvistage-com' });
+    expect(auth?.selectors).toEqual(myvistageComSelectors.login);
+    expect(auth?.steps).toBeUndefined();
+  });
+
+  it('keeps human-like typing behavior configured at the flow level', () => {
+    expect(myvistageComActor.auth?.behavior?.typing).toEqual({
+      targetWordsPerMinute: 65,
+      intervalJitterMs: 18
+    });
+  });
+});

package/tests/unit/sites/myvistage-com.postComment.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest';
+import { myvistageComActor } from '../../../src/sites/myvistage-com/myvistage-com.actor.js';
+import { myvistageComSelectors } from '../../../src/sites/myvistage-com/myvistage-com.selectors.js';
+import { makeContext } from '../../fixtures/makeContext.js';
+
+describe('myvistage-com actor postComment task', () => {
+  it('fills fields in order, submits the form, and returns completion output', async () => {
+    const { context, fakePage, fakeInteractor } = makeContext({
+      actorId: 'myvistage-com',
+      baseUrl: 'https://myvistage.com'
+    });
+
+    fakePage
+      .setSelector(myvistageComSelectors.postComment.comment)
+      .setSelector(myvistageComSelectors.postComment.subject)
+      .setSelector(myvistageComSelectors.postComment.submit);
+
+    const result = await myvistageComActor.tasks.postComment(context, {
+      comment: 'Great insights, thank you for sharing.',
+      subject: 'Quick follow-up'
+    });
+
+    expect(fakePage.gotos[0]?.url).toBe('https://myvistage.com/?status/151341-151341-1779377493/');
+    expect(fakeInteractor.typed).toEqual([
+      {
+        selector: myvistageComSelectors.postComment.comment,
+        value: 'Great insights, thank you for sharing.',
+        options: { required: true }
+      },
+      {
+        selector: myvistageComSelectors.postComment.subject,
+        value: 'Quick follow-up',
+        options: { required: false }
+      }
+    ]);
+    expect(fakeInteractor.clicks).toEqual([{ selector: myvistageComSelectors.postComment.submit }]);
+    expect(result).toEqual({
+      submittedComment: 'Great insights, thank you for sharing.',
+      submittedSubject: 'Quick follow-up'
+    });
+  });
+
+  it('skips optional fields when not provided and still submits', async () => {
+    const { context, fakePage, fakeInteractor } = makeContext({
+      actorId: 'myvistage-com',
+      baseUrl: 'https://myvistage.com'
+    });
+
+    fakePage
+      .setSelector(myvistageComSelectors.postComment.comment)
+      .setSelector(myvistageComSelectors.postComment.submit);
+
+    const result = await myvistageComActor.tasks.postComment(context, {
+      comment: 'Posting without a subject.'
+    });
+
+    expect(fakeInteractor.typed).toEqual([
+      {
+        selector: myvistageComSelectors.postComment.comment,
+        value: 'Posting without a subject.',
+        options: { required: true }
+      }
+    ]);
+    expect(fakeInteractor.clicks).toEqual([{ selector: myvistageComSelectors.postComment.submit }]);
+    expect(result).toEqual({
+      submittedComment: 'Posting without a subject.',
+      submittedSubject: null
+    });
+  });
+});

package/tests/unit/sites/upwork-com.login.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+import { upworkComActor } from '../../../src/sites/upwork-com/upwork-com.actor.js';
+import { upworkComSelectors } from '../../../src/sites/upwork-com/upwork-com.selectors.js';
+
+describe('upwork-com actor login flow', () => {
+  it('uses a staged username-first/password-second login definition', () => {
+    const auth = upworkComActor.auth;
+
+    expect(auth).toBeDefined();
+    expect(auth?.loginUrl).toBe('https://www.upwork.com/ab/account-security/login');
+    expect(auth?.credentials).toEqual({ id: 'upwork' });
+    expect(auth?.selectors.loggedInSignal).toBe(upworkComSelectors.login.loggedInSignal);
+    expect(auth?.selectors.errorMessage).toBe(upworkComSelectors.login.errorMessage);
+
+    expect(auth?.steps).toEqual([
+      {
+        type: 'fill',
+        name: 'username',
+        selector: upworkComSelectors.login.username,
+        credential: 'username'
+      },
+      {
+        type: 'click',
+        name: 'continue to password',
+        selector: upworkComSelectors.login.continueToPassword,
+        waitForSelector: upworkComSelectors.login.password,
+        waitForSelectorTimeoutMs: 5_000
+      },
+      {
+        type: 'fill',
+        name: 'password',
+        selector: upworkComSelectors.login.password,
+        credential: 'password'
+      },
+      {
+        type: 'click',
+        name: 'submit password',
+        selector: upworkComSelectors.login.submit,
+        submit: true,
+        waitForNavigation: true,
+        checkForError: false
+      }
+    ]);
+  });
+
+  it('keeps human-like typing behavior configured at the flow level', () => {
+    expect(upworkComActor.auth?.behavior?.typing).toEqual({
+      targetWordsPerMinute: 65,
+      intervalJitterMs: 18
+    });
+  });
+});

package/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["tests", "dist", "node_modules", "vitest.config.ts"]
+}

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022", "DOM"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "rootDir": ".",
+    "types": ["node", "vitest/globals"]
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts", "vitest.config.ts"],
+  "exclude": ["dist", "node_modules"]
+}

package/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    globals: true,
+    include: ['tests/**/*.test.ts'],
+    restoreMocks: true,
+    clearMocks: true,
+    mockReset: true
+  }
+});