Docs

docs/content/doc/development/structure.md

@@ -16,7 +16,12 @@ In general, this api repo has the following structure:
 * `docs`
 * `pkg`
   * `caldav`
+  * `cmd`
   * `config`
+  * `db`
+    * `fixtures`
+  * `files`
+  * `integration`
   * `log`
   * `mail`
   * `metrics`
@@ -29,8 +34,11 @@ In general, this api repo has the following structure:
   * `red`
   * `routes`
     * `api/v1`
+  * `static`
   * `swagger`
+  * `user`
   * `utils`
+  * `version`
 * `REST-Tests`
 * `templates`
 * `vendor`
@@ -70,6 +78,21 @@ how to interpret which env variables for config etc.
 
 If you want to add a new config parameter, you should add default value in this package.
 
+### db
+
+This package contains the db connection handling and db fixtures for testing.
+Each other package gets its db connection object from this package.
+
+### files
+
+This package is responsible for all file-related things.
+This means it handles saving and retrieving files from the db and the underlying file system.
+
+### integration
+
+All integration tests live here.
+See [integration tests]({{< ref "test.md" >}}#integration-tests) for more details.
+
 ### log
 
 Similar to `config`, this will set up the logging, based on differen logging backends.
@@ -127,11 +150,19 @@ To add a new route, see [adding a new route]({{< ref "../practical-instructions/
 This is where all http-handler functions for the api are stored. 
 Every handler function which does not use the standard web handler should live here.
 
+### static
+
+All static files generated by `make generate` live here.
+
 ### swagger
 
 This is where the [generated]({{< ref "make.md#generate-swagger-definitions-from-code-comments">}} [api docs]({{< ref "../usage/api.md">}}) live. 
 You usually don't need to touch this package.
 
+### user
+
+All user-related things like registration etc. live in this package.
+
 ### utils
 
 A small package, containing some helper functions:
@@ -141,6 +172,12 @@ A small package, containing some helper functions:
 
 See their function definitions for instructions on how to use them. 
 
+### version
+
+The single purpouse of this package is to hold the current vikunja version which gets overridden through build flags 
+each time `make release` or `make build` is run.
+It is a seperate package to avoid import cycles with other packages.
+
 ## REST-Tests
 
 Holds all kinds of test files to directly test the api from inside of [jetbrains ide's](https://www.jetbrains.com/help/idea/http-client-in-product-code-editor.html).

docs/content/doc/development/test.md

@@ -42,3 +42,29 @@ The integration tests use the same config and fixtures as the unit tests and the
 see at the beginning of this document.
 
 To run integration tests, use `make integration-test`.
+
+# Initializing db fixtures when writing tests
+
+All db fixtures for all tests live in the `pkg/db/fixtures/` folder as yaml files.
+Each file has the same name as the table the fixtures are for.
+You should put new fixtures in this folder.
+
+When initializing db fixtures, you are responsible for defining which tables your package needs in your test init function.
+Usually, this is done as follows (this code snippet is taken from the `user` package):
+
+```go
+err = db.InitTestFixtures("users")
+if err != nil {
+	log.Fatal(err)
+}
+```
+
+In your actual tests, you then load the fixtures into the in-memory db like so:
+
+```go
+db.LoadAndAssertFixtures(t)
+```
+
+This will load all fixtures you defined in your test init method.
+You should always use this method to load fixtures, the only exception is when your package tests require extra test 
+fixtures other than db fixtures (like files).