Skip to main content

Flow Emulator

The Flow Emulator is a lightweight tool that emulates the behavior of the real Flow network for local development and testing.

Installation​

The emulator is included with the Flow CLI. Follow the installation guide to get started.

Quick Start​

First, create a flow.json configuration file:


_10
flow init --config-only

Then start the Flow Emulator:


_10
flow emulator

You'll see output similar to:


_10
INFO[0000] ⚙️ Using service account 0xf8d6e0586b0a20c7 serviceAddress=f8d6e0586b0a20c7 ...
_10
INFO[0000] 🌱 Starting Flow Emulator
_10
INFO[0000] 🛠 GRPC server started on 127.0.0.1:3569
_10
INFO[0000] 📡 HTTP server started on 127.0.0.1:8080

This starts a local Flow network with:

  • gRPC server on port 3569
  • REST API on http://localhost:8888
  • Admin API on port 8080

Common Options​


_14
# Start with verbose logging
_14
flow emulator --verbose
_14
_14
# Set custom block time (e.g., 1 second between blocks)
_14
flow emulator --block-time 1s
_14
_14
# Persist state between restarts
_14
flow emulator --persist
_14
_14
# Change the gRPC and REST API ports
_14
flow emulator --port 9000 --rest-port 9001
_14
_14
# For a complete list of available flags, run:
_14
flow emulator --help

For all available options, see the CLI commands overview.

Debugging & Testing​

  • Code Coverage: Add --coverage-reporting flag and visit http://localhost:8080/emulator/codeCoverage
  • Debugging: Use #debugger() pragma in Cadence code for breakpoints

Snapshots​

The Flow CLI provides a command to create emulator snapshots, which are points in blockchain history you can later jump to and reset the state to that moment. This can be useful for testing where you establish a beginning state, run tests and after revert back to the initial state.

Create a new snapshot​

Create a new emulator snapshot at the current block with a name of myInitialState.


_10
flow emulator snapshot create myInitialState

Load an existing snapshot​

To jump to a previously created snapshot we use the load command in combination with the name.


_10
flow emulator snapshot load myInitialState

List all existing snapshots​

To list all the existing snapshots we previously created and can load to run:


_10
flow emulator list

To learn more about using the Emulator, have a look at the README of the repository.

Additional Resources​

For advanced configuration options, see the Flow Emulator repository.

Rate this page