Testable architecture #86

mlvandijk · 2017-12-10T19:41:31Z

First version of Testable Architecture, of what I think is intended here, based on several blogs and podcasts.
Sources are listed under "More information:" but could be moved to blog-posts (and recommended media?).

Please review to see if I got the right meaning and didn't over simplify in my summary.

olleolleolle

I commented on tiny details of this article, which I think is a good article. It introduces the area.

olleolleolle · 2017-12-10T20:04:53Z

content/testable-architecture.md

+Automated tests and executable specifications can only work with software that has a testable architecture.
+A testable architecture enables fast and reliable tests that are easy to write, execute and maintain.
+Fast tests enable the developers to run them and obtain fast feedback on what they are building, without loosing focus or flow.


loosing => losing

olleolleolle · 2017-12-10T20:06:14Z

content/testable-architecture.md

+We want our tests to use some kind of in-memory stub implementation, instead of an actual database.
+From the perspective of the domain logic, the behavior looks exactly the same.
+To make sure that the stub works in the same way as the real thing, we need to have confidence, which we can obtain using ‘contract tests’.


Is the ornamentation around contract tests exactly what you want, here?

Not sure what you mean here. Do you mean the ' ' around 'contract tests'? Copied that from the https://sdjournal.org/bdd-like-jazz/ blogpost.

I mean the single quotes, yes.

Is "contract tests" not official naming, then perhaps single quotes are fine, but if we wish to make it stand out, then bold type could perhaps be helpful.

See, I'm all weasel words and equivocating. Sorry about that.

No problem. Thank you for proof reading all the time! It's hard to see the details when you've written and read the same doc several times. I really, really appreciate you taking the time to review; it makes the end result that much better!

Not sure if 'contract tests' is the 'official' name (see, doing it again with the ' '). There seems to be a lot of misunderstanding about different types of tests all the time. I might just rewrite a little bit and avoid the term 'contract tests' (unless someone can provide a link/definition).

olleolleolle · 2017-12-10T20:07:39Z

content/testable-architecture.md

+
+This architectural patterns is called the **ports and adapters pattern** (or [hexagonal architecture](http://alistair.cockburn.us/Hexagonal+architecture)).
+This pattern enables you to hook your scenarios and unit tests at a lower level, while he 'contract tests' give you the confidence to do that.


mlvandijk · 2017-12-11T19:00:57Z

@olleolleolle I've added a link to some more information about contract testing, which I hope helps a little for people unfamiliar with the term.

olleolleolle

Thanks for introducing this area.

tsundberg · 2017-12-12T10:25:33Z

content/testable-architecture.md

+Automated tests and executable specifications can only work with software that has a testable architecture.
+A testable architecture enables fast and reliable tests that are easy to write, execute and maintain.
+Fast tests enable the developers to run them and obtain fast feedback on what they are building, without losing focus or flow.


... enable the developers to run them and obtain ...

could use an additional word

... enable the developers to run them continuously and obtain ...

... enable the developers to run them often and obtain ...

... enable the developers to run them frequent and obtain ...

I'm not sure if the extra word should be 'continuously', 'often' or 'frequent'

tsundberg · 2017-12-12T10:28:48Z

content/testable-architecture.md

+When designing for testability, make sure that your products and services are composed of loosely-coupled,
+well-encapsulated components or modules; following the principles of
+[SOLID design](https://en.wikipedia.org/wiki/SOLID_(object-oriented_design)).


I would end this paragraph

... services are composed of loosely-coupled, well-encapsulated components or modules.

I wouldn't include the SOLID principles here. They could be added as a resource at the end instead.

tsundberg · 2017-12-12T10:30:59Z

content/testable-architecture.md

+makes it possible to test at different levels, with maximum confidence and minimum cost.
+
+* Ensure that you can run your tests underneath your UI. Do not depend solely on UI tests. They are slow, expensive, and hard to fix.


I would replace 'underneath' with 'below'.
I would also not use the abbrevation UI. I would introduce it as
... below your user interface, UI.

I would add brittle to the list of properties for a UI test.

They are slow, brittle, expensive, and hard to fix.

tsundberg · 2017-12-12T10:34:15Z

content/testable-architecture.md

+* Running tests against a database makes tests slow. And to make the tests behave consistently each time we run them,
+we need to make sure the database is in the expected state for each test, so the tests don't interfere with one another.
+


I would turn around this sentence:

"And to make the tests behave consistently each time we run them, we need to make sure the database is in the expected state for each test, so the tests don't interfere with one another."

Something like this:

We need to make sure the database is in the expected state for each test in order to make the tests behave consistently. This will ensure that the tests don't interfere with each other and can be executed in any order.

tsundberg · 2017-12-12T10:35:35Z

content/testable-architecture.md

+we need to make sure the database is in the expected state for each test, so the tests don't interfere with one another.
+
+We want our tests to use some kind of in-memory stub implementation, instead of an actual database.


I would rephrase "We want our tests to use some kind of in-memory stub implementation, instead of an actual database." as

"We want most of our tests to use some kind of in-memory stub implementation, instead of an actual database."

Making it a bit softer.

tsundberg · 2017-12-12T10:36:26Z

content/testable-architecture.md

+
+We want our tests to use some kind of in-memory stub implementation, instead of an actual database.
+From the perspective of the domain logic, the behavior looks exactly the same.


I would replace 'looks' with 'is'

tsundberg · 2017-12-12T10:38:00Z

content/testable-architecture.md

+
+We can think of our database and our stub as two things that can be plugged into the same socket, or **port**.
+The application containing the business logic doesn't need to know it's talking to a stub rather than the actual database; it's simply talking to this port


I would add 'if' in "doesn't need to know it's talking"

so it becomes

"doesn't need to know if it is talking"

I would also consider replacing 'rather than' with 'or'

tsundberg · 2017-12-12T10:41:52Z

content/testable-architecture.md

+
+The business logic is at the core of the application, completely decoupled from external devices and services. It doesn’t know anything about databases, message queues,
+and web services because we’ve isolated them through these ports. Often, these ports are connected to adapters that interact with the real implementation. There will be an adapter for the database,


I would change the 'and' in the enumeration of techniques to 'or' as in

"It doesn’t know anything about databases, message queues, and web services because ..."

would become

"It doesn’t know anything about databases, message queues, or web services because ..."

I would also use the complete words 'we have' instead of 'we’ve'

tsundberg · 2017-12-12T10:43:37Z

content/testable-architecture.md

+and web services because we’ve isolated them through these ports. Often, these ports are connected to adapters that interact with the real implementation. There will be an adapter for the database,
+an adapter for the queue, and an adapter for the web service. There is also a port that defines how we can interact with our system, such as
+a web server which plugs into this port and displays a UI in a browser. All the IO tends to happen outside of these ports.


I'm not sure I understand what you mean in this sentense:

"There is also a port that defines how we can interact with our system, such as a web server which plugs into this port and displays a UI in a browser. All the IO tends to happen outside of these ports."

I think it is the beginning that confuses me, 'There is also a port'

tsundberg · 2017-12-12T10:47:34Z

content/testable-architecture.md

+
+This architectural patterns is called the **ports and adapters pattern** (or [hexagonal architecture](http://alistair.cockburn.us/Hexagonal+architecture)).
+This pattern enables you to hook your scenarios and unit tests at a lower level, while the **contract tests** give you the confidence to do that.


I would remove the word 'the' before ports and adapter. Can't motivate more than I think it reads better.

I would replace 'This pattern' with 'It' and thus avoid the word This twice in two sentences next to each other.

I would use the word 'connect' instead of 'hook'

tsundberg · 2017-12-12T10:48:15Z

content/testable-architecture.md

+Diagnosing where the problem is in a full-stack, end-to-end test is really hard, because it can be anywhere.
+These tests are brittle because one change can break all your tests. They are also slow,
+as there is IO involved when going through a a browser, web service or database.


I would consider replacing "can break all your tests" with "can break all of them"

tsundberg

I think this can be merged.

aslakhellesoy

Excellent job @mlvandijk! You nailed it!

aslakhellesoy · 2017-12-13T23:10:55Z

content/testable-architecture.md

+To make sure that the stub works in the same way as the real thing, we need to have confidence, which we can obtain using [contract tests](https://martinfowler.com/bliki/IntegrationContractTest.html).
+
+We can think of our database and our stub as two things that can be plugged into the same socket, or **port**.


I think the word "socket" can easily be misunderstood as "TCP socket", so maybe clarify that it is a "socket", not a socket :-)

Thanks @aslakhellesoy ! Yeah, the "socket" here is used as a metaphor; I'll just remove it to avoid confusion.

mlvandijk added 2 commits December 8, 2017 21:25

First draft and links for Testable Architecture

42ff841

Update Testable Architecture

4db4146

mlvandijk requested a review from aslakhellesoy December 10, 2017 19:41

olleolleolle reviewed Dec 10, 2017

View reviewed changes

mlvandijk added 2 commits December 11, 2017 14:26

Fix typos

f747a47

Update link about contract tests

d92279e

olleolleolle approved these changes Dec 11, 2017

View reviewed changes

tsundberg self-requested a review December 12, 2017 10:20

tsundberg reviewed Dec 12, 2017

View reviewed changes

Update to clarify details and improve writing

953e32c

tsundberg approved these changes Dec 12, 2017

View reviewed changes

mlvandijk merged commit 6b58003 into master Dec 12, 2017

mlvandijk mentioned this pull request Dec 12, 2017

Add missing docs in new menu structure #80

Closed

10 tasks

aslakhellesoy reviewed Dec 13, 2017

View reviewed changes

mlvandijk deleted the testable-architecture branch December 17, 2017 06:13

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Testable architecture #86

Testable architecture #86

mlvandijk commented Dec 10, 2017

olleolleolle left a comment

olleolleolle Dec 10, 2017

olleolleolle Dec 10, 2017

mlvandijk Dec 11, 2017

olleolleolle Dec 11, 2017

olleolleolle Dec 11, 2017

mlvandijk Dec 11, 2017

mlvandijk Dec 11, 2017

olleolleolle Dec 10, 2017

mlvandijk commented Dec 11, 2017

olleolleolle left a comment

tsundberg Dec 12, 2017 •

edited

Loading

tsundberg Dec 12, 2017

tsundberg Dec 12, 2017

tsundberg Dec 12, 2017

tsundberg Dec 12, 2017

tsundberg Dec 12, 2017

tsundberg Dec 12, 2017 •

edited

Loading

tsundberg Dec 12, 2017

tsundberg Dec 12, 2017

tsundberg Dec 12, 2017

tsundberg Dec 12, 2017

tsundberg left a comment

aslakhellesoy left a comment

aslakhellesoy Dec 13, 2017

mlvandijk Dec 17, 2017


		This architectural patterns is called the ports and adapters pattern (or [hexagonal architecture](http://alistair.cockburn.us/Hexagonal+architecture)).
		This pattern enables you to hook your scenarios and unit tests at a lower level, while he 'contract tests' give you the confidence to do that.

		makes it possible to test at different levels, with maximum confidence and minimum cost.

		* Ensure that you can run your tests underneath your UI. Do not depend solely on UI tests. They are slow, expensive, and hard to fix.

		* Running tests against a database makes tests slow. And to make the tests behave consistently each time we run them,
		we need to make sure the database is in the expected state for each test, so the tests don't interfere with one another.

		we need to make sure the database is in the expected state for each test, so the tests don't interfere with one another.

		We want our tests to use some kind of in-memory stub implementation, instead of an actual database.


		We want our tests to use some kind of in-memory stub implementation, instead of an actual database.
		From the perspective of the domain logic, the behavior looks exactly the same.


		We can think of our database and our stub as two things that can be plugged into the same socket, or port.
		The application containing the business logic doesn't need to know it's talking to a stub rather than the actual database; it's simply talking to this port


		The business logic is at the core of the application, completely decoupled from external devices and services. It doesn’t know anything about databases, message queues,
		and web services because we’ve isolated them through these ports. Often, these ports are connected to adapters that interact with the real implementation. There will be an adapter for the database,

		To make sure that the stub works in the same way as the real thing, we need to have confidence, which we can obtain using [contract tests](https://martinfowler.com/bliki/IntegrationContractTest.html).

		We can think of our database and our stub as two things that can be plugged into the same socket, or port.

Testable architecture #86

Testable architecture #86

Conversation

mlvandijk commented Dec 10, 2017

olleolleolle left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mlvandijk commented Dec 11, 2017

olleolleolle left a comment

Choose a reason for hiding this comment

tsundberg Dec 12, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tsundberg Dec 12, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tsundberg left a comment

Choose a reason for hiding this comment

aslakhellesoy left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tsundberg Dec 12, 2017 •

edited

Loading

tsundberg Dec 12, 2017 •

edited

Loading