You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+14-55
Original file line number
Diff line number
Diff line change
@@ -5,35 +5,27 @@
5
5
6
6
> An [Express](https://expressjs.com/) and [Bookshelf](http://bookshelfjs.org/) based backend implementation of the [RealWorld API Spec](https://github.com/gothinkster/realworld/tree/master/api).
This project was created in order to familiarise myself with some key technologies in use at my day job. It's not intended to be production ready, but PRs that address this and any other issues are welcome!
27
19
28
-
## getting started
20
+
## Getting Started
29
21
30
22
Ensure [Docker Compose](https://docs.docker.com/compose/install/) is installed, then:
31
23
32
24
1. Clone this repo.
33
25
2. Change to the above dir.
34
26
3. Run `yarn docker:start` to start the app.
35
27
36
-
## running tests
28
+
## Running Tests
37
29
38
30
Run the full test suite with:
39
31
@@ -59,43 +51,10 @@ Then in a new terminal window, assuming you've cloned the `realworld-server-test
High-level overview of some important decisions made building the app. Check the code comments for more detail too.
65
-
66
-
### structure
67
-
68
-
#### group by coupling
69
-
70
-
The general rule with modules in the `lib/` dir is "things that change together, stay together". This is largely a personal preference after having to maintain apps that instead group by function, but the approach is also summarised nicely in this [express code structure](https://github.com/focusaurus/express_code_structure) example.
71
-
72
-
Each module is usually an Express sub-app. Code that is shared across modules is either promoted (e.g. middleware), or is added to a specific app-wide registry (e.g. models).
73
-
74
-
#### initializers
75
-
76
-
The initialization procedure is based on [the approach taken by the Locomotive framework](http://www.locomotivejs.org/guide/initialization/). App initialization steps have been split into separate functions in
77
-
the `initializers/` folder, and are run in a certain order. Any required app-wide references are set on the [`app.locals`](https://expressjs.com/en/4x/api.html#app.locals) object.
78
-
79
-
### configuration
80
-
81
-
Configuration is handled by [node-convict](https://github.com/mozilla/node-convict), which provides context on each setting and enables validation and early failures for when the configuration is wrong.
82
-
83
-
Some values are required, and there are also some defaults which can be overridden if required. You can do this via environment-specific configuration files, for example `development.json` and `test.json`. Environment variables are also respected, see [precedence order](https://github.com/mozilla/node-convict#precendence-order) for more information.
84
-
85
-
### testing
86
-
87
-
#### outside-in
88
-
89
-
The preference is to create high-level tests first in order to test the API end-to-end from a user’s perspective. From there we can drop down into lower-level tests like unit tests (this hasn't yet been done in this repo). See [Testing from the Outside-In](https://robots.thoughtbot.com/testing-from-the-outsidein) for more information.
90
-
91
-
#### run in band
92
-
93
-
Since we're hitting a real DB via our functional tests, we want to run them serially in the current process using Jest's [`runInBand`](https://facebook.github.io/jest/docs/en/cli.html#runinband) option so they remain isolated. If the test suite gets expanded to include unit tests that don't hit the DB for example, then we may want to be specific about when we use that flag in order to keep the tests running as fast as possible.
94
-
95
-
#### prefer snapshot tests
54
+
## Documentation
96
55
97
-
Where possible Jest's [snapshot testing](https://facebook.github.io/jest/docs/en/snapshot-testing.html) feature is used in order to validate key parts of the API response. Where this is not straightforward, for example when the response returns creation dates which vary over time, we've fallen back to more specific assertions.
Configuration is handled by [node-convict](https://github.com/mozilla/node-convict), which provides context on each setting and enables validation and early failures for when the configuration is wrong.
4
+
5
+
Some values are required, and there are also some defaults which can be overridden if required. You can do this via environment-specific configuration files, for example `development.json` and `test.json`. Environment variables are also respected, see [precedence order](https://github.com/mozilla/node-convict#precendence-order) for more information.
The general rule with modules in the `lib/` dir is "things that change together, stay together". This is largely a personal preference after having to maintain apps that instead group by function, but the approach is also summarised nicely in this [express code structure](https://github.com/focusaurus/express_code_structure) example.
4
+
5
+
Each module is usually an Express sub-app. Code that is shared across modules is either promoted (e.g. middleware), or is added to a specific app-wide registry (e.g. models).
The initialization procedure is based on [the approach taken by the Locomotive framework](http://www.locomotivejs.org/guide/initialization/). App initialization steps have been split into separate functions in
4
+
the `initializers/` folder, and are run in a certain order. Any required app-wide references are set on the [`app.locals`](https://expressjs.com/en/4x/api.html#app.locals) object.
The preference is to create high-level tests first in order to test the API end-to-end from a user’s perspective. From there we can drop down into lower-level tests like unit tests (this hasn't yet been done in this repo). See [Testing from the Outside-In](https://robots.thoughtbot.com/testing-from-the-outsidein) for more information.
Where possible Jest's [snapshot testing](https://facebook.github.io/jest/docs/en/snapshot-testing.html) feature is used in order to validate key parts of the API response. Where this is not straightforward, for example when the response returns creation dates which vary over time, we've fallen back to more specific assertions.
Since we're hitting a real DB via our functional tests, we want to run them serially in the current process using Jest's [`runInBand`](https://facebook.github.io/jest/docs/en/cli.html#runinband) option so they remain isolated. If the test suite gets expanded to include unit tests that don't hit the DB for example, then we may want to be specific about when we use that flag in order to keep the tests running as fast as possible.
0 commit comments