README.md

fakehub

fakehub - A fully functional fake version of a GitHub REST API that supports all the features and works locally, with no connection to GitHub at all.

Motivation. There are many applications that use GitHub API for different purposes. All of them need to create automated tests, which need to mock the API server somehow. We offer a fully functioning mock version of a GitHub REST API, which would support all functions, but work locally, with absolutely no connection to GitHub.

Quick start

First, install it from crate:

cargo install fakehub

Then, create a simple test, test.sh:

{
  fakehub start -d
  out="$(curl -s 'http://localhost:3000/users/jeff' | jq -r '.login')"
  expected="jeff"
  if [ "$out" == $expected ]; then
    echo "Test passed!"
  else
    echo "Login '$out' does not match with expected: '$expected'"
    exit 1
  fi
  fakehub stop
}

And run it:

sh test.sh

You should be able to see this:

2024-10-15T15:14:33.469924Z  INFO fakehub: Starting server on port 3000
2024-10-15T15:14:33.470238Z  INFO fakehub: Server is running in detached mode on port 3000
2024-10-15T15:14:33.470247Z  INFO fakehub_server::sys::sys_info: OS: macos
2024-10-15T15:14:33.470251Z  INFO fakehub_server::sys::sys_info: PID: 11751
Test passed!
2024-10-15T15:14:33.486892Z  INFO fakehub: Stopping fakehub...
2024-10-15T15:14:33.518901Z  INFO fakehub::sys::kill_unix: Port 3000 killed
2024-10-15T15:14:33.518913Z  INFO fakehub: fakehub stopped

Table of contents

• Overview
• Request format
• GitHub objects
• CLI options

Overview

fakehub is a full clone of GitHub REST API. This is very beneficial for testing, when you should not use real GitHub, but a mock version of it instead. fakehub stores all the data in memory. When request arrives, we query the storage, transform objects into GitHub API-compatible format (JSON) and give it to you.

Request format

fakehub supports the format specified in GitHub REST API docs. For instance, if you want to use Get a repository endpoint: you should just replace api.github.com to localhost:$port (make sure that fakehub is running on specified port).

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  http://localhost:$port/repos/OWNER/REPO

Attention! Don't use your own GitHub Personal Access Tokens to authorize in fakehub. Instead, use generated token by fakehub:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"login": "jeff"}' \
  http://localhost:$port/login

This should generate you an access token to fakehub API.

GitHub objects

TBD..

CLI options

You can use the following options within fakehub command-line tool:

Name	Value	Default	Description
-p, --port	int	3000	Port to run fakehub server on.
-v, --verbose	boolean	false	Verbose run output, i.e. debug logs, etc.
-d, --detach	boolean	false	Run fakehub server in detached mode.
-i, --init	string	-	Path to file or directory with initial state.
-r, --report	boolean	false	Generate report after fakehub shutdown.
--report-format	string	-	Generated report format. Possible values: latex for LaTeX, xml for XML, and txt for plain text.

How to contribute?

Make sure that you have Rust, just, npm, and Java 21+ installed on your system, then fork this repository, make changes, send us a pull request. We will review your changes and apply them to the master branch shortly, provided they don't violate our quality standards. To avoid frustration, before sending us your pull request please run full build:

just full

Here is the contribution vitals, made by zerocracy/judges-action (updated every hour!).