Imposter SDK

May 21, 2026 · View on GitHub

The Imposter SDK allows you to embed Imposter directly into your own Go applications and workflows. Use it to programmatically start and manage mock servers, enabling powerful integration testing, local development environments, and custom tooling.

Use cases

  • Integration testing — spin up mock dependencies as part of your test suite
  • Local development — run mock services alongside your application during development
  • Custom tooling — build bespoke workflows that manage mock servers on demand
  • CI/CD pipelines — programmatically control mocks in your build and deployment pipelines

Key concepts

There are a few key concepts to learn before using the SDK:

Getting started

Import the Imposter SDK into your Go project:

go get github.com/imposter-project/imposter-cli

Example

Here is a simple example that starts Imposter on port 8080, using the configuration in a given directory:

package main

import (
    "sync"

    "github.com/imposter-project/imposter-cli/internal/engine"
    "github.com/imposter-project/imposter-cli/internal/engine/docker"
)

func main() {
    configDir := "/path/to/imposter/config"

    // register the engine implementation you want to use.
    // swap for jvm.EnableEngine() or native.EnableEngine() as required.
    docker.EnableEngine()

    startOptions := engine.StartOptions{
        Port:           8080,
        Version:        "latest",
        PullPolicy:     engine.PullIfNotPresent,
        LogLevel:       "DEBUG",
        ReplaceRunning: true,
    }

    mockEngine := engine.BuildEngine(engine.EngineTypeDockerCore, configDir, startOptions)

    // block until the engine is terminated
    wg := &sync.WaitGroup{}
    mockEngine.Start(wg)
    wg.Wait()
}

The matching engine type constants live on the engine package:

  • engine.EngineTypeDockerCore (paired with docker.EnableEngine())
  • engine.EngineTypeJvmSingleJar (paired with jvm.EnableEngine())
  • engine.EngineTypeNative (paired with native.EnableEngine())

Learn more