Dart IOOverrides

last modified October 18, 2026

The IOOverrides class in Dart provides a way to override standard IO operations for testing purposes. It's part of the dart:io library.

IOOverrides allows mocking file system, socket, standard stream, and process exit operations. This enables reliable unit tests without real IO operations.

Basic Definition

IOOverrides is an abstract base class in the dart:io library. It provides hooks to override standard IO operations.

Key features include file system mocking, socket interception, and process exit handling. It's essential for test isolation.

Basic IOOverrides Usage

This example shows how to override file operations for testing.

import 'dart:io';

final class MockFileOverrides extends IOOverrides {
  final File mockedFile = File('mocked_content.txt');
  
  @override
  File createFile(String path) {
    return mockedFile;
  }
}

void main() {
  IOOverrides.runWithIOOverrides(() {
    var file = File('test.txt');
    print(file.path);
  }, MockFileOverrides());
}

We create a custom IOOverrides implementation that intercepts file creation. The createFile hook redirects every File to the mocked file. The runWithIOOverrides method executes code with our overrides active.

$ dart main.dart
mocked_content.txt

Mocking Socket Connections

This example demonstrates redirecting socket connections to a local mock server.

import 'dart:convert';
import 'dart:io';

Future<void> main() async {
  final server = await ServerSocket.bind(InternetAddress.loopbackIPv4, 0);
  server.listen((socket) async {
    socket.write('Mocked response');
    await socket.flush();
    socket.destroy();
  });
  
  final mockSocket =
      await Socket.connect(InternetAddress.loopbackIPv4, server.port);
  
  await IOOverrides.runZoned(() async {
    final socket = await Socket.connect('example.com', 80);
    final response = await utf8.decoder.bind(socket).join();
    print(response);
  }, socketConnect: (host, port,
          {sourceAddress, sourcePort = 0, timeout}) =>
      Future.value(mockSocket));
  
  mockSocket.destroy();
  await server.close();
}

IOOverrides has no hook for HttpClient; HTTP mocking belongs to HttpOverrides. It can intercept sockets, so we redirect Socket.connect to a local server that returns a predefined response.

$ dart main.dart
Mocked response

Overriding Process Exit

This example shows how to intercept calls to exit.

import 'dart:io';

final class MockExitOverrides extends IOOverrides {
  @override
  Never exit(int code) {
    print('Exit requested with code $code');
    throw StateError('exit($code) intercepted');
  }
}

void main() {
  IOOverrides.runWithIOOverrides(() {
    try {
      exit(1);
    } on StateError catch (e) {
      print(e.message);
    }
  }, MockExitOverrides());
}

We override process exit to prevent the VM from terminating during a test. The callback records the requested exit code and throws instead.

$ dart main.dart
Exit requested with code 1
exit(1) intercepted

Combining Multiple Overrides

This example combines file and directory overrides in a single test.

import 'dart:io';

final class CombinedOverrides extends IOOverrides {
  final File mockedFile = File('mock_file.txt');
  
  @override
  File createFile(String path) => mockedFile;
  
  @override
  Directory getCurrentDirectory() => Directory('/mock/dir');
}

void main() {
  IOOverrides.runWithIOOverrides(() {
    // Test file operation
    print(File('test.txt').path);
    
    // Test directory operation
    print(Directory.current.path);
  }, CombinedOverrides());
}

We create a comprehensive override that handles both file and directory operations. This enables complex test scenarios with multiple IO dependencies.

$ dart main.dart
mock_file.txt
/mock/dir

Testing with IOOverrides

This example shows a complete unit test using IOOverrides.

import 'dart:io';
import 'package:test/test.dart';

final class TestOverrides extends IOOverrides {
  @override
  Directory getCurrentDirectory() => Directory('/mock/dir');
}

String getCurrentDir() {
  return Directory.current.path;
}

void main() {
  test('Test directory override', () {
    IOOverrides.runWithIOOverrides(() {
      expect(getCurrentDir(), equals('/mock/dir'));
    }, TestOverrides());
  });
}

We test a function that depends on the current directory. The override ensures consistent results regardless of the real environment.

$ dart test main.dart
00:00 +0: Test directory override
00:00 +1: All tests passed!

Best Practices

• Isolation: Keep overrides focused on specific test cases
• Restoration: Overrides automatically revert after runWithIOOverrides
• Completeness: Implement all required methods when overriding
• Realism: Make mock behavior match real implementations

Source

Dart IOOverrides Documentation

This tutorial covered Dart's IOOverrides class with practical examples showing how to mock various IO operations for reliable testing.

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all Dart tutorials.