Skip to content

Commit a5b5852

Browse files
huafuhuafu
committed
docs: quick diagrams about jest, ts-jest and e2e runner
1 parent cc45adc commit a5b5852

6 files changed

Lines changed: 301 additions & 0 deletions

File tree

‎doc/tech/e2e/index.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# e2e tests
2+
3+
## Preparing
4+
5+
The preparation of E2E test directory is done in `scripts/e2e.js`. Here is the process:
6+
7+
![Preparing E2E tests](https://www.plantuml.com/plantuml/svg/ZLExZjim4Epv5ODhpYw20wwqcmE2AzBT7qWqkR8OymMIEiTDlZrBoZBaWv6aKZ6SnywktdAHgKpEukaZKPJ9-2FUNzzHA9Vy91einEumUMq99N_xoS1U-508oHp78e2piHQ7oLYzFC21Xf08Af4iLRACX5b3aDUeT5PjCAkIYpY7T88swOjsJw_qyhlhAinebo_E6d_gkXxrcr42J7r8lnJ5Wk3n_GV8VveKl2DVyihmF1eUOiFHG5ADpTXoWYtpxrpH86cv1KYUm_XRa8MJk-wbhxutTS0Cs2puSxvMmgb9bP0kszg2nuQouMwtpMPtDh4sKz3xeAbpGK-MSZytmUesSs3Mv_bMhBcu_MnlXkgzKo5UCF206KCA3giWB3RtjCgqNm97gKxoIB11dHh_bdFjo8OQZehKiiZ6_GTxb1bgbFv8UfPe8YvyqiDHboS-EcwRpuvFQiDxKcRx6BnTMhkgwvjMLzl27VgtJF-dMQd-kTopv-xdDIR3vpD5ReU-zFHeXTUjyUTwaZfulaAnQocM2qCj_S8YkOGen1i_vp_r3m00 "Preparing E2E tests")
8+
9+
10+
## Running
11+
12+
When a test-case needs to be run with a given template within tests, here is what's happening (in `e2e/__helpers__/test-case/runtime.ts`):
13+
14+
![Running a test case](https://www.plantuml.com/plantuml/svg/TLN1Zjem4BtdAwpsK50BA_K8KdUlUwhK7m3ZJ8WNnuviPm5Lss_l6yS92RGS88p7Cs_Ul9cyX2Xzx1eZFltghDNsAAI85A9GCj2d8XqNnKPvaf74sVcJABNV5jRXhzV7EXP2lCOlneW3uQYgo9EDeYMVugmu3boaBREjQGs7EiYWmxeWs3bMiVeXw3iz_TdjE0boxCArCTgUThkdtyEj3txCGJ-sHQ4hiQXb06RhIjerhkmC1KRul1In9YiMLmfBvD_aQ3F7BGvI8OOghWCmtvqkXQULpspOjX7QWWPZaaFbl22fwXj9gRG184SSIoA3quLrIwvILqoZQw-YqeonygwPN9lnYMJPIziROwXAICza8emc97KJ54Dh6C15KHl5Vbhgdc7YRDzATP97MXcdJkit5-p-reFYN2EhM8n5CeWUmv066PXE9bu74QniG-rYCiy9dr2U1CEMETTYl9uwHYewhr4pQXJvAfNPSrPgS9rNFHy1zbeEyRgsb96x1YGD6EbCsTlw8ceQylO1AcTAyibsem3FtBPSu1kIhfMpbJwkty93YUmrTn6uL7LMHUtiyuC_I57StBEEjMXbcXHSZVZTPeTxZf8Qt3cmyaOJNI9BoXwpPOIV_eoooqSilS7iWCWF3M8vJZepo2yddKfmJdtsoOASoh6U2R67-dynykTVWdpeIAe1tqcVjtKKMb9QPg1tCnHSS-VGOqqtEJdWre01WTVEdK8_sHU9OQCCx-Zb0VYyKnJ2OhaNhp-J5qzZFsS87oMtEao6Q9Cbbmk3A9oz1qSHEqjr8M897Be8W1SmQ6KpxCftT0bncVrf79o20qmc3nyNLscLYUUInZvz7TV61DXdP9FHRR3RaYieUvZuOIINd67Hw11udgOQIDjqKCwTRlfevydypgE68kic3Vlrcx1qDjUXANTkI6h105rqI4FDSZjhwD9IKbjoEepoSw0CTx8zlqiOSEZV8CDhOxQXRvBo53jliVf3Pn8pw4rR52zmmUlnBm00 "Running a test case")

‎doc/tech/e2e/preparing.puml‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
@startuml "Preparing E2E tests"
2+
start
3+
4+
:bundle ts-jest;
5+
note right
6+
will build ts-jest before creating the bundle
7+
end note
8+
9+
:create temp work dir;
10+
note right
11+
`e2e/~__workdir_symlink__` links to it
12+
except on CI environments
13+
end note
14+
15+
while (for each template)
16+
note right
17+
tempaltes are in `e2e/~__templates__/`
18+
end note
19+
20+
if (template's build directory) then (esists)
21+
:wipe but `node_modules` dir;
22+
else (not exists)
23+
:create;
24+
endif
25+
26+
:copy files from template's dir to its build dir;
27+
28+
if (package lock file) then (exists)
29+
:read metadata;
30+
31+
if (package lock file) then (has changed)
32+
:remove `node_modules` dir;
33+
34+
:npm install (or ci);
35+
36+
:npm install ts-jest bundle;
37+
38+
else if (ts-jest bundle) then (has changed)
39+
:npm install ts-jest bundle;
40+
41+
else (hasn't changed)
42+
endif
43+
:write updated metadata;
44+
45+
else (not exists)
46+
endif
47+
48+
endwhile (done)
49+
50+
:all templates ready;
51+
52+
stop
53+
54+
@enduml

‎doc/tech/e2e/running.puml‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
@startuml "Running a test case"
2+
start
3+
4+
:create work dir;
5+
note right
6+
It'll be different per test-case
7+
and per template basis.
8+
end note
9+
-> e2e/~__workdir_symlink__/{template}/{test-case};
10+
11+
if (has a node_modules dir?) then (yes)
12+
:symlink node_modules;
13+
note left
14+
avoid re-running npm install
15+
for each test case and template;
16+
end note
17+
else (no)
18+
endif
19+
20+
:copy files from template;
21+
note right
22+
all files in template dir are
23+
copied to test case work dir
24+
except `node_modules` and
25+
`package-lock.josn`
26+
end note
27+
28+
while (for each file in test case dir)
29+
if (is snapshot dir) then (yes)
30+
:symlink dir;
31+
note left
32+
snapshots directories are symlinked
33+
to test case source dir so that
34+
updating them would update in the
35+
source folder
36+
end note
37+
38+
else if (is jest.config.js) then (yes)
39+
if (jest.config.js is function?) then (yes)
40+
:call with parent content;
41+
note left
42+
allows for
43+
extending
44+
end note
45+
else (no)
46+
endif
47+
48+
else (others)
49+
:copy;
50+
note right
51+
all files in test case source
52+
dir are copied to the work dir
53+
except `node_modules` and
54+
`package-lock.josn`
55+
end note
56+
57+
endif
58+
endwhile
59+
60+
:create special files;
61+
note right
62+
some special files are created
63+
to handle hooks for example and
64+
grab `process()` IO for later
65+
expectations
66+
end note
67+
68+
:update package.json;
69+
note right
70+
set a custom but fixed name
71+
and version in package.json
72+
which is specific to the
73+
test case + template
74+
end note
75+
76+
#tomato:run tests;
77+
78+
while (for each snapshot) is (missing in test case)
79+
:copy;
80+
note right
81+
while we symlinked each snapshots
82+
directory, newly created snapshots
83+
in non existing dir will need to
84+
be copied over into
85+
e2e/~__cases__/{test-case}
86+
end note
87+
endwhile
88+
89+
:return results;
90+
91+
stop
92+
93+
@enduml

‎doc/tech/process/index.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Jest processing
2+
3+
## Jest process
4+
5+
![Jest require()](https://www.plantuml.com/plantuml/svg/RP313e8m44Jl-nKJBfI3V00U9F6cNr5XaHees2u7_jwM81B3fSdElivCjlIYdKnzX-J6Nk3uFHd7Aak8bXLHyTNIndISPcSYqq2rsaD3dBQ-6Ln_oI0jMwYPVKP0HBObEqJyoNBLLSjtdlzneDZH-OvKUPw7J80xpr1sMF4fJAzO-J6PJax6BeojJKDhlB6eeib1Lloyx50DLjZAGS2-p-Y6YhtVkaIBiTQokkoYVoQhi9ql7YveH6LumyK_ "Jest require()")
6+
7+
8+
## TsJest process
9+
10+
![Jest require()](https://www.plantuml.com/plantuml/svg/bLHBhjim3Dph5CJhelOYEK02j6zTe40NlO1YKR5UPCaLvPS6oE5BIOu_-IpgXM6FnE6GG-cTeWnnw2oy_K2A4F3FO09MzPiGrpxu1ebyk8gyJOXTfBHjEwvKv8VGOBqNmcYegFM3LK0n67Sq-lAzXjYYW-g2L0k0tGTvDo_l6TfyWw5NCY9_5pBcGai8bVErGAUCBkJQM7IoGs2Cu6nY2rkrZNIVusnwdAW0d8y85dNax_G73b51zD3uhcVA32lKnfbeM5rAGmnobXoxLCFmzSllrb2qU1tZ0rIDR5fKzPMNaz1M4iHBZnj6cnENUjy65ja4v9f1Sf8SdT58OAKx0c7uD4Nzd3ihIht8FPjQLL8Q1pq6Oc7eOc5yahGq6Zhi5abryDr3S2PUvbvN1gyhIxMLncIBHcnHKN5XwKbwEdb263YVrudn5Z2jbtufa0V_kMYR4ZF3hIemb9WKd5dPjCpnYWLFzgPdjZZ_hSfzNaSCqb42Vters7KzmHpRkQ2SXqEjXGFUParDozn8GzxcchhCzKBKpVFi-ercQJyBrURlY70VUze_TtiDFtSyP-CXNnpybsTqFfdZiK_s7UG1xSEnp-ZpU-D-61ffBHMQpGT7P72IipoN_tDtfC6LEcBuLPYWzVxq83FbVjpswfPYZwsNCGtLkWHJHZZ5yjZ58RZYBVaEOvlsc_WrpqM6ywooFeVdaNjz-vGgTddqj0_TqdvU5EATtto1_mC0 "Jest require()")

‎doc/tech/process/jest.puml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
@startuml "Jest require()"
2+
3+
start
4+
5+
:require('file');
6+
7+
if (has a transform?) then (yes)
8+
if (transformer has getCacheKey?) then (yes)
9+
:transformer.getCacheKey(...);
10+
else (no)
11+
:use jest built-in;
12+
endif
13+
14+
if (in cache?) then (yes)
15+
:use cache content;
16+
else (no)
17+
:transformer.process(...);
18+
:update cache;
19+
endif
20+
21+
else (no)
22+
endif
23+
24+
:require();
25+
26+
end
27+
28+
@enduml

‎doc/tech/process/ts-jest.puml‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
@startuml "Jest require()"
2+
3+
|processor|
4+
start
5+
6+
:tsJest.process(source);
7+
8+
if (should stringify?) then (yes)
9+
:json stringify;
10+
-> update
11+
source;
12+
13+
else (no)
14+
endif
15+
16+
if (filename ends with .d.ts) then (yes)
17+
:wipe source;
18+
note left
19+
no need to compile
20+
definition files
21+
end note
22+
23+
else (no)
24+
25+
|#Thistle|compiler (cached)|
26+
if (has type-checking?) then (yes)
27+
:create and cache
28+
ts lang service;
29+
else (no)
30+
endif
31+
32+
-> source;
33+
34+
if (in persistent cache?) then (yes)
35+
:update mem cache
36+
from persistent cache;
37+
38+
else (no)
39+
if (has type checking?) then (yes)
40+
:compile with
41+
service;
42+
note left
43+
make use of the service
44+
created above and cached
45+
46+
mem cache is used when
47+
reading files
48+
end note
49+
50+
else (no)
51+
:compile with
52+
transpileModule;
53+
note right
54+
files will be compiled
55+
as isolated modules
56+
end note
57+
58+
endif
59+
60+
-> compiled source;
61+
62+
:fix source maps;
63+
:update mem cache;
64+
:update persistent cache;
65+
66+
endif
67+
|processor|
68+
69+
-> update
70+
source;
71+
72+
endif
73+
74+
if (should use babel?) then (yes)
75+
:babelJest.process(source);
76+
note left
77+
calls babel-jest
78+
processor
79+
end note
80+
-> update
81+
source;
82+
83+
else (no)
84+
endif
85+
86+
if (has afterProcess hook?) then (yes)
87+
:call afterProcess hook;
88+
-> update
89+
source;
90+
floating note left
91+
if the hook returns
92+
something it'll be
93+
used as new source
94+
end note
95+
96+
endif
97+
98+
:transformed source;
99+
100+
end
101+
102+
@enduml

0 commit comments

Comments
 (0)
⚡