imposter-go

A Go implementation of the Imposter Mock Engine.

Features

💻 Run locally: Lightweight local HTTP mock server
🚀 Run in AWS Lambda: low latency, high throughput, <140ms cold start (see test results)
✅ REST/HTTP API mock support
✅ SOAP/WSDL mock support
✅ OpenAPI/Swagger mock support
✅ JavaScript scripting
✅ Support for steps

⚠️ Limitations

No support for Groovy scripting
No support (yet) for some SOAP styles (https://github.com/imposter-project/imposter-go/issues/7)

Getting Started

The recommended way to get started for most users is to use the latest Imposter CLI.

Note If you don't have Imposter CLI installed, or you want to use the imposter-go binary directly, continue to the Installation section.

With Imposter CLI installed, use the -t golang option, and pass -v <version>:

imposter up -t golang -v <version>

...where version is from the Releases page, for example:

imposter up -t golang -v 0.15.0

Installation

Using Pre-built Binaries

Download the latest release for your platform from GitHub:

macOS

# For Intel Macs (x86_64)
curl -L https://github.com/imposter-project/imposter-go/releases/latest/download/imposter-go_Darwin_x86_64.tar.gz | tar xz
sudo mv imposter-go /usr/local/bin/

# For Apple Silicon Macs (arm64)
curl -L https://github.com/imposter-project/imposter-go/releases/latest/download/imposter-go_Darwin_arm64.tar.gz | tar xz
sudo mv imposter-go /usr/local/bin/

Linux

# For x86_64 systems
curl -L https://github.com/imposter-project/imposter-go/releases/latest/download/imposter-go_Linux_x86_64.tar.gz | tar xz
sudo mv imposter-go /usr/local/bin/

# For arm64 systems
curl -L https://github.com/imposter-project/imposter-go/releases/latest/download/imposter-go_Linux_arm64.tar.gz | tar xz
sudo mv imposter-go /usr/local/bin/

Windows

Download the latest release from GitHub Releases
Extract the imposter-go_Windows_x86_64.zip file
Add the extracted imposter-go.exe to your PATH or move it to a directory in your PATH

Usage

Run with a directory containing Imposter configuration file(s):

imposter-go ./examples/rest/simple

Visit http://localhost:8080/hello in your browser or use curl:

curl http://localhost:8080/hello

Examples

The repository includes several examples demonstrating different features:

Simple REST API - Basic REST API mocking
SOAP Web Service - SOAP/WSDL-based service mocking
OpenAPI HTTP API - OpenAPI-based service mocking
AWS Lambda - Running Imposter in AWS Lambda

Configuration

A subset of the Imposter environment variables are supported. For example:

Set the IMPOSTER_PORT environment variable to change the default port:

export IMPOSTER_PORT=9090

Enable recursive directory scanning for configuration files:

export IMPOSTER_CONFIG_SCAN_RECURSIVE=true

Set the IMPOSTER_LOG_LEVEL environment variable to control logging verbosity:

export IMPOSTER_LOG_LEVEL=DEBUG  # Available levels: TRACE, DEBUG, INFO, WARN, ERROR

The default log level is DEBUG. Available log levels:

TRACE - Most verbose, logs all messages
DEBUG - Detailed information for debugging
INFO - General operational messages
WARN - Warning messages for potentially harmful situations
ERROR - Error messages for serious problems

Building from Source

Requirements

Go 1.23 or later (earlier versions may work but are not tested)
Make (for building)

Build Steps

Clone the repository:

git clone https://github.com/imposter-project/imposter-go.git
cd imposter-go

Run the server with an example configuration:
```
make run ./examples/rest/simple
```
Visit http://localhost:8080/hello in your browser or use curl:
```
curl http://localhost:8080/hello
```

Check the server version:

curl http://localhost:8080/system/status

Development

The project uses Make for building and development. The following targets are available:

make run <path> - Run the server directly (useful during development)
make build - Build the project with version information
make install - Install the binary to your Go bin directory
make test - Run tests with verbose output

For development, use make run which will compile and run the server in one step:

# Run with a specific configuration
make run ./examples/rest/simple

# Run with multiple arguments
make run --debug ./examples/soap/simple

For production or installation, use make build or make install.

The version information is automatically derived from git tags. When building from source:

Released versions will show the git tag (e.g. "v1.0.0")
Development builds will show the git commit hash
If no git information is available, it will show "dev"

Testing

Run the test suite using:

make test

This will run all tests.

To run a specific test, use the go test command:

go test ./pkg/server

To run tests with verbose output, use the -v flag:

go test -v ./pkg/server

Releasing

To create a new release:

Tag your commit with a semver tag prefixed with 'v':
```
git tag v1.0.0
git push origin v1.0.0
```
The GitHub Actions workflow will automatically:
- Build binaries for all supported platforms (Linux, macOS, Windows)
- Generate a changelog from commit messages
- Create a GitHub release
- Upload the built artifacts

The release notes will include:

Version and release date
Automatically generated changelog (excluding docs, test, ci, and chore commits)
Installation instructions
Link to the full changelog comparing with the previous tag

# Packages

# README