Server folder restructuring & test tooling & test refactoring

We have a few goals of restructuring the codebase that we have agreed on but aren’t documented anywhere. This issue serves as a place to document what we plan to do & as a place to document new utils and concepts that are intended to make our lives easier and help us move faster.

---

Lib & Lib common

Add a new lib folder, to contain all of the shared libraries in Ghost.

Underneath this, a new common folder, which contains the libraries that are used everywhere:

• events
• errors
• i18n
• logging

These 4 things need to be exposed to the whole of Ghost including theme helpers, apps & adapters.

They are are all effectively “read only” things - it’s not possible to affect behaviour by using these libraries.

Other things that might live under lib, would be an apps folder that contains all the code which manages apps, whereby the top level apps folder contains Ghosts built-in “internal” apps.

Services

There is a second type/set of shared libraries in Ghost, which I would call “services”. These cannot be exposed to apps/adapters/themes directly without creating security concerns or permissions problems:

• xmlrpc/slack/zapier “ping” services
• mail
• auth
• sitemaps
• rss
• permissions?
• config?

In the near future this might also feature a new url and/or routing service.

Services might end up having some sort of registry in future.

Clearing up data

The data folder is a crutch. It’s full of all kinds of weird stuff that has always needed a proper home. Not sure how we’re going to move forward with the meta folder just yet, but we know this is a nightmare.

Many of the these things will get moved to services over time.

A fresh look at utils

We’ve bunged an awful lot of stuff in “utils” over the years. Some of it should be there, some of it should probably be in a service (url stuff). Some of it should belong TO a library or service, and some of it can be farmed out to either be a dependency or by using a new dependency.

Tests

We want to focus mainly on unit testing and either the route-based functional tests, or the integration tests. There’s a whole bunch of tests which can/should be removed or replaced. The aim is to make tests FAST so we can ship FAST.

The utilities & fixtures around tests need to be similarly split up so that different types of test have different types of utilities, and that fixtures for specific bits of data or config are easier to find / write.

Where we have defined data structures, we can move towards using more custom should assertions - E.g. for testing that API responses or resources look how we expect them to look.

---

There’s not going to be any one big push towards doing this, but it is expected that PRs and commits go by that make small movements towards these goals.

---

Rough task list

(so we know when we can close this)

Structure:

• Moved to having a lib
• Moved to having a services folder and most of the “interesting” stuff lives in there… [this is almost done, i am not sure right now what else to move to services]
• Add lib/common with the common errors, events etc & a special way to require these
• Get rid of the utils folder, finding these things a better home
• Data folder doesn’t contain random things
• New web folder for all the expressy stuff

Test refactoring:

• try to speed up routing tests (start/stop behaviour of the server and db reset)
• split tests into acceptance, regression and unit tests
• cronjob for regression tests
• re-work acceptance tests
• re-work regression tests
• tidy up bad unit tests

Tools:

• Switch to eslint
• Upgrade sinon
• Upgrade as much as possible test deps
• re-use request utility everywhere (e.g. https://github.com/TryGhost/Ghost/blob/bffb3dbd90bfe572798f81645e3cea908570b978/core/server/api/webhooks.js#L17-L17)

[ErisDS]

Old table (minus module tests)

Node	DB	Routes (307)	Unit (1514)	Integration (554)	Total
v8	sqlite	2m	15s	3m	6:53
v8	mysql	3m	18s	3m	7:19
v6	sqlite	3m	20s	3m	8:52
v6	mysql	4m	29s	4m	8:39
v4	sqlite	4m	26s	4m	11:55
v4	mysql	4m	21s	3m	8:56

Updated version, based on this recent build which fixed a broken test.

Node	DB	Routes (530)	Unit (2106)	Integration (328)	Time
v10	sqlite	4m	34s	4m	11:8m
v10	mysql	4m	32s	3m	9:09
v8	sqlite	4m	30s	3m	10:12
v8	mysql	4m	32s	3m	9:14
v6	sqlite	5m	33s	4m	10:39
v6	mysql	5m	44s	4m	11:25

Total time: 18 min 28 sec

Some observations:

• Node v10 is a bit slower than Node v8
• Unit tests are taking almost twice as long as 1 yr ago
• Time on BOTH integration and route testing has gone up by ~1min

The increased time on unit tests would be fine if we were seeing a significant reduction in the route or integration tests. Instead, we’ve got increases across the board.

I know we have more code and more features, but this is getting out of control. It feels like tests are getting in our way more than they are helping.

Using the Node v10 SQLite build as the gold standard, any test that runs at over 1000ms needs to be rewritten. Any unit tests which use the database must also be rewritten.

Any remaining > 1000ms test, or unit tests using the DB will be deleted on 14th Jan 😬

[kirrg001]

We had a chat about the test env improvements and we realised that we want to much at once and we need to set smaller goals.

Goals for next Monday

• Naz will reduce the model regression tests to its need
• Kate will provide a utility in Ghost-utils to start/stop an instance

We will set tiny goals every week, which are achievable on a Monday.