• Stars
    star
    110
  • Rank 316,770 (Top 7 %)
  • Language
    Go
  • License
    MIT License
  • Created over 8 years ago
  • Updated about 8 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Automate the boilerplate of fuzz testing Go interfaces | owner: @willsewell

Go Interface Fuzzer is a fuzzy testing tool for Go interfaces used @Pusher. The goal of the project is to make it easier for developers to have confidence in the correctness of their programs by combining randomised testing with reference semantics.

Given an interface, a reference implementation, and some hints on how to generate function parameters and compare function return values, Go Interface Fuzzer will generate testing functions which can be used to check that the behaviour of an arbitrary other type implementing the interface behaves the same.

See the _examples directory for a complete self-contained example.

Table of Contents

Project Status

The tool is stable and the interface fixed. New functionality, directives, and command-line arguments may be added, but existing usages will not suddenly stop working.

Getting Started

Installing

To start using Go Interface Fuzzer, install Go and run go get:

$ go get github.com/pusher/go-interface-fuzzer

This will install the go-interface-fuzzer command-line tool into your $GOBIN path, which defaults to $GOPATH/bin.

Usage

The generated code in the _examples directory is produced by

go-interface-fuzzer -c -o -f _examples/store.generated.go _examples/store.go
  • The -c flag generates a complete source file, complete with package name and imports.
  • The -o flag writes the output to the filename given by the -f flag.
  • The -f flag specifies the filename to use when writing output and resolving imports.

The generated code can be customised further, see the full help text (go-interface-fuzzer --help) for a complete flag listing.

The tool generates three functions, named after the interface used. With the example file, the following functions are be produced:

  • FuzzStoreWith(reference Store, test Store, rand *rand.Rand, maxops uint) error

    Create a new reference store and test store, apply a randomly-generated list of actions, and bail out on inconsistency.

  • FuzzStore(makeTest (func(int) Store), rand *rand.Rand, maxops uint) error

    Call FuzzStoreWithReference with the ModelStore as the reference one.

  • FuzzTestStore(makeTest (func(int) Store), t *testing.T)

    A test case parameterised by the store generating function, with a default maxops of 100.

By default Go Interface Fuzzer generates an incomplete fragment: no package name, no imports, just the three testing functions per interface.

Incorporating into the build

Go makes adding a code generation stage to your build process quite simple, with the go generate tool. To incorporate into your build, add a comment to your source file:

//go:generate go-interface-fuzzer -c -o -f output_file.go input_file.go

Typically this would be added to the same file which defines the interface and provides the processing directives (see the next section), but that isn't required.

To then actually generate the file, run go generate. It is not done for you as part of go build.

For further information on code generation in Go see "Generating code", on the Go blog.

Directives

An interface must be marked-up with some processing directives to direct the tool. These directives are given inside a single multi-line comment.

The minimum is just indicating that a fuzz tester should be generated for the interface, and how to produce a new value of the reference implementation type. For example:

/*
@fuzz interface: Store
@known correct:  makeReferenceStore int
*/
type Store interface {
    // ...
}

The fuzzer definition does not need to be immediately next to the interface, it can be anywhere in the source file.

See the _examples directory for a complete self-contained example using most of the directives.

@fuzz interface (required)

This directive begins the definition of a fuzzer, and gives the name of the interface to test.

Example: @fuzz interface: Store

Argument syntax: InterfaceName

@known correct (required)

This directive gives a function to produce a new value of the reference implementation. It specifies the parameters of the function, and whether the return type is a value or a pointer type.

The generated fuzzing function will expect a function argument with the same parameters to create a new value of the type under test.

Example: @known correct: makeReferenceStore int

Argument syntax: [&] FunctionName [ArgType1 ... ArgTypeN]

The presence of a & means that this returns a value rather than a pointer, and so a reference must be made to it.

@invariant

This directive specifies a property that must always hold. It is only checked for the test implementation, not the reference implementation.

Example: @invariant: %var.NumEntries() == len(%var.AsSlice())

Argument syntax: Expression

The argument is a Go expression that evaluates to a boolean, with %var replaced with the variable name.

@comparison

This directive specifies a function to use to compare two values. If not specified the reflection package is used.

Example: @comparison: *MessageIterator:CompareWith

Argument syntax: (Type:FunctionName | FunctionName Type)

In the method form, the target of the comparison is passed as the sole parameter; in the function form both are passed as parameters.

@generator

This directive specifies a function to generate a value of the required type. It is passed a PRNG of type *rand.Rand. If no generator for a type is specified, the tool will attempt to produce a default; and report an error otherwise.

Example: @generator: GenerateChannel model.Channel

Argument syntax: [!] FunctionName Type

The presence of a ! means that this is a stateful function: it is also passed a state parameter and is expected to return a new state as its second result.

@generator state

This directive supplies an initial state for stateful generators. It must be given if any generators are stateful. The initial state is any legal Go expression; it is just copied verbatim into the generated code.

Example: @generator state: InitialGeneratorState

Argument syntax: Expression

Defaults

The following default comparison operations are used if not overridden:

Type Comparison
error Equal if both values are nil or non-nil.
Everything else reflect.DeepEqual

The following default generator functions are used if not overridden:

Type Generator
bool rand.Intn(2) == 0
byte byte(rand.Uint32())
complex64 complex(float32(rand.NormFloat64()), float32(rand.NormFloat64()))
complex128 complex(rand.NormFloat64(), rand.NormFloat64())
float32 float32(rand.NormFloat64())
float64 rand.NormFloat64()
int rand.Int()
int8 int8(rand.Int())
int16 int16(rand.Int())
int32 rand.Int31()
int64 rand.Int63()
rune rune(rand.Int31())
uint uint(rand.Uint32())
uint8 uint8(rand.Uint32())
uint16 uint16(rand.Uint32())
uint32 rand.Uint32()
uint64 `(uint64(rand.Uint32()) << 32)
Everything else No default

Other Uses

Regression testing

Although the motivating use-case for Go Interface Fuzzer was an interface with two implementations that should have identical behaviour, there is nothing preventing the use of multiple versions of the same implementation. This facilitates regression testing, although at the cost of needing to keep the old implementation around.

Here are the concrete steps you would need to follow to do this:

  1. Make a copy of your current implementation, with a new name.
  2. Write a new implementation.
  3. Use the current implementation as the reference implementation for the generated fuzzer.

This isn't quite the same as reference correctness, as any bugs in the old implementation which the new fixes will be reported as an error in the new implementation.

Assertion-only testing

By supplying the same implementation as both the reference and the test implementation, the fuzz tester will simply check invariants. Although, it'll be a little slow, because every operation is being performed twice.

In the future, there will probably be an "invariant-only" mode of operation.

More Repositories

1

pusher-js

Pusher Javascript library
JavaScript
1,970
star
2

atom-pair

An Atom package that allows for epic pair programming
JavaScript
1,454
star
3

pusher-http-php

PHP library for interacting with the Pusher Channels HTTP API
PHP
1,355
star
4

pusher-http-ruby

Ruby library for Pusher Channels HTTP API
Ruby
659
star
5

libPusher

An Objective-C interface to Pusher Channels
C
409
star
6

pusher-http-laravel

[DEPRECATED] A Pusher Channels bridge for Laravel
PHP
405
star
7

pusher-http-python

Pusher Channels HTTP API library for Python
Python
368
star
8

k8s-spot-rescheduler

Tries to move K8s Pods from on-demand to spot instances
Go
313
star
9

pusher-websocket-java

Pusher Channels client library for Java targeting general Java and Android
Java
302
star
10

pusher-websocket-swift

Pusher Channels websocket library for Swift
Swift
267
star
11

build-a-slack-clone-with-react-and-pusher-chatkit

In this tutorial, you'll learn how to build a chat app with React, complete with typing indicators, online status, and more.
JavaScript
235
star
12

pusher-angular

Pusher Angular Library | owner=@leesio
JavaScript
233
star
13

pusher-http-go

Pusher Channels HTTP API library for Go
Go
196
star
14

NWWebSocket

A WebSocket client written in Swift, using the Network framework from Apple.
Swift
123
star
15

k8s-spot-termination-handler

Monitors AWS for spot termination notices when run on spot instances and shuts down gracefully
Makefile
118
star
16

pusher-http-dotnet

.NET library for interacting with the Pusher HTTP API
C#
109
star
17

pusher-websocket-dotnet

Pusher Channels Client Library for .NET
C#
107
star
18

k8s-auth-example

Example Kubernetes Authentication helper. Performs OIDC login and configures Kubectl appropriately.
Go
107
star
19

faros

Faros is a CRD based GitOps controller
Go
99
star
20

backbone-todo-app

JavaScript
92
star
21

chatkit-client-js

JavaScript client SDK for Pusher Chatkit
JavaScript
90
star
22

pusher-channels-flutter

Pusher Channels client library for Flutter targeting IOS, Android, and WEB
Dart
72
star
23

quack

In-Cluster templating for Kubernetes manifests
Go
70
star
24

pusher-websocket-react-native

React Native official Pusher SDK
TypeScript
61
star
25

websockets-from-scratch-tutorial

Tutorial that shows how to implement a websocket server using Ruby's built-in libs
Ruby
60
star
26

push-notifications-php

Pusher Beams PHP Server SDK
PHP
56
star
27

backpusher

JavaScript
54
star
28

chatkit-android

Android client SDK for Pusher Chatkit
Kotlin
53
star
29

django-pusherable

Real time notification when an object view is accessed via Pusher
Python
52
star
30

cli

A CLI for Pusher (beta)
Go
51
star
31

notify

Ruby
51
star
32

k8s-spot-price-monitor

Monitors the spot prices of instances in a Kubernetes cluster and exposes them as prometheus metrics
Python
44
star
33

chatkit-command-line-chat

A CLI chat, built with Chatkit
JavaScript
41
star
34

pusher-http-java

Java client to interact with the Pusher HTTP API
Java
40
star
35

chatkit-swift

Swift SDK for Pusher Chatkit
Swift
40
star
36

push-notifications-web

Beams Browser notifications
JavaScript
39
star
37

electron-desktop-chat

A desktop chat built with React, React Desktop and Electron
JavaScript
38
star
38

crank

Process slow restarter
Go
37
star
39

pusher-websocket-android

Library built on top of pusher-websocket-java for Android. Want Push Notifications? Check out Pusher Beams!
Java
35
star
40

chameleon

A collection of front-end UI components used across Pusher ✨
CSS
35
star
41

chatkit-server-php

PHP SDK for Pusher Chatkit
PHP
35
star
42

push-notifications-swift

Swift SDK for the Pusher Beams product:
Swift
34
star
43

cide

Isolated test runner with Docker
Ruby
33
star
44

pusher-phonegap-android

JavaScript
30
star
45

push-notifications-python

Pusher Beams Python Server SDK
Python
30
star
46

pusher-websocket-unity

Pusher Channels Unity Client Library
C#
27
star
47

hacktoberfest

24
star
48

laravel-chat

PHP
23
star
49

push-notifications-android

Android SDK for Pusher Beams
Kotlin
21
star
50

push-notifications-node

Pusher Beams Node.js Server SDK
JavaScript
20
star
51

pusher-test-iOS

iOS app for developers to test connections to Pusher
Objective-C
19
star
52

push-notifications-ruby

Pusher Beams Ruby Server SDK
Ruby
18
star
53

chatkit-server-node

Node.js SDK for Pusher Chatkit
TypeScript
16
star
54

rack-headers_filter

Remove untrusted headers from Rack requests | owner=@zimbatm
Ruby
15
star
55

pusher-test-android

Test and diagnostic app for Android, based on pusher-java-client
Java
14
star
56

pusher-realtime-tfl-cameras

Realtime TfL Traffic Camera API, powered by Pusher
JavaScript
14
star
57

buddha

Buddha command execution and health checking | owner: @willsewell
Go
14
star
58

chatkit-server-go

Chatkit server SDK for Golang
Go
13
star
59

pusher-channels-auth-example

A simple server exposing a pusher auth endpoint
JavaScript
13
star
60

pusher-platform-js

Pusher Platform client library for browsers and react native
TypeScript
13
star
61

stronghold

[DEPRECATED] A configuration service | owner: @willsewell
Haskell
12
star
62

sample-chatroom-ios-chatkit

How to make an iOS Chatroom app using Swift and Chatkit
PHP
12
star
63

pusher-twilio-example

CSS
12
star
64

chatkit-server-ruby

Ruby server SDK for Chatkit
Ruby
12
star
65

prom-rule-reloader

Watches configmaps for prometheus rules and keeps prometheus in-sync
Go
12
star
66

electron-desktop-starter-template

JavaScript
11
star
67

realtime-visitor-tracker

Realtime location aware visitor tracker for a web site or application
PHP
11
star
68

push-notifications-server-java

Pusher Beams Java Server SDK
Kotlin
10
star
69

android-slack-clone

Android chat application, built with Chatkit
Kotlin
10
star
70

filtrand

JavaScript
10
star
71

vault

Front-end pattern library
Ruby
9
star
72

git-store

Go git abstraction for use in Kubernetes Controllers
Go
9
star
73

pusher-platform-android

Pusher Platform SDK for Android
Kotlin
9
star
74

push-notifications-go

Pusher Beams Go Server SDK
Go
9
star
75

pusher-platform-swift

Swift SDK for Pusher platform products
Swift
8
star
76

realtime_survey_complete

JavaScript
8
star
77

docs

The all new Pusher docs, powered by @11ty and @vercel
CSS
8
star
78

push-notifications-server-swift

Pusher Beams Swift Server SDK
Swift
8
star
79

pusher-python-rest

Python client to interact with the Pusher REST API. DEPRECATED in favour of https://github.com/pusher/pusher-http-python
Python
8
star
80

real-time-progress-bar-tutorial

Used inthe realtime progress bar tutorial blog post - http://blog.pusher.com
JavaScript
7
star
81

pusher-channels-chunking-example

HTML
7
star
82

pusher-http-swift

Swift library for interacting with the Pusher Channels HTTP API
Swift
7
star
83

feeds-client-js

JS client for Pusher Feeds
JavaScript
6
star
84

pusher-test

Simple website which allows manual testing of pusher-js versions
JavaScript
6
star
85

java-websocket

A fork of https://github.com/TooTallNate/Java-WebSocket | owner=@zmarkan
HTML
6
star
86

navarchos

Node replacing controller
Go
5
star
87

bridge-troll

A Troll that ensures files don't change
Go
5
star
88

realtime-notifications-tutorial

Create realtime notifications in minutes, not days =)
4
star
89

pusher-socket-protocol

Protocol for pusher sockets
HTML
4
star
90

icanhazissues

Github issues kanban
JavaScript
4
star
91

textsync-server-node

[DEPRECATED] A node.js library to simplify token generation for TextSync authorization endpoints.
TypeScript
4
star
92

pusher_tutorial_realtimeresults

JavaScript
3
star
93

pusher-js-diagnostics

JavaScript
3
star
94

react-rest-api-tutorial

Accompanying tutorial for consuming RESTful APIs in React
CSS
3
star
95

feeds-server-node

The server Node SDK for Pusher Feeds
JavaScript
3
star
96

testing

Configuration for Pusher's Open Source Prow instance
Go
3
star
97

spacegame_example

Simple example of a space game using node.js and Pusher
JavaScript
3
star
98

chatkit-quickstart-swift

A project to get started with Chatkit.
Swift
2
star
99

pusher-whos-in

Ruby
2
star
100

healthz-proxy

healthz proxy for zero downtime rollouts
Go
2
star