From ff7efdf32f5df9169e60a46e718a2bd8b153040d Mon Sep 17 00:00:00 2001 From: Christian Westgaard Date: Tue, 14 May 2024 13:18:44 +0200 Subject: [PATCH] Fix #54 Remove the Globals chapter --- docs/client-side.adoc | 2 +- docs/globals.adoc | 128 ------------------ docs/index.adoc | 16 ++- docs/menu.json | 27 ++-- docs/mock.adoc | 8 +- docs/test.adoc | 2 +- src/jest/server/getAppConfig.test.ts | 34 ----- .../resources/lib/myproject/getAppConfig.ts | 6 - 8 files changed, 32 insertions(+), 191 deletions(-) delete mode 100644 docs/globals.adoc delete mode 100644 src/jest/server/getAppConfig.test.ts delete mode 100644 src/main/resources/lib/myproject/getAppConfig.ts diff --git a/docs/client-side.adoc b/docs/client-side.adoc index 7eba897..70a8117 100644 --- a/docs/client-side.adoc +++ b/docs/client-side.adoc @@ -88,4 +88,4 @@ You have now learned how to write a test for a React component using Jest and Re Now that we have some tests, it may be useful to store coverage reports in a tool that can show progress over time. One such tool is Codecov. -The following chapter will show you how to integrate <> with your project. +The following chapter will show you how to integrate <> with your project. diff --git a/docs/globals.adoc b/docs/globals.adoc deleted file mode 100644 index d287074..0000000 --- a/docs/globals.adoc +++ /dev/null @@ -1,128 +0,0 @@ -= Mocking Globals -:sourcedir: ../ - -This chapter introduces the concept of mocking. - -== Introduction - -Mocking is the concept of creating fake objects that stand in for real objects in the system. This way, you may test or simulate bigger parts of a system - even without that system being actually available. - -== Globals - -When programming in Javascript there is always a global scope. Depending on which Javascript engine/environment you are in, the global scope is different. - -TIP: Useful reading: https://developer.mozilla.org/en-US/docs/Glossary/Global_object[Global object^] - -== Browser - -In the browser, the global scope is the `window` object. The `window` object contains the `document` object that represents the current web page. The `document` object contains functions and properties that allow you to inspect and manipulate the web page. - -== XP Framework - -In the Enonic XP Framework the global scope contains a bunch of objects and functions that are useful when developing applications. - -TIP: You can read about them https://developer.enonic.com/docs/xp/stable/framework/globals[here^]. - -== Source code - -Let's start by adding some more code we can test: - -.src/main/resources/lib/myproject/getAppConfig.ts -[source, typescript] ----- -include::{sourcedir}src/main/resources/lib/myproject/getAppConfig.ts[] ----- - -== Test without mock - -Then, we write a simple test for the function above: - -.src/jest/server/getAppConfig.ts -[source, typescript] ----- -import { - describe, - expect, - test as it -} from '@jest/globals'; -import { getAppConfig } from '/lib/myproject/getAppConfig'; - - -describe('getAppConfig', () => { - it('should return the application config', () => { - expect(getAppConfig()).toEqual({}); - }); -}); ----- - -If you try to run this test without mocking some props on the global object, it will fail with the following error message: - -[source, shell] ----- -ReferenceError: log is not defined ----- - -NOTE: Since the starter-ts project template we used already have mocked the Enonic XP globals for us: you won't get that error. - -== Test with mock - -NOTE: All the configuration below is already set up for us by the starter-ts project template we used. 🎉 But here we explain the reasoning behind it. - -To avoid errors about globals not being defined, we have to mock the missing globals. In this example 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, the following can be added to the `serverSideConfig` within your `jest.config.ts` file: - -.jest.config.ts - serverSideConfig -[source, typescript] ----- -globals: { - app: { - name: 'com.example.myproject', - config: {}, - version: '1.0.0' - }, -}, ----- - -A more flexible solution, that also let you mock functions, like `log.info` is to use a setup file. -It will run before the execution of each test file. - -Example setup file: - -.src/jest/server/setupFile.ts -[source, typescript] ----- -include::{sourcedir}src/jest/server/setupFile.ts[] ----- - -Then, it must be registered it in the `serverSideConfig`: - -.jest.config.ts - serverSideConfig -[source, typescript] ----- -setupFiles: ['/src/jest/server/setupFile.ts'], ----- - -This will mock default values for the global `app` and `log` objects, and the values can be augmented in the test files. - -== Types - -To avoid type errors when accessing global objects and functions in the test files, you can import types directly from the `src/jest/server/global.d.ts` file, which is already set up for us by the starter-ts project template we used. - -.src/jest/server/global.d.ts -[source, typescript] ----- -include::{sourcedir}src/jest/server/global.d.ts[] ----- - -.src/jest/server/getAppConfig.test.ts -[source, typescript] ----- -include::{sourcedir}src/jest/server/getAppConfig.test.ts[] ----- - -== Summary - -In this chapter you learned how to mock global objects in the Enonic XP Framework when writing tests with Jest. - -Let's move on to the next chapter and learn how to <> and write our first "real" test for Enonic server-side code. diff --git a/docs/index.adoc b/docs/index.adoc index d729d38..c26599f 100644 --- a/docs/index.adoc +++ b/docs/index.adoc @@ -16,12 +16,16 @@ TIP: For more details, visit the https://jestjs.io/[Jest documentation^]. This guide will show you how to: -* Create a <> with Jest environment already setup. -* Write a simple <> without any mocks -* Write a test mocking <> -* Write a test for server-side code manually <> Java libraries -* Write a test for server-side code using <> -* Write a test for <> code +1. Create a <> with Jest environment already setup. +2. Write a simple <> without any mocks +3. Write a test for server-side code manually <> Java libraries +4. Write a test for server-side code using <> +5. Write a test for <> code + +== Advanced topics + +In addition to the main topics, you might want to learn about these advanced topics: + * Set up <> with Github Actions * <> tests with the code they test diff --git a/docs/menu.json b/docs/menu.json index e0efa4a..184dbbb 100644 --- a/docs/menu.json +++ b/docs/menu.json @@ -9,28 +9,29 @@ "document": "test" }, { - "title": "3 - Globals", - "document": "globals" - }, - { - "title": "4 - Functions", + "title": "3 - Mocking", "document": "mock" }, { - "title": "5 - Mock XP", + "title": "4 - Mock XP", "document": "mock-xp" }, { - "title": "6 - Client side", + "title": "5 - Client side", "document": "client-side" }, { - "title": "7 - Codecov", - "document": "codecov" - }, - { - "title": "8 - Colocation", - "document": "colocation" + "title": "Advanced", + "menuItems": [ + { + "title": "Codecov", + "document": "codecov" + }, + { + "title": "Colocation", + "document": "colocation" + } + ] } ] } diff --git a/docs/mock.adoc b/docs/mock.adoc index 2ba7384..7dbe9db 100644 --- a/docs/mock.adoc +++ b/docs/mock.adoc @@ -1,7 +1,11 @@ -= Mocking functions += Mocking :sourcedir: ../ -This chapter covers mocking functions and Enonic libraries. +This chapter introduces the concept of `mocking`. It shows how to mock functions and Enonic libraries. + +== Introduction + +Mocking is the concept of creating fake functions or objects that stand in for real functions or objects in the system. This way, you may test or simulate parts of a system - even without that system being actually available. == Source code diff --git a/docs/test.adoc b/docs/test.adoc index 99ccfc1..945d76e 100644 --- a/docs/test.adoc +++ b/docs/test.adoc @@ -74,4 +74,4 @@ Ran all test suites matching /src\/jest\/server\/fibonacci.test.ts/i. This chapter explained how to write and run a simple Jest test for an Enonic XP project. -In order to write more advanced tests, we must introduce a new concept. Let's have a look at <>. +In order to write more advanced tests, we must introduce a new concept. Let's have a look at <>. diff --git a/src/jest/server/getAppConfig.test.ts b/src/jest/server/getAppConfig.test.ts deleted file mode 100644 index 394093f..0000000 --- a/src/jest/server/getAppConfig.test.ts +++ /dev/null @@ -1,34 +0,0 @@ -import type {App, Log} from './global.d'; - -import { - beforeAll, - describe, - expect, - test as it -} from '@jest/globals'; - - -// Avoid type errors below. -declare module globalThis { - var app: App - var log: Log -} - - -// Augment the app.config object for tests in this file only. -globalThis.app.config.key = 'value'; - - -describe('getAppConfig', () => { - beforeAll(() => { - // Silence log.debug for tests under this describe. - globalThis.log.debug = () => {}; - }); - it('should return the application config', () => { - import('/lib/myproject/getAppConfig').then(({getAppConfig}) => { - expect(getAppConfig()).toEqual({ - key: 'value' - }); - }); - }); -}); diff --git a/src/main/resources/lib/myproject/getAppConfig.ts b/src/main/resources/lib/myproject/getAppConfig.ts deleted file mode 100644 index 2933e6d..0000000 --- a/src/main/resources/lib/myproject/getAppConfig.ts +++ /dev/null @@ -1,6 +0,0 @@ -export const getAppConfig = () => { - log.debug('getAppConfig() called'); - const config = app.config; - log.info('App config:%s', config); - return config; -};