Skip to content

Commit 70f89e1

Browse files
jan-molakjan-molak
committed
docs(website): extracted the chapter on Serenity/JS architecture
1 parent b11bcbf commit 70f89e1

File tree

2 files changed

+175
-2
lines changed

2 files changed

+175
-2
lines changed

‎src/docs/handbook/architecture.mdx

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
---
2+
sidebar_position: 2
3+
title: Architecture
4+
---
5+
6+
# Serenity/JS Architecture
7+
8+
Serenity/JS is a **modular**, **full-stack acceptance testing framework** based on Node.js.
9+
The official Serenity/JS Node modules are distributed via [NPM](https://www.npmjs.com/)
10+
under the [`@serenity-js/*` namespace](https://www.npmjs.com/search?q=%40serenity-js), and you can use as many or as few of them as you need
11+
to improve the reporting capabilities of your test suite,
12+
integrate with the various interfaces of your system under test,
13+
and introduce advanced code reuse patterns in your organisation.
14+
15+
At the high level, Serenity/JS framework is a [**collection of modules**](/api) where each module provides at least one of the following:
16+
- [**Screenplay Pattern**](/handbook/design/screenplay-pattern)-based **integration library** for the given interface of your system under test
17+
- [**Test Runner Adapter**](/handbook/test-runners/) that translates your test runner events into [Serenity/JS domain events](/handbook/reporting/domain-events) used for [reporting](/handbook/reporting/)
18+
- [**Reporting Services**](/handbook/reporting/) that translate Serenity/JS domain events into test reports
19+
20+
To build a Serenity/JS-based test automation framework, you pick those Serenity/JS modules that provide the capabilities
21+
**supporting the type of testing** and **reporting** you want to do.
22+
If you wish, you can also **extend Serenity/JS** and create your own modules that [wrap another low-level integration library](/api/core/class/Ability),
23+
or interact with an interface that the framework itself doesn't support yet!
24+
25+
## Serenity/JS Test Runner Adapters
26+
27+
Serenity/JS **Test Runner Adapters** are tiny reporting libraries that **attach to your test runner of choice**.
28+
The responsibility of an adapter is to listen to the actions performed by the test runner and translate them to [Serenity/JS Domain Events](/handbook/reporting/domain-events),
29+
which are then used for [test reporting purposes](/handbook/reporting/).
30+
31+
:::tip First steps with Serenity/JS
32+
Setting up a Serenity/JS test runner adapter and reporting services is the first thing most developers do when introducing Serenity/JS to an existing code base.
33+
:::
34+
35+
Out of the box, Serenity/JS offers test runner adapters for the following test runners:
36+
- [Cucumber](/api/cucumber) - Serenity/JS supports **all latest major versions** of Cucumber.js
37+
- [Jasmine](/api/jasmine)
38+
- [Mocha](/api/mocha)
39+
- [Playwright Test](/api/playwright-test)
40+
- [Protractor](/api/protractor)
41+
- [WebdriverIO](/api/webdriverio)
42+
43+
## Serenity/JS Reporting Services
44+
45+
Just like the [core design patterns](/handbook/design/) in your Serenity/JS scenarios revolve around the [system metaphor](http://www.extremeprogramming.org/rules/metaphor.html)
46+
of a [stage performance](/handbook/design/screenplay-pattern), Serenity/JS reporting services follow the metaphor of a [_stage crew_](https://en.wikipedia.org/wiki/Running_crew).
47+
48+
:::tip What if I don't follow the Screenplay Pattern yet?
49+
Serenity/JS Reporting Services rely on [domain events](/handbook/reporting/domain-events) emitted by [actors](/api/core/class/Actor) _**and**_ Test Runner Adapters.
50+
If your test scenarios don't follow the Screenplay Pattern and have no actors yet, don't worry! Serenity/JS reports will present information gathered by the adapter
51+
and will start to include information provided by actors whenever you're ready to introduce them.
52+
:::
53+
54+
The [`StageCrewMembers`](/api/core/interface/StageCrewMember) observe the [actors](/api/core/class/Actor) on [`Stage`](/api/core/class/Stage),
55+
watch the [`Activities`](/api/core/class/Activity) they perform, and listen to the [domain events](/handbook/reporting/domain-events) emitted by their environment.
56+
They use the information they gather to [generate artifacts](/api/core-events/class/ArtifactGenerated), such as test reports,
57+
produce more events to prompt other crew members to action, or perform side effects like printing to the terminal, writing files to disk, or performing network or database calls.
58+
59+
Several of the Serenity/JS modules provide [`StageCrewMembers`](/api/core/interface/StageCrewMember) you can use for test reporting purposes:
60+
- [Console Reporter](/handbook/reporting/console-reporter) - writes text-based test reports to your computer terminal,
61+
- [Serenity BDD Reporter](/handbook/reporting/serenity-bdd-reporter) - emits [Serenity BDD](https://serenity-bdd.github.io/)-compatible JSON reports,
62+
to be archived via [`ArtifactArchiver`](/handbook/reporting/artifact-archiver)
63+
and consumed by the [Serenity BDD CLI](/handbook/reporting/serenity-bdd-reporter/#using-the-serenity-bdd-cli)
64+
to produce HTML reports and living documentation,
65+
- [Photographer](/handbook/reporting/photographer) - automatically captures screenshots of the web browser window used by the active actor,
66+
to be archived via [`ArtifactArchiver`](/handbook/reporting/artifact-archiver) and attached to [Serenity BDD reports](/handbook/reporting/serenity-bdd-reporter)
67+
- [Artifact Archiver](/handbook/reporting/artifact-archiver) - stores report artifacts on disk,
68+
- [Stream Reporter](/handbook/reporting/stream-reporter) - logs any events it receives to help you with debugging.
69+
70+
:::tip Creating custom reporting services
71+
Studying existing Serenity/JS reporting services will help you create your own [`StageCrewMembers`](/api/core/interface/StageCrewMember) that produce custom reports or send the results to external reporting or storage systems.
72+
:::
73+
74+
## Serenity/JS Screenplay Pattern APIs
75+
76+
Most Serenity/JS modules offer low-level [Screenplay Pattern](/handbook/design/screenplay-pattern) APIs:
77+
[Abilities](/api/core/class/Ability), [Questions](/api/core/class/Question) and [Activities](/api/core/class/Activity),
78+
dedicated to helping you integrate your test scenarios with the interfaces of your system under test and create elegant, business-focused test [DSLs](https://en.wikipedia.org/wiki/Domain-specific_language).
79+
80+
Out of the box, Serenity/JS enables integration with [web-](/handbook/web-testing/), [mobile-](/handbook/mobile-testing/), and [HTTP API-based](/handbook/api-testing/)
81+
interfaces and provides wrappers around battle-tested integration libraries to take care of the low-level interactions with your system.
82+
83+
In particular:
84+
- [**Serenity/JS Web module**](/api/web) provides the universal web testing façade - a set of integration library-agnostic Screenplay Pattern APIs dedicated to web UI testing
85+
- [**Serenity/JS Playwright module**](/api/playwright) provides wrappers around [Microsoft Playwright](https://playwright.dev/), to be used with the Serenity/JS Web module
86+
- [**Serenity/JS Protractor module**](/api/protractor) provides wrappers around [Angular Protractor](https://www.protractortest.org/#/), to be used with the Serenity/JS Web module
87+
- [**Serenity/JS WebdriverIO module**](/api/webdriverio) provides wrappers around [WebdriverIO](https://webdriver.io/), to be used with the Serenity/JS Web module
88+
- [**Serenity/JS REST module**](/api/rest) provides Screenplay Pattern APIs dedicated to HTTP and REST API testing, as well as wrappers around [Axios](https://github.com/axios/axios) HTTP client
89+
- [**Serenity/JS Local Server**](/api/local-server) provides Screenplay Pattern APIs dedicated to interacting with local HTTP servers, as well as wrappers supporting servers built with [Express](https://expressjs.com/),
90+
[Hapi](https://hapijs.com/), [Koa](https://koajs.com/), [Restify](http://restify.com/), and raw [Node.js](https://nodejs.org/en/docs/guides/anatomy-of-an-http-transaction/).
91+
92+
Apart from the integration modules, the framework also offers [**Serenity/JS Assertions**](/api/assertions) - a dedicated and interface-agnostic assertions library based on the Screenplay Pattern.
93+
94+
## What Serenity/JS modules do I need?
95+
96+
What Serenity/JS modules you need depends on the **type of tests** you want to write and the **lower-level integration libraries**
97+
you want to use.
98+
99+
For example, if you wanted to create a test suite that exercised a **REST API** and didn't need to touch the UI, you'd use:
100+
- [`@serenity-js/core`](/api/core)
101+
- [`@serenity-js/assertions`](/api/assertions)
102+
- [`@serenity-js/rest`](/api/rest)
103+
- plus a [test runner adapter](/handbook/test-runners/) and a [reporting module](/handbook/reporting/)
104+
105+
If you wanted to create a test suite that exercised a **web interface**, you'd need:
106+
- [`@serenity-js/core`](/api/core)
107+
- [`@serenity-js/assertions`](/api/assertions)
108+
- [`@serenity-js/web`](/api/web), plus a module providing wrappers for your integration library of choice, so [`@serenity-js/playwright`](/api/playwright), [`@serenity-js/protractor`](/api/protractor), or [`@serenity-js/webdriverio`](/api/webdriverio)
109+
- you'd also want a [test runner adapter](/handbook/test-runners/) and a [reporting module](/handbook/reporting/)
110+
111+
:::info Short on time? ⏱️
112+
**Serenity/JS Project Templates** and **Serenity/JS GitPods** come with all the appropriate Serenity/JS modules
113+
and lower-level integration and test tools already configured, so you can start automating your tests straight away!
114+
115+
Learn more about faster ways to get started using [Serenity/JS Project Templates](/handbook/project-templates/).
116+
:::
117+
118+
## Integration architecture summary
119+
120+
At the high level:
121+
- [**Serenity/JS Test Runner Adapter**](/handbook/test-runners/) attaches to your test runner and enables test reporting
122+
- [**Serenity/JS Screenplay Pattern**](/handbook/design/screenplay-pattern/) libraries provide an abstraction that enables your test scenarios to interact with the system under test,
123+
while being agnostic of the underlying integration tool
124+
- [**Serenity/JS Reporting Services**](/handbook/reporting/) combine the information provided by your test runner and any custom test automation code
125+
to produce test execution reports and living documentation in various formats
126+
127+
<figure>
128+
129+
```mermaid
130+
flowchart TB
131+
Developer["💻 You"]
132+
TestCode["Your Test Code"]
133+
IntegrationLibraries["Low-Level Integration Libraries"]
134+
SUT["Your System-Under-Test"]
135+
TestReports["Test Execution Reports"]
136+
Stage
137+
138+
subgraph TestRunner["Test Runner"]
139+
direction TB
140+
TestRunnerAdapter["Serenity/JS Test Runner Adapter"]
141+
end
142+
143+
subgraph TestCode["Your Test Code"]
144+
direction TB
145+
TestScenarios["Your Test Scenarios"]
146+
TestDSL["Your Custom Screenplay Pattern APIs"]
147+
end
148+
149+
subgraph SerenityModules["Serenity/JS Modules"]
150+
direction TB
151+
ScreenplayPatternAPIs["Serenity/JS Screenplay Pattern APIs"]
152+
end
153+
154+
subgraph ReportingServices["Serenity/JS Reporting Services"]
155+
direction TB
156+
StageCrewMember["StageCrewMember"]
157+
end
158+
159+
Developer -- invoke --> TestRunner
160+
161+
TestScenarios -- use --> TestDSL
162+
TestDSL -- use --> SerenityModules
163+
TestRunner -- executes --> TestCode
164+
TestRunnerAdapter --> |emits DomainEvents| Stage
165+
ScreenplayPatternAPIs --> |emit DomainEvents| Stage
166+
ScreenplayPatternAPIs --> |wrap| IntegrationLibraries
167+
IntegrationLibraries --> |interact with| SUT
168+
Stage --> |forwards DomainEvents| ReportingServices
169+
ReportingServices --> |produce| TestReports
170+
```
171+
172+
<figcaption>Serenity/JS integration architecture diagram</figcaption>
173+
</figure>

‎src/docs/releases/versioning.mdx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ with release versions [determined automatically](/community/contributing/commit-
1010
based on the commit messages introduced with changes
1111
introduced to the [`main` branch](https://github.com/serenity-js/serenity-js/tree/main) since the most recent release.
1212

13-
All [Serenity/JS modules](/handbook/getting-started/architecture) are released together, even if not all of them have changed in a given release.
13+
All [Serenity/JS modules](/handbook/architecture) are released together, even if not all of them have changed in a given release.
1414
This is to make it easier for you to stay up to date without having to worry about any compatibility issues between the framework's modules.
1515

1616
## Release cadence
@@ -29,7 +29,7 @@ Learn how to [keep your Serenity/JS project up to date](/releases/updating-seren
2929

3030
The [public APIs](/api) of the framework will not be removed or changed in a backward-incompatible way in minor or patch releases of the framework. However, from time to time some APIs might get marked as `@deprecated`.
3131

32-
When an API is marked as `@deprectated`, the documentation of the API will provide instructions on what other API has superseded the deprecated one. Additionally, a ticket marked as [`deprecation-notice`](https://github.com/serenity-js/serenity-js/labels/deprecation-notice) is raised on Serenity/JS GitHub, and you'll have at least 3 months since the ticket is raised to migrate the code using a deprecated api to the new alternative.
32+
When an API is marked as `@deprecated`, the documentation of the API will provide instructions on what other API has superseded the deprecated one. Additionally, a ticket marked as [`deprecation-notice`](https://github.com/serenity-js/serenity-js/labels/deprecation-notice) is raised on Serenity/JS GitHub, and you'll have at least 3 months since the ticket is raised to migrate the code using a deprecated api to the new alternative.
3333

3434
Removing a deprecated API will not affect the major version number of the Serenity/JS framework, but a new major version release will typically remove all the deprecated APIs implemented in the previous major version.
3535

0 commit comments

Comments
 (0)