From e83469acab32584d49f44abb047e99aa0b31a4d2 Mon Sep 17 00:00:00 2001
From: Miguel de la Cruz <miguel@mcrx.me>
Date: Wed, 10 Aug 2022 11:19:46 +0200
Subject: [PATCH] Improve README file

---
 README.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/README.md b/README.md
index 3a2e811..f6c2af0 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,61 @@
 # Foundation
 
 A set of helpers to help to create and manage database migration tests.
+
+## Install
+
+```
+go get git.ctrlz.es/mgdelacroix/foundation
+```
+
+## Usage
+
+To start using foundation, you need to implement the `Migrator`
+interface, describing how your tool manages migrations and what are
+the intermediate steps (generally data migrations), if any, that need
+to run at the end of each migration step:
+
+```go
+type Migrator interface {
+	DB() *sql.DB
+	DriverName() string
+	Setup() error
+	MigrateToStep(step int) error
+	TearDown() error
+}
+
+interceptors := map[int]Interceptor{
+    // function that will run after step 6
+    6: func() err {
+        return myStore.RunDataMigration()
+    },
+}
+```
+
+With the interface implemented, you can use `foundation` in your tests
+to load fixtures, set the database on a specific state and then run
+your assertions:
+
+```go
+t.Run("migration should link book 1 with its author", func(t *testing.T) {
+	f := foundation.New(t, migrator).
+		RegisterInterceptors(interceptors).
+		// runs migrations up to and including 5
+		MigrateToStep(5).
+		// loads the SQL of the file
+		ExecFile("./myfixtures.sql").
+		// runs migration 6 and its interceptor function
+		MigrateToStep(6)
+	defer f.TearDown()
+
+	book := struct{
+		ID int
+		AuthorID int
+	}{}
+
+	err = f.DB().Get(&book, "SELECT id, authorID FROM books")
+	require.NoError(t, err)
+	require.Equal(t, 1, book.ID)
+	require.Equal(t, 3, book.AuthorID)
+})
+```