Fix up docs

README.md

@@ -17,9 +17,12 @@ The order of precedence for configured values is as follows:
 1. Values provided in explicit cli arguments ( `--username`, `--password`, `--host`, `--port`, etc. )
 2. Values provided in cli `--url`
 3. Values provided in `PILGRIM_*` environment variables
-  - Values in `PILGRIM_URL` are of lowest precedence and are overridden by their explicit `PILGRIM_*` equivalents
+  - Values in `PILGRIM_URL` are of lowest precedence and are overridden by their
+    explicit `PILGRIM_*` equivalents
 
-By default, pilgrim will search for a `.pilgrim` file in the directory it has been run in and will use the values within to replace values that have not been provided in a higher precedence form.
+By default, pilgrim will search for a `.pilgrim` file in the directory it has
+been run in and will use the values within to replace values that have not been
+provided in a higher precedence form.
 
 #### CLI Arguments
 
@@ -47,8 +50,9 @@ By default, pilgrim will search for a `.pilgrim` file in the directory it has be
 
 ##### Conflicts between `--down` and `--up`
 
-If both `--down` and `--up` are provided, `pilgrim` will return an error and will not migrate the database.
+If both `--down` and `--up` are provided, `pilgrim` will return an error and
-The `--script` name provided must adhere to the [migration naming convention and contain the folder it is located in](#migration-naming-convention-folder-structure).
+will not migrate the database. The `--script` name provided must adhere to the
+[migration naming convention and contain the folder it is located in](#migration-naming-convention-folder-structure).
 
 #### Environment Variables
 
@@ -68,9 +72,11 @@ The `--script` name provided must adhere to the [migration naming convention and
 
 #### Migration Naming Convention & Folder Structure
 
-`pilgrim` requires that migration files be named uniquely, and can be ordered. To ensure this, migrations
+`pilgrim` requires that migration files be named uniquely, and can be ordered.
-must be sorted by date, and then further within each date-named directory, the contained migration files must begin with a number.
+To ensure this, migrations must be sorted by date, and then further within each
-The numbers need not be unique ( you can have multiple scripts starting with `1_`, for example ), but the name of the migration does.
+date-named directory, the contained migration files must begin with a number.
+The numbers need not be unique ( you can have multiple scripts starting with
+`1_`, for example ), but the name of the migration does.
 
 Example migration directory:
 
@@ -89,7 +95,8 @@ migrations
 
 #### Migration Definition
 
-Creating a pilgrim migration involves creating a regular SQL file, with some mandatory comments contained within:
+Creating a pilgrim migration involves creating a regular SQL file, with some
+mandatory comments contained within:
 
 ```sql
 -- PILGRIM::UP
@@ -101,15 +108,15 @@ CREATE TABLE ...
 DROP TABLE ...
 ```
 
-Everything between `-- PILGRIM::UP` and `-- PILGRIM::DOWN` is run during the `--up` phase of migration.
+Everything between `-- PILGRIM::UP` and `-- PILGRIM::DOWN` is run during the
-Everything after `--PILGRIM::DOWN` to the end of the file is run during the `--down` phase of migration.
+`--up` phase of migration.
 
+Everything after `--PILGRIM::DOWN` to the end of the file is run during the
+`--down` phase of migration.
+
+If a file is missing these comments, the migration will not be run, and the file
+will be ignored.
 
 ## Development
 
-This project is built using golang `1.23.1`.
+See [Development Documentation](./docs/README.md)
-
-1. Checkout this repository
-2. Run `go build -o target`
-
-This will build a `pilgrim` binary in the `target` folder.

docs/README.md

@@ -0,0 +1,9 @@
+# Development Documentation
+
+All documentation related to development of the pilgrim project is to be found
+here in the `docs` folder.
+
+## Index
+
+1. [Setup](./SETUP.md)
+2. [Testing](./TESTS.md)

docs/SETUP.md

@@ -0,0 +1,10 @@
+# Setup
+
+This project is built using golang `1.23.1`.
+
+#### Setup steps
+
+1. Checkout this repository
+2. Run `go build -o target`
+
+This will build a `pilgrim` binary in the `target` folder.

docs/TESTS.md

@@ -0,0 +1,21 @@
+# Writing & Maintaining Tests
+
+Pilgrim's tests are written using the testify framework and mockery.
+
+#### Generate Mocks
+
+The below command, when executed from the project root, will generate mocks for
+all interfaces in all packages of the project, and put them in the `mocks`
+directory, under the `pilgrim_mock` package
+
+```bash
+mockery --all --outpkg pilgrim_mock --output ./internal/mocks
+```
+
+#### Run Tests
+
+To run all tests, execute the following from the root directory
+
+```bash
+go test ./...
+```

internal/pilgrim_conf_test/context_test.go

@@ -75,6 +75,20 @@ func Test_PilgrimContext_CliDriverOverridesCliUrlDriver(t *testing.T) {
 	)
 }
 
+func Test_PilgrimContext_EnvDriverOverridesEnvUrlDriver(t *testing.T) {
+	runTest(
+		func(env *pilgrim_mock.EnvVarRetriever, cli *pilgrim_mock.CliFlagRetriever) {
+			env.EXPECT().Driver().Return(pilgrim_conf.DbDriver_MSSQL, true) // This should be highest priority
+			env.EXPECT().Url().Return("postgres://env_host:5432", true)
+		},
+		func(env *pilgrim_mock.EnvVarRetriever, cli *pilgrim_mock.CliFlagRetriever) {
+			ctx := pilgrim_conf.NewPilgrimContext(cli, env)
+
+			assert.Equal(t, pilgrim_conf.DbDriver_MSSQL, ctx.UrlParts().Driver)
+		},
+	)
+}
+
 // func Test_PilgrimContext_EnvDriverOverridesEnvUrlDriver(t *testing.T) {
 // 	context, _, _ := createPilgrimContextWithDependencies(
 // 		map[string]string{},