Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

21.2 KB
Raw Blame
// NativeClipboard asks its channel only where a runner answers it, which a Windows host is not.
@TestOn('!windows')
library;

import 'dart:async';
import 'dart:convert';

import 'package:flutter/foundation.dart';
import 'package:flutter/gestures.dart';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:harness_mobile/core/models.dart';
import 'package:harness_mobile/phone/terminal_paste.dart';
import 'package:harness_mobile/state/app_state.dart';
import 'package:harness_mobile/terminal/terminal_binary.dart';
import 'package:harness_mobile/terminal/terminal_session.dart';
import 'package:harness_mobile/widgets/terminal_panel.dart';
import 'package:xterm/xterm.dart';

import 'terminal_panel_fixture.dart';

/// A hardware keyboard's ⌘V (Ctrl+V on Android) and a right- or middle-click on the terminal, with
/// the pane's paste hooked up the way the phone's page hooks it: to `pasteClipboard`, the path the
/// on-screen Paste takes. They must do exactly what that Paste does — and never hand the far
/// machine a ⌃V, which pasted THAT machine's clipboard rather than this phone's.
///
/// Every other key stays the terminal's, as it was.
void main() {
  final phones = TargetPlatformVariant({
    TargetPlatform.iOS,
    TargetPlatform.android,
  });

  late AppNotifier notifier;
  late _Wire wire;
  late List<String> reports;
  late int hostPastes;

  setUp(() {
    notifier = panelNotifier();
    wire = _Wire();
    reports = [];
    hostPastes = 0;
  });

  tearDown(() => notifier.dispose());

  /// ⚠️ Built inside each test, never in `setUp`: the session's send queue is a Future, and one
  /// made outside the test's fake clock never drains in it.
  TerminalSession session({String engineId = 'claude'}) {
    final made = controllingSession(
      engineId: engineId,
      send: (type, payload) async {
        wire.frames.add((type: type, payload: payload));
        return true;
      },
      sendBinary: (frame) async {
        wire.binaries.add(frame);
        return true;
      },
    );
    addTearDown(made.dispose);
    return made;
  }

  /// The machine the pane's agent runs on, as the phone knows it.
  void machine({bool pasteRaw = false, bool imagePaste = false}) {
    notifier.machineStates['m'] =
        MachineState(
            const Machine(
              machineId: 'm',
              authMode: MachineAuthMode.remote,
              name: 'Studio',
            ),
          )
          ..terminalPasteRawAvailable = pasteRaw
          ..terminalImagePasteAvailable = imagePaste;
  }

  /// A focused pane. [hosted] gives it the paste `TerminalPage._paste` gives it: the phone's own
  /// path, told whether the page still shows this terminal and where to say what happened.
  Future<void> pumpPanel(
    WidgetTester tester,
    TerminalSession pane, {
    bool hosted = true,
  }) async {
    await tester.pumpWidget(
      MaterialApp(
        home: Scaffold(
          body: Align(
            alignment: Alignment.topLeft,
            child: SizedBox(
              width: 400,
              height: 320,
              child: TerminalPanel(
                notifier: notifier,
                session: pane,
                focused: true,
                onPaste: hosted
                    ? () {
                        hostPastes++;
                        unawaited(
                          pasteClipboard(
                            session: pane,
                            machine: notifier.stateOf(pane.machineId),
                            stillShowing: () => true,
                            report: reports.add,
                          ),
                        );
                      }
                    : null,
              ),
            ),
          ),
        ),
      ),
    );
    await tester.pump();
    await tester.pump();
  }

  /// [key] pressed with [modifiers] held, from a hardware keyboard on the phone the test runs as.
  Future<void> chord(
    WidgetTester tester,
    LogicalKeyboardKey key, [
    List<LogicalKeyboardKey> modifiers = const [],
  ]) async {
    final platform = defaultTargetPlatform == TargetPlatform.iOS
        ? 'ios'
        : 'android';
    for (final modifier in modifiers) {
      await tester.sendKeyDownEvent(modifier, platform: platform);
    }
    await tester.sendKeyEvent(key, platform: platform);
    for (final modifier in modifiers.reversed) {
      await tester.sendKeyUpEvent(modifier, platform: platform);
    }
    // Past the session's input coalescing, so every key is on the wire.
    await tester.pump(const Duration(milliseconds: 50));
  }

  /// The paste chord of the phone the test runs as: ⌘V on iOS, Ctrl+V on Android.
  Future<void> pasteChord(WidgetTester tester) =>
      chord(tester, LogicalKeyboardKey.keyV, [
        defaultTargetPlatform == TargetPlatform.iOS
            ? LogicalKeyboardKey.metaLeft
            : LogicalKeyboardKey.controlLeft,
      ]);

  /// A mouse or trackpad click on the terminal with [buttons], away from anything drawn over it.
  Future<void> click(WidgetTester tester, int buttons) async {
    final view = tester.getRect(find.byType(TerminalView));
    await tester.tapAt(
      view.topLeft + const Offset(40, 20),
      buttons: buttons,
      kind: PointerDeviceKind.mouse,
    );
    await tester.pump(const Duration(milliseconds: 50));
  }

  /// Lets the platform's image codec run until [done] holds. Decoding is real work on the engine's
  /// own threads, which the test's fake clock never waits for, so each turn steps out to the real
  /// clock and then pumps what came back.
  Future<void> decodeUntil(WidgetTester tester, bool Function() done) async {
    for (var turn = 0; turn < 200 && !done(); turn++) {
      await tester.runAsync(
        () => Future<void>.delayed(const Duration(milliseconds: 10)),
      );
      await tester.pump();
    }
    expect(done(), isTrue, reason: 'the clipboard image was decoded');
  }

  group('⌘V (Ctrl+V on Android) pastes as the on-screen Paste does', () {
    testWidgets(
      'the text goes out as one paste, asked about before it is read',
      (tester) async {
        final clipboard = _Clipboard(tester)..text = 'git status';
        machine(pasteRaw: true);
        await pumpPanel(tester, session());

        await pasteChord(tester);

        expect(hostPastes, 1);
        expect(wire.pasted, ['git status']);
        expect(wire.input, isNot(contains('\x16')));
        expect(reports, isEmpty);
        // iOS answers `hasStrings` without its "Allow Paste" prompt, so the person is asked once,
        // for the one thing actually read.
        expect(clipboard.methods, [
          'Clipboard.hasStrings',
          'Clipboard.getData',
        ]);
      },
      variant: phones,
    );

    testWidgets('an image over the upload\'s ceiling is scaled down and sent', (
      tester,
    ) async {
      // What iOS hands over for a photo from the library: the image at its own size, past what
      // one upload takes. A real picture, padded past the ceiling with bytes a decoder skips.
      final clipboard = _Clipboard(tester)
        ..image = Uint8List.fromList([
          ..._onePixelPng,
          ...Uint8List(terminalLocalImagePasteMaxPayloadBytes + 1),
        ]);
      machine(imagePaste: true);
      await pumpPanel(tester, session());

      await pasteChord(tester);
      // Until the upload is asked for, or a key went out in its place.
      await decodeUntil(
        tester,
        () => wire.uploadBegin != null || wire.input.isNotEmpty,
      );

      expect(wire.input, isNot(contains('\x16')));
      expect(hostPastes, 1);
      expect(clipboard.imageReads, 1);
      expect(
        wire.uploadBegin!['totalBytes'],
        allOf(greaterThan(0), lessThan(clipboard.image!.length)),
      );
      expect(reports, isEmpty);
      // The upload's own wait for the machine to accept it runs out.
      await tester.pump(const Duration(seconds: 11));
    }, variant: phones);

    testWidgets(
      'an empty clipboard is said, and no ⌃V goes to the far machine',
      (tester) async {
        final clipboard = _Clipboard(tester);
        machine(imagePaste: true);
        await pumpPanel(tester, session());

        await pasteChord(tester);

        expect(wire.input, isNot(contains('\x16')));
        expect(wire.binaries, isEmpty, reason: 'no ⌃V, no paste');
        expect(hostPastes, 1);
        expect(reports, ['There is nothing on the clipboard to paste.']);
        expect(wire.uploadBegin, isNull);
        // No text, so the text was never read — and iOS never asked about it.
        expect(clipboard.methods, isNot(contains('Clipboard.getData')));
      },
      variant: phones,
    );

    testWidgets(
      'an image the phone cannot read is said, and no ⌃V goes instead',
      (tester) async {
        // What the native side answers for an image it found but could not re-encode.
        _Clipboard(tester).image = Uint8List(0);
        machine(imagePaste: true);
        await pumpPanel(tester, session());

        await pasteChord(tester);

        expect(wire.input, isNot(contains('\x16')));
        expect(wire.binaries, isEmpty);
        expect(reports, [
          "The clipboard's image isn't one this phone can read.",
        ]);
        expect(wire.uploadBegin, isNull);
      },
      variant: phones,
    );

    testWidgets(
      'bytes that are not a picture are said to be unreadable, not sent as '
      'they came',
      (tester) async {
        _Clipboard(tester).image = Uint8List.fromList([1, 2, 3, 4]);
        machine(imagePaste: true);
        await pumpPanel(tester, session());

        await pasteChord(tester);
        await decodeUntil(tester, () => reports.isNotEmpty);

        expect(reports, [
          "The clipboard's image isn't one this phone can read.",
        ]);
        expect(wire.uploadBegin, isNull);
        expect(wire.binaries, isEmpty);
      },
      variant: phones,
    );

    testWidgets('a plain shell is not offered the image, and no ⌃V either', (
      tester,
    ) async {
      final clipboard = _Clipboard(tester)..image = _onePixelPng;
      machine(imagePaste: true);
      await pumpPanel(tester, session(engineId: 'terminal'));

      await pasteChord(tester);

      // The CLI delivers an image by replaying ⌃V, which a shell reads as quoted-insert.
      expect(clipboard.imageReads, 0);
      expect(reports, ['There is no text on the clipboard.']);
      expect(wire.binaries, isEmpty);
      expect(wire.uploadBegin, isNull);
    }, variant: phones);

    testWidgets(
      'a terminal that reconnected during the read is not pasted into',
      (tester) async {
        final pane = session();
        _Clipboard(tester)
          ..text = 'git status'
          // The read waits on iOS's prompt, and the stream came back as another one meanwhile.
          ..onRead = () => pane.streamId = 's2';
        machine(pasteRaw: true);
        await pumpPanel(tester, pane);

        await pasteChord(tester);

        expect(wire.pasted, isEmpty);
        expect(reports, [pasteChangedMessage]);
      },
      variant: phones,
    );

    testWidgets(
      'a pane that cannot take input reads nothing and sends nothing',
      (tester) async {
        final clipboard = _Clipboard(tester)..text = 'git status';
        machine(pasteRaw: true);
        final pane = session();
        await pumpPanel(tester, pane);
        pane.status = TerminalSessionStatus.takenOver;

        await pasteChord(tester);

        // Not even read: asked, iOS would raise its "Allow Paste" prompt for a paste that could only
        // be refused. And the key is still taken, so xterm's own paste does not read it either.
        expect(hostPastes, 0);
        expect(clipboard.methods, isEmpty);
        expect(wire.binaries, isEmpty);
        expect(reports, isEmpty);
      },
      variant: phones,
    );
  });

  group('a right- or middle-click', () {
    testWidgets('with nothing selected pastes as ⌘V does', (tester) async {
      _Clipboard(tester).text = 'git status';
      machine(pasteRaw: true);
      await pumpPanel(tester, session());

      await click(tester, kSecondaryMouseButton);

      expect(hostPastes, 1);
      expect(wire.pasted, ['git status']);
      expect(reports, isEmpty);
    }, variant: phones);

    testWidgets('with an empty clipboard says so, and sends no ⌃V', (
      tester,
    ) async {
      _Clipboard(tester);
      machine(imagePaste: true);
      await pumpPanel(tester, session());

      await click(tester, kSecondaryMouseButton);

      expect(wire.input, isNot(contains('\x16')));
      expect(wire.binaries, isEmpty);
      expect(hostPastes, 1);
      expect(reports, ['There is nothing on the clipboard to paste.']);
    }, variant: phones);

    testWidgets('a middle-click pastes the same way', (tester) async {
      _Clipboard(tester).text = 'git status';
      machine(pasteRaw: true);
      await pumpPanel(tester, session());

      await click(tester, kMiddleMouseButton);

      expect(hostPastes, 1);
      expect(wire.pasted, ['git status']);
    }, variant: phones);

    testWidgets('with a selection copies it, and pastes nothing', (
      tester,
    ) async {
      final clipboard = _Clipboard(tester)..text = 'git status';
      machine(pasteRaw: true);
      final pane = session();
      pane.terminal.write('${'\r\n' * 30}npm test\r\nall 42 passed');
      await pumpPanel(tester, pane);
      final view = tester.widget<TerminalView>(find.byType(TerminalView));
      final buffer = pane.terminal.buffer;
      final row = buffer.lines.length - 1;
      view.controller!.setSelection(
        buffer.createAnchor(0, row),
        buffer.createAnchor(13, row),
      );
      await tester.pump();

      await click(tester, kSecondaryMouseButton);

      expect(clipboard.copied, 'all 42 passed');
      expect(view.controller!.selection, isNull);
      expect(hostPastes, 0);
      expect(wire.binaries, isEmpty);
    }, variant: phones);

    testWidgets(
      'on a pane with no paste of its host\'s, pastes only text, and never a ⌃V',
      (tester) async {
        final clipboard = _Clipboard(tester)..image = _onePixelPng;
        machine(pasteRaw: true, imagePaste: true);
        await pumpPanel(tester, session(), hosted: false);

        await click(tester, kSecondaryMouseButton);

        // No text: nothing at all — the image is the host's to send, and a ⌃V would read the far
        // machine's clipboard.
        expect(clipboard.imageReads, 0);
        expect(clipboard.methods, isNot(contains('Clipboard.getData')));
        expect(wire.binaries, isEmpty);
        expect(wire.uploadBegin, isNull);

        clipboard.text = 'git status';
        await click(tester, kSecondaryMouseButton);

        expect(wire.pasted, ['git status']);
      },
      variant: phones,
    );
  });

  group('every other key is the terminal\'s, as it was', () {
    testWidgets('Ctrl+C interrupts', (tester) async {
      final clipboard = _Clipboard(tester)..text = 'git status';
      machine(pasteRaw: true);
      await pumpPanel(tester, session());

      await chord(tester, LogicalKeyboardKey.keyC, [
        LogicalKeyboardKey.controlLeft,
      ]);

      expect(wire.input, '\x03');
      expect(hostPastes, 0);
      expect(clipboard.methods, isEmpty);
    }, variant: phones);

    testWidgets('an arrow moves through the history', (tester) async {
      _Clipboard(tester).text = 'git status';
      machine(pasteRaw: true);
      await pumpPanel(tester, session());

      await chord(tester, LogicalKeyboardKey.arrowUp);

      expect(wire.input, '\x1b[A');
      expect(hostPastes, 0);
    }, variant: phones);

    testWidgets('a bare V is a letter, typed through the keyboard', (
      tester,
    ) async {
      final clipboard = _Clipboard(tester)..text = 'git status';
      machine(pasteRaw: true);
      await pumpPanel(tester, session());

      // A hardware letter is the keyboard's to type: the key goes by, and the text arrives through
      // the input connection.
      await chord(tester, LogicalKeyboardKey.keyV);
      final typed = '${tester.testTextInput.editingState!['text']}v';
      tester.testTextInput.updateEditingValue(
        TextEditingValue(
          text: typed,
          selection: TextSelection.collapsed(offset: typed.length),
        ),
      );
      await tester.pump(const Duration(milliseconds: 50));

      expect(wire.input, 'v');
      expect(wire.pasted, isEmpty);
      expect(hostPastes, 0);
      expect(clipboard.methods, isEmpty);
    }, variant: phones);

    testWidgets('⌘C (Ctrl+Shift+C on Android) copies the selection', (
      tester,
    ) async {
      final clipboard = _Clipboard(tester);
      machine(pasteRaw: true);
      final pane = session();
      pane.terminal.write('npm test');
      await pumpPanel(tester, pane);
      final buffer = pane.terminal.buffer;
      tester
          .widget<TerminalView>(find.byType(TerminalView))
          .controller!
          .setSelection(buffer.createAnchor(0, 0), buffer.createAnchor(8, 0));
      await tester.pump();

      await chord(
        tester,
        LogicalKeyboardKey.keyC,
        defaultTargetPlatform == TargetPlatform.iOS
            ? [LogicalKeyboardKey.metaLeft]
            : [LogicalKeyboardKey.controlLeft, LogicalKeyboardKey.shiftLeft],
      );

      expect(clipboard.copied, 'npm test');
      expect(wire.binaries, isEmpty);
      expect(hostPastes, 0);
    }, variant: phones);

    testWidgets('⇧ with the paste chord is not this paste', (tester) async {
      _Clipboard(tester).text = 'git status';
      machine(pasteRaw: true);
      await pumpPanel(tester, session());

      await chord(tester, LogicalKeyboardKey.keyV, [
        defaultTargetPlatform == TargetPlatform.iOS
            ? LogicalKeyboardKey.metaLeft
            : LogicalKeyboardKey.controlLeft,
        LogicalKeyboardKey.shiftLeft,
      ]);

      expect(hostPastes, 0);
      expect(wire.pasted, isEmpty);
    }, variant: phones);

    testWidgets("iOS's ⌃V is a keystroke for the far program, not a paste", (
      tester,
    ) async {
      final clipboard = _Clipboard(tester)..text = 'git status';
      machine(pasteRaw: true);
      await pumpPanel(tester, session());

      await chord(tester, LogicalKeyboardKey.keyV, [
        LogicalKeyboardKey.controlLeft,
      ]);

      // Typed on purpose — Claude Code reads it as its own image paste — so it goes as typed.
      expect(wire.input, '\x16');
      expect(hostPastes, 0);
      expect(clipboard.methods, isEmpty);
    }, variant: TargetPlatformVariant.only(TargetPlatform.iOS));
  });
}

/// A 1x1 PNG, for an image the transcode can actually read.
final _onePixelPng = base64Decode(
  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==',
);

/// Everything the pane put on the wire.
class _Wire {
  final frames = <({String type, Map<String, dynamic> payload})>[];
  final binaries = <TerminalBinaryFrame>[];

  /// What was typed as input, as text.
  String get input => utf8.decode([
    for (final frame in binaries)
      if (frame.kind == TerminalBinaryKind.input) ...frame.bytes,
  ], allowMalformed: true);

  /// Each paste sent as one paste frame, as text.
  List<String> get pasted => [
    for (final frame in binaries)
      if (frame.kind == TerminalBinaryKind.paste) utf8.decode(frame.bytes),
  ];

  /// The announcement of an image upload, or null when none was asked for.
  Map<String, dynamic>? get uploadBegin {
    for (final frame in frames) {
      if (frame.type == 'terminal_chunked_upload_begin') return frame.payload;
    }
    return null;
  }
}

/// The phone's clipboard, both halves: the text Flutter's [Clipboard] reads, and the image the
/// native side reads (`harness/clipboard_image`). Records every clipboard call the pane makes.
class _Clipboard {
  _Clipboard(WidgetTester tester) {
    final messenger = tester.binding.defaultBinaryMessenger;
    messenger.setMockMethodCallHandler(SystemChannels.platform, (call) async {
      if (call.method.startsWith('Clipboard.')) methods.add(call.method);
      switch (call.method) {
        case 'Clipboard.setData':
          copied = (call.arguments as Map)['text'] as String?;
        // ⚠️ Typed `<String, dynamic>`: Flutter casts the reply to that, and a `Map<String, bool>`
        // fails the cast inside an unawaited paste — no paste, no message, no failure.
        case 'Clipboard.hasStrings':
          return <String, dynamic>{'value': text != null && text!.isNotEmpty};
        case 'Clipboard.getData':
          onRead?.call();
          return text == null ? null : {'text': text};
      }
      return null;
    });
    messenger.setMockMethodCallHandler(_imageChannel, (call) async {
      if (call.method != 'readImagePng') return null;
      imageReads++;
      return image;
    });
    addTearDown(() {
      messenger.setMockMethodCallHandler(SystemChannels.platform, null);
      messenger.setMockMethodCallHandler(_imageChannel, null);
    });
  }

  static const _imageChannel = MethodChannel('harness/clipboard_image');

  /// Null for a clipboard with no text.
  String? text;

  /// The image as the native side answers it: null for none, empty for one it could not read.
  Uint8List? image;

  /// Runs while the text is being read — the window in which iOS can be showing its prompt.
  void Function()? onRead;

  /// What was copied onto the clipboard, if anything.
  String? copied;

  final methods = <String>[];
  int imageReads = 0;
}