add README

README.md

@@ -5,4 +5,82 @@
 [![rcard](https://goreportcard.com/badge/github.com/modern-go/test)](https://goreportcard.com/report/github.com/modern-go/test)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://raw.githubusercontent.com/modern-go/test/master/LICENSE)
 
-Make go unit test more readable
+Make go unit test more readable
+
+* C style assert, with clear error message
+* Diff object, if unequal, tells exactly where is the difference
+* JsonEqual to compare complex object graph
+
+# Assert
+
+```go
+import (
+	"context"
+	. "github.com/modern-go/test"
+	. "github.com/modern-go/test/must"
+	"testing"
+)
+
+func Test(t *testing.T) {
+	t.Run("one should not equal two", Case(func(ctx context.Context) {
+		Assert(1 == 2)
+	}))
+}
+```
+
+If test failed, the error message will tell you where it failed and what has failed
+
+```
+example_test.go:12: failed: Assert(1 == 2)
+```
+
+# Equal/NotEqual
+
+the implementation of diff is copied from testify.
+
+```go
+map1 := map[string]string{
+"a": "b",
+"c": "hello",
+}
+map2 := map[string]string{
+"a": "b",
+"c": "hi",
+}
+must.Equal(map1, map2)
+```
+
+the diff will be printed
+
+```
+Error: Not equal:
+expected: map[string]string{"a":"b", "c":"hello"}
+actual : map[string]string{"a":"b", "c":"hi"}
+
+Diff:
+--- Expected
++++ Actual
+@@ -2,3 +2,3 @@
+(string) (len=1) "a": (string) (len=1) "b",
+- (string) (len=1) "c": (string) (len=5) "hello"
++ (string) (len=1) "c": (string) (len=2) "hi"
+}
+case_test.go:39: failed: must.Equal(map1, map2)
+```
+
+# JsonEqual
+
+check complex object graph using json
+
+```go
+must.JsonEqual(`{"a":{"b":"c"}}`, map[string]interface{}{
+    "a": map[string]interface{}{
+        "b": "c",
+    },
+})
+```
+
+# must v.s. should
+
+* must: when assertion failed, the test case will skip remaining assertions, skip to next test case
+* should: when assertion failed, the test case will continue check remaining assertions

must/equal.go

@@ -21,6 +21,21 @@ func Equal(expected interface{}, actual interface{}) {
 	t.Fatal(test.ExtractFailedLines(file, line))
 }
 
+//go:noinline
+func NotEqual(expected interface{}, actual interface{}) {
+	t := test.CurrentT()
+	if assert.NotEqual(t, expected, actual) {
+		return
+	}
+	test.Helper()
+	_, file, line, ok := runtime.Caller(1)
+	if !ok {
+		t.Fatal("check failed")
+		return
+	}
+	t.Fatal(test.ExtractFailedLines(file, line))
+}
+
 //go:noinline
 func AssertEqual(expected interface{}, actual interface{}) {
 	t := test.CurrentT()

must/json.go

@@ -26,8 +26,10 @@ func JsonEqual(expected string, actual interface{}) {
 		actualJson = actualVal
 	default:
 		actualJson, err = json.Marshal(actual)
-		t.Fatal("actual can not marshal to json: " + err.Error())
-		return
+		if err != nil {
+			t.Fatal("actual can not marshal to json: " + err.Error())
+			return
+		}
 	}
 	var actualObj interface{}
 	err = json.Unmarshal(actualJson, &actualObj)

should/equal.go

@@ -21,6 +21,21 @@ func Equal(expected interface{}, actual interface{}) {
 	t.Error(test.ExtractFailedLines(file, line))
 }
 
+//go:noinline
+func NotEqual(expected interface{}, actual interface{}) {
+	t := test.CurrentT()
+	if assert.NotEqual(t, expected, actual) {
+		return
+	}
+	test.Helper()
+	_, file, line, ok := runtime.Caller(1)
+	if !ok {
+		t.Error("check failed")
+		return
+	}
+	t.Error(test.ExtractFailedLines(file, line))
+}
+
 //go:noinline
 func AssertEqual(expected interface{}, actual interface{}) {
 	t := test.CurrentT()

test/case_test.go → tests/case_test.go

@@ -1,4 +1,4 @@
-package test
+package tests
 
 import (
 	"context"
@@ -58,4 +58,11 @@ func Test_case(t *testing.T) {
 		ret := should.Call(os.Stat, "/bin/bash")
 		should.Equal("bash", ret[0].(os.FileInfo).Name())
 	}))
+	t.Run("json equal", test.Case(func(ctx context.Context) {
+		must.JsonEqual(`{"a":{"b":"c"}}`, map[string]interface{}{
+			"a": map[string]interface{}{
+				"b": "c",
+			},
+		})
+	}))
 }

tests/example_test.go

@@ -0,0 +1,20 @@
+package tests
+
+import (
+	"context"
+	. "github.com/modern-go/test"
+	. "github.com/modern-go/test/must"
+	"testing"
+)
+
+func Test(t *testing.T) {
+	t.Run("one should not equal two", Case(func(ctx context.Context) {
+		Assert(1 == 2)
+	}))
+}
+
+func Test_one_should_not_equal_two(t *testing.T) {
+	if 1 != 2 {
+		t.Fatal("1==2")
+	}
+}