wip #29 tweaks

docs/client-side.adoc

@@ -29,3 +29,9 @@ include::{sourcedir}src/main/resources/assets/js/HelloWorld.tsx[]
 ----
 include::{sourcedir}src/main/resources/assets/js/HelloWorld.test.tsx[]
 ----
+
+== Summary
+
+In this guide, we have learned how to write a test for a React component using Jest and React Test Renderer.
+
+Now that there exists some test, it may be useful to store coverage reports in a tool that can show changes over time. One such tool is Codecov. The following tutorial will show you how to integrate link:coverage[Codecov] with your project.

docs/coverage.adoc → docs/codecov.adoc

@@ -1,6 +1,9 @@
-= Coverage
+= Codecov
 :toc: right
 
+https://about.codecov.io/[Codecov,window=_blank,opts=nofollow] is a nice reporting tool that can be used to visualize your test coverage over time and across multiple projects. It integrates nicely with GitHub and other CI/CD tools.
+
+
 == Command line
 
 To get a nice test coverage report when running tests, simply add the `--coverage` option:
@@ -33,9 +36,6 @@ just add the `--coverage` option in the `package.json` 's `scripts` section like
 
 This also enables the `npm test` in the <<#github_action, Github action>> below to produce a coverage report for <<#codecov, Codecov>>.
 
-== Codecov
-
-https://about.codecov.io/[Codecov,window=_blank,opts=nofollow] is a nice reporting tool that can be used to visualize your test coverage across multiple projects. It integrates nicely with GitHub and other CI/CD tools.
 
 
 == GitHub action
@@ -76,3 +76,7 @@ jobs:
 
       - uses: codecov/codecov-action@v4
 ----
+
+== Summary
+
+With the above setup, you will get a nice test coverage report every time you run `npm test` and also every time you push to GitHub. The report will be sent to Codecov where you can visualize it and track your progress over time.

docs/globals.adoc

@@ -56,8 +56,9 @@ ReferenceError: log is not defined
 
 To fix that, both the `log` and `app` objects must be mocked.
 
-This can be achieved in multiple ways. When it comes to static values like the global `app` object we can add the following to the `serverSideConfig` in `jest.config.ts` file:
+This can be achieved in multiple ways. When it comes to static values like the global `app` object, the following can be added to the `serverSideConfig` in the `jest.config.ts` file:
 
+.jest.config.ts
 [source, typescript]
 ----
 globals: {
@@ -71,7 +72,7 @@ globals: {
 },
 ----
 
-But when it comes to functions like `log.info` we can use a setup File which is run before execution of each test file:
+But when it comes to functions like `log.info`, a setup file can be used. It will run before the execution of each test file:
 
 .test/server/setupFile.ts
 [source, typescript]
@@ -81,12 +82,13 @@ include::{sourcedir}test/server/setupFile.ts[]
 
 Then add the following to the `serverSideConfig` in `jest.config.ts` file:
 
+.jest.config.ts
 [source, typescript]
 ----
 setupFiles: ['<rootDir>/test/server/setupFile.ts'],
 ----
 
-The above will mock default values for the global `app` and `log` objects, which we can augment in the tests.
+The above will mock default values for the global `app` and `log` objects. The values can be augmented in the test files.
 
 To avoid type errors when accessing those objects, you can make a type declaration file referencing `@enonic-types/global`
 
@@ -103,3 +105,9 @@ Then you can import and use those types in the test file:
 ----
 include::{sourcedir}src/main/resources/lib/tutorial-jest/getAppConfig.test.ts[]
 ----
+
+== Summary
+
+In this tutorial, you learned how to mock global objects in the Enonic XP Framework when writing tests with Jest.
+
+Let's move on to the next tutorial to learn how to link:mock[mock] functions and write our first "real" test for a Enonic XP Framework server-side source code file.

docs/index.adoc

@@ -1,4 +1,4 @@
-= Introduction to testing with Jest
+= Testing XP apps with Jest
 :toc: right
 :experimental:
 :sourcedir: ../

docs/menu.json

@@ -25,8 +25,8 @@
         "document": "client-side"
       },
       {
-        "title": "7 - Coverage",
-        "document": "coverage"
+        "title": "7 - Codecov",
+        "document": "codecov"
       }
     ]
 }

docs/mock-xp.adoc

@@ -37,3 +37,12 @@ NOTE: If anyone is able to find or create a test for thymeleaf rendering, please
 ----
 include::{sourcedir}src/main/resources/controllers/preview.test.ts[]
 ----
+
+
+== Summary
+
+This guide, showed how to write tests for Enonic XP applications using Jest in combination with Mock XP.
+
+Mock XP was used to mock the Enonic XP *portal* API.
+
+The next tutorial will show how to write a link:client-side[client-side] test for an Enonic XP application.

docs/mock.adoc

@@ -3,7 +3,7 @@
 
 == Source code
 
-To demonstrate the power of mocking, we'll make a simple Typescript wrapper around an Enonic Java library:
+To demonstrate the power of mocking, let's make a simple Typescript wrapper around an Enonic Java library:
 
 .src/main/resources/lib/tutorial-jest/sanitize.ts
 [source, typescript]
@@ -42,7 +42,7 @@ Cannot find module '/lib/xp/common' from 'src/main/resources/lib/tutorial-jest/s
 
 This happens because the module file `/lib/xp/common` isn't available in the test environment. It only exists inside the application jar file, which is used at runtime in the Enonic XP server.
 
-So we have to "fake" it.
+In order to run the test successfully, a "fake" version of the module must be made available in the test environment. This is where mocking comes in.
 
 == Test with mock
 
@@ -56,3 +56,9 @@ Notice that `sanitize` is no longer "statically" imported at the beginning of th
 That's why a dynamic import in each test is used instead.
 
 Obviously this mock doesn't cover ascii-folding for the whole unicode range, but is sufficient enough to run this test.
+
+== Summary
+
+This guide showed how to mock a Java library in a Typescript file using Jest. This is neccessary when you want to test your code in a controlled environment, without having to rely on the actual library being present.
+
+Writing mocks for whole libraries can be a bit tedious, so in the next tutorial, the same test case will be repeated, but it will use a more convenitent link:mock-xp[Mock XP] library provided by Enonic.

docs/setup.adoc

@@ -3,7 +3,9 @@
 
 == Node modules
 
-In order to write tests in Typescript and run them a bunch of node modules needs to be installed:
+In order to write tests in Typescript and run them using Jest, a bunch of node modules needs to be installed.
+
+Run the following command at the root of the project:
 
 [source, shell]
 ----
@@ -60,6 +62,8 @@ In order to run tests the following needs to be added to the `package.json` file
 
 === build.gradle
 
+The Enonic XP framework uses gradle to build libraries and applications.
+
 In order to run the tests on every build, add the following to the `build.gradle` file:
 
 .build.gradle
@@ -99,3 +103,10 @@ const FILES_SERVER = globSync(
   }
 ).map(s => s.replaceAll('\\', '/')); // Windows compatibility
 ----
+
+== Summary
+
+With the above setup in place, it is possible to write tests in Typescript and run them using Jest.
+The tests will be run on every build and the coverage will be reported.
+
+Let's learn how to write our first link:test[test].

docs/test.adoc

@@ -1,6 +1,15 @@
 = Simple test
 :sourcedir: ../
 
+Test files import from *_sources_* and defines *_test cases_* with *_assertions_*.
+
+Test files written for Jest uses `describe` and `it` functions to organize the test cases.
+
+
+The `expect` function is used to write *_assertions_* and returns an object which contains a bunch of *_Jest matchers_*.
+
+The test below uses the `toEqual` matcher, see https://jestjs.io/docs/using-matchers for more matchers.
+
 == Source code
 
 .src/main/resources/lib/tutorial-jest/fibonacci.ts
@@ -17,6 +26,8 @@ include::{sourcedir}src/main/resources/lib/tutorial-jest/fibonacci.ts[]
 include::{sourcedir}src/main/resources/lib/tutorial-jest/fibonacci.test.ts[]
 ----
 
+
+
 == Execution
 
 Run all tests with npm:
@@ -39,3 +50,9 @@ Run a specific test with npm:
 ----
 npm test src/main/resources/lib/tutorial-jest/fibonacci.test.ts
 ----
+
+== Summary
+
+This tutorial showed how to write and run a simple Jest test for Enonic XP projects.
+
+In order to write more advanced tests, some concepts are important to know, let's learn how to mock link:globals[Globals].