From 3ee80099f9483ab1708453db6e36523b00a57229 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Harouna=20Traor=C3=A9?= Date: Wed, 31 Aug 2022 10:54:06 +0200 Subject: [PATCH 1/9] add writing tests for modules documentation --- docs/guide/writing-tests-for-modules.md | 162 ++++++++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 docs/guide/writing-tests-for-modules.md diff --git a/docs/guide/writing-tests-for-modules.md b/docs/guide/writing-tests-for-modules.md new file mode 100644 index 00000000..e2374883 --- /dev/null +++ b/docs/guide/writing-tests-for-modules.md @@ -0,0 +1,162 @@ +# Writing tests for modules + +## Requirements + +a running MongoDB server + +## Setup + +This setup assumes you will use the following packages + +- [apostrophe](https://www.npmjs.com/package/apostrophe): *ApostropheCMS is a full-featured, open source CMS built with Node.js that seeks to empower organizations by combining in-context editing and headless architecture in a full-stack JS environment* +- [eslint](https://www.npmjs.com/package/eslint): *ESLint is a tool for identifying and reporting on patterns found in ECMAScript/JavaScript code* +- [eslint-config-apostrophe](https://www.npmjs.com/package/eslint-config-apostrophe): *An ESLint configuration for ApostropheCMS core and officials modules* +- [mocha](https://www.npmjs.com/package/mocha): *Simple, flexible, fun JavaScript test framework for Node.js & The Browser* +```sh +npm install --save-dev apostrophe eslint eslint-config-apostrophe mocha +``` + +You will need to add some new scripts to your `package.json`. + +```json +{ + "scripts": { + "lint": "npm run eslint", + "eslint": "eslint .", + "test": "npm run lint && mocha" + } +} +``` + +When you call `npm test`, it will lint your files according to [eslint-config-apostrophe](https://www.npmjs.com/package/eslint-config-apostrophe) rules and run the tests using [mocha](https://www.npmjs.com/package/mocha). + +### Test folder + +You will need a `test/package.json` file referencing the repository URL of your module. Please replace `%module-name%` & `%module-repository-url%` with your module informations. + +e.g. for the module `[@apostrophecms/sitemap](https://github.com/apostrophecms/sitemap)` we use + +> `"@apostrophecms/sitemap": "git://github.com/apostrophecms/sitemap.git"` +> + +```json +{ + "/**": "This package.json file is not actually installed.", + " * ": "Apostrophe requires that all npm modules to be loaded by moog", + " */": "exist in package.json at project level, which for a test is here", + "dependencies": { + "apostrophe": "^3.8.1", + "%module-name%": "%module-repository-url%" + } +} +``` + +You don’t want to commit test files artifacts to git, please add the following to your `.gitignore` file + +```gitignore +# Test files +/test/apos-build +/test/public +/test/locales +``` + +## Writing tests + +We start with a single test file `test/index.js`. + +As your tests grows, you can break it down into multiple files based on your liking. + +Mocha does not play well with arrow-functions, more info at [https://mochajs.org/#arrow-functions](https://mochajs.org/#arrow-functions) + + +```javascript +// test/index.js +const assert = require('assert'); +const t = require('apostrophe/test-lib/util.js'); + +const getAppConfig = function (options = {}) { + return { + '@apostrophecms/express': { + options: { + session: { secret: 'supersecret' } + } + }, + '%module-name%': { + options: { + // pass the required options here + ...options + } + } + }; +}; + +describe('%module-name%', function () { + let apos; + + this.timeout(t.timeout); + + after(function () { + return t.destroy(apos); + }); + + it('should be a property of the apos object', async function () { + const appConfig = getAppConfig(); + + await t.create({ + root: module, + testModule: true, + modules: { + ...appConfig, + testRunner: { + handlers(self) { + return { + 'apostrophe:afterInit': { + checkModule () { + apos = self.apos; + assert(self.apos.modules['%module-name%']); + } + } + }; + } + } + } + }); + }); +}); +``` + +### Dependencies + +[apostrophe/test-lib/util.js](https://github.com/apostrophecms/apostrophe/blob/main/test-lib/util.js) contains some logic to create and destroy apostrophe instances for testing purposes. + +It exposes: + +- `t.create` to create an apostrophe instance +- `t.destroy` to delete the database when the apostrophe instance is destroyed +- `t.createAdmin` to create an admin user +- `t.getUserJar` to get a cookie jar for the admin user +- `t.timeout` can be set using an environment variable `TEST_TIMEOUT`, e.g.`TEST_TIMEOUT=5000 npm test` + +`[testModule](https://github.com/apostrophecms/apostrophe/blob/main/index.js#L468)` will tweak the Apostrophe environment suitably for unit tests + +## FAQ + +### MongoServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017 + +Apostrophe assumes by default that there is MongDB server running on `127.0.0.1:27017`. + +You can change it by using the environment variable `APOS_MONGODB_URI`. + +```sh +APOS_MONGODB_URI=mongodb://%mongodb-address% npm test +``` + +### Mocha doesn't seems to work with apostrophe + +Starting from Apostrophe 3.26.0, we now support Mocha 9+ ([CHANGELOG](https://github.com/apostrophecms/apostrophe/blob/main/CHANGELOG.md#fixes-2)) + +If you are using an older version of Apostrophe, please use Mocha 8. + +```sh +npm install --save-dev mocha@8 +``` From ff764f46459798657510cc10a2c71ebb7482a0ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Harouna=20Traor=C3=A9?= Date: Wed, 31 Aug 2022 11:01:58 +0200 Subject: [PATCH 2/9] use fixed anchor for link to changelog --- docs/guide/writing-tests-for-modules.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/guide/writing-tests-for-modules.md b/docs/guide/writing-tests-for-modules.md index e2374883..5379fbde 100644 --- a/docs/guide/writing-tests-for-modules.md +++ b/docs/guide/writing-tests-for-modules.md @@ -153,7 +153,8 @@ APOS_MONGODB_URI=mongodb://%mongodb-address% npm test ### Mocha doesn't seems to work with apostrophe -Starting from Apostrophe 3.26.0, we now support Mocha 9+ ([CHANGELOG](https://github.com/apostrophecms/apostrophe/blob/main/CHANGELOG.md#fixes-2)) +Starting from Apostrophe 3.26.0, we now support Mocha 9+ +([CHANGELOG](https://github.com/apostrophecms/apostrophe/blob/main/CHANGELOG.md#3260-2022-08-03)) If you are using an older version of Apostrophe, please use Mocha 8. From 43a841befcaa3b31a8d40be9e205a2e860d478b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Harouna=20Traor=C3=A9?= Date: Wed, 31 Aug 2022 11:05:23 +0200 Subject: [PATCH 3/9] cosmetic changes --- docs/guide/writing-tests-for-modules.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/guide/writing-tests-for-modules.md b/docs/guide/writing-tests-for-modules.md index 5379fbde..80238c3e 100644 --- a/docs/guide/writing-tests-for-modules.md +++ b/docs/guide/writing-tests-for-modules.md @@ -2,7 +2,7 @@ ## Requirements -a running MongoDB server +- A running MongoDB server ## Setup @@ -34,7 +34,7 @@ When you call `npm test`, it will lint your files according to [eslint-config-ap You will need a `test/package.json` file referencing the repository URL of your module. Please replace `%module-name%` & `%module-repository-url%` with your module informations. -e.g. for the module `[@apostrophecms/sitemap](https://github.com/apostrophecms/sitemap)` we use +e.g. for the module [@apostrophecms/sitemap](https://github.com/apostrophecms/sitemap) we use > `"@apostrophecms/sitemap": "git://github.com/apostrophecms/sitemap.git"` > @@ -45,7 +45,7 @@ e.g. for the module `[@apostrophecms/sitemap](https://github.com/apostrophecms/s " * ": "Apostrophe requires that all npm modules to be loaded by moog", " */": "exist in package.json at project level, which for a test is here", "dependencies": { - "apostrophe": "^3.8.1", + "apostrophe": "^3.26.0", "%module-name%": "%module-repository-url%" } } @@ -137,7 +137,7 @@ It exposes: - `t.getUserJar` to get a cookie jar for the admin user - `t.timeout` can be set using an environment variable `TEST_TIMEOUT`, e.g.`TEST_TIMEOUT=5000 npm test` -`[testModule](https://github.com/apostrophecms/apostrophe/blob/main/index.js#L468)` will tweak the Apostrophe environment suitably for unit tests +[testModule](https://github.com/apostrophecms/apostrophe/blob/main/index.js#L468) will tweak the Apostrophe environment suitably for unit tests ## FAQ @@ -154,7 +154,7 @@ APOS_MONGODB_URI=mongodb://%mongodb-address% npm test ### Mocha doesn't seems to work with apostrophe Starting from Apostrophe 3.26.0, we now support Mocha 9+ -([CHANGELOG](https://github.com/apostrophecms/apostrophe/blob/main/CHANGELOG.md#3260-2022-08-03)) +([Apostrophe 3.26.0 Changelog](https://github.com/apostrophecms/apostrophe/blob/main/CHANGELOG.md#3260-2022-08-03)) If you are using an older version of Apostrophe, please use Mocha 8. From f0c2af537519266247a384c5f303a55181d23801 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Harouna=20Traor=C3=A9?= Date: Tue, 13 Sep 2022 11:29:01 +0200 Subject: [PATCH 4/9] add test output and missing detail links --- docs/guide/writing-tests-for-modules.md | 122 ++++++++++++++---------- 1 file changed, 73 insertions(+), 49 deletions(-) diff --git a/docs/guide/writing-tests-for-modules.md b/docs/guide/writing-tests-for-modules.md index 80238c3e..64e9336a 100644 --- a/docs/guide/writing-tests-for-modules.md +++ b/docs/guide/writing-tests-for-modules.md @@ -68,62 +68,56 @@ As your tests grows, you can break it down into multiple files based on your lik Mocha does not play well with arrow-functions, more info at [https://mochajs.org/#arrow-functions](https://mochajs.org/#arrow-functions) - -```javascript -// test/index.js -const assert = require('assert'); -const t = require('apostrophe/test-lib/util.js'); - -const getAppConfig = function (options = {}) { - return { - '@apostrophecms/express': { - options: { - session: { secret: 'supersecret' } - } - }, - '%module-name%': { - options: { - // pass the required options here - ...options + + ```javascript + const assert = require('assert').strict; + const t = require('apostrophe/test-lib/util.js'); + + // getAppConfig is used to set options for Apostrophe and the module you want to test + const getAppConfig = function (options = {}) { + return { + '%module-name%': { + options: { + // Pass the required options here, if your module doesn't have any options + // please skip the `options` attribute + ...options, + custom: true + } } - } + }; }; -}; -describe('%module-name%', function () { - let apos; + describe('%module-name%', function () { + let apos; - this.timeout(t.timeout); + this.timeout(t.timeout); - after(function () { - return t.destroy(apos); - }); + before(async function () { + apos = await t.create({ + shortName: '%module-name%', + testModule: true, + modules: getAppConfig() + }); + }); - it('should be a property of the apos object', async function () { - const appConfig = getAppConfig(); - - await t.create({ - root: module, - testModule: true, - modules: { - ...appConfig, - testRunner: { - handlers(self) { - return { - 'apostrophe:afterInit': { - checkModule () { - apos = self.apos; - assert(self.apos.modules['%module-name%']); - } - } - }; - } - } - } + after(async function () { + await t.destroy(apos); + }); + + it('should have module options', async function () { + const actual = apos.modules['%module-name%'].options; + const expected = { + custom: true + }; + + assert.deepEqual(actual, expected); }); }); -}); -``` + ``` + + ### Dependencies @@ -137,7 +131,37 @@ It exposes: - `t.getUserJar` to get a cookie jar for the admin user - `t.timeout` can be set using an environment variable `TEST_TIMEOUT`, e.g.`TEST_TIMEOUT=5000 npm test` -[testModule](https://github.com/apostrophecms/apostrophe/blob/main/index.js#L468) will tweak the Apostrophe environment suitably for unit tests +[testModule](https://github.com/apostrophecms/apostrophe/blob/main/index.js#L468) will tweak the Apostrophe environment suitably for unit tests (i.e. set default modules options, check test files location, build module paths) + +- `describe` & `it` functions are provided by mocha, more info at [BDD](https://mochajs.org/#bdd) + +### Output + +By running the test using `npm test` command, you should see the output below + +``` +$ npm test + +> @apostrophecms/sitemap@1.0.1 test +> npm run lint && mocha + + +> @apostrophecms/sitemap@1.0.1 lint +> npm run eslint + + +> @apostrophecms/sitemap@1.0.1 eslint +> eslint . + + + + Apostrophe Sitemap +Listening at http://127.0.0.1:7780 + ✓ should have module options + + + 1 passing (909ms) +``` ## FAQ From 9d73c0d4bf828432ddae11db45b632abc482f0a7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Harouna=20Traor=C3=A9?= Date: Tue, 13 Sep 2022 15:17:28 +0200 Subject: [PATCH 5/9] use login hcaptcha as a reference --- docs/.vuepress/sidebar.js | 3 +- docs/guide/writing-tests-for-modules.md | 42 ++++++++++++++++++++----- 2 files changed, 37 insertions(+), 8 deletions(-) diff --git a/docs/.vuepress/sidebar.js b/docs/.vuepress/sidebar.js index 8f5b9bf1..e718e082 100644 --- a/docs/.vuepress/sidebar.js +++ b/docs/.vuepress/sidebar.js @@ -53,7 +53,8 @@ module.exports = { 'guide/front-end-helpers.md' ] }, - [ 'guide/media.md', 'Working with images and media' ] + [ 'guide/media.md', 'Working with images and media' ], + [ 'guide/writing-tests-for-modules.md', 'Writing tests for modules' ] ] }, { diff --git a/docs/guide/writing-tests-for-modules.md b/docs/guide/writing-tests-for-modules.md index 64e9336a..b0048d0b 100644 --- a/docs/guide/writing-tests-for-modules.md +++ b/docs/guide/writing-tests-for-modules.md @@ -1,5 +1,18 @@ # Writing tests for modules +Tests are useful to guarantee that the requirements of your application are met over time. + +You don't have to test over and over again the same scenarios, it's a time saving tool. + +There are many kind of tests + +- [unit testing](https://en.wikipedia.org/wiki/Unit_testing) where we test a single part of the application, a single + module, file commonly referred as a unit +- [integration testing](https://en.wikipedia.org/wiki/Integration_testing) where we test multiple parts of an + application working together as a group +- [system testing](https://en.wikipedia.org/wiki/System_testing), sometimes referred as [end-to-end testing](https://www.indeed.com/career-advice/career-development/end-to-end-testing) where we test the entire application +- and many more + ## Requirements - A running MongoDB server @@ -34,9 +47,9 @@ When you call `npm test`, it will lint your files according to [eslint-config-ap You will need a `test/package.json` file referencing the repository URL of your module. Please replace `%module-name%` & `%module-repository-url%` with your module informations. -e.g. for the module [@apostrophecms/sitemap](https://github.com/apostrophecms/sitemap) we use +e.g. for the module [@apostrophecms/login-hcaptcha](https://github.com/apostrophecms/login-hcaptcha) we use -> `"@apostrophecms/sitemap": "git://github.com/apostrophecms/sitemap.git"` +> `"@apostrophecms/login-hcaptcha": "git://github.com/apostrophecms/login-hcaptcha.git"` > ```json @@ -104,9 +117,10 @@ Mocha does not play well with arrow-functions, more info at [https://mochajs.org await t.destroy(apos); }); - it('should have module options', async function () { + it('should have module options', function () { const actual = apos.modules['%module-name%'].options; const expected = { + apos, custom: true }; @@ -142,20 +156,20 @@ By running the test using `npm test` command, you should see the output below ``` $ npm test -> @apostrophecms/sitemap@1.0.1 test +> @apostrophecms/login-hcaptcha@1.0.0 test > npm run lint && mocha -> @apostrophecms/sitemap@1.0.1 lint +> @apostrophecms/login-hcaptcha@1.0.0 lint > npm run eslint -> @apostrophecms/sitemap@1.0.1 eslint +> @apostrophecms/login-hcaptcha@1.0.1 eslint > eslint . - Apostrophe Sitemap + Apostrophe Login hCAPTCHA Listening at http://127.0.0.1:7780 ✓ should have module options @@ -163,6 +177,20 @@ Listening at http://127.0.0.1:7780 1 passing (909ms) ``` +### What's next? + +You can now test the additional methods you've provided with your module on [self](https://v3.docs.apostrophecms.org/reference/module-api/module-overview.html#methods-self). + +You can use any existing apostrophe modules with a `test` folder as a reference. + +You'll find below a non exhaustive list of modules: + +- [@apostrophecms/form](https://github.com/apostrophecms/form/blob/main/test/test.js) +- [@apostrophecms/login-hcaptcha](https://github.com/apostrophecms/login-hcaptcha/blob/main/test/test.js) +- [@apostrophecms/svg-sprite](https://github.com/apostrophecms/svg-sprite/blob/main/test/test.js) +- [@apostrophecms/scheduled-publishing](https://github.com/apostrophecms/scheduled-publishing/blob/main/test/test.js) +- [@apostrophecms/sitemap](https://github.com/apostrophecms/sitemap/blob/main/test/test.js) + ## FAQ ### MongoServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017 From a4a8f4eeb24688a8049818b29627562fbcd69e1d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Harouna=20Traor=C3=A9?= Date: Tue, 13 Sep 2022 21:31:27 +0200 Subject: [PATCH 6/9] use fictitious article module --- docs/guide/writing-tests-for-modules.md | 37 +++++++++++++++++++------ 1 file changed, 29 insertions(+), 8 deletions(-) diff --git a/docs/guide/writing-tests-for-modules.md b/docs/guide/writing-tests-for-modules.md index b0048d0b..86a03366 100644 --- a/docs/guide/writing-tests-for-modules.md +++ b/docs/guide/writing-tests-for-modules.md @@ -13,6 +13,12 @@ There are many kind of tests - [system testing](https://en.wikipedia.org/wiki/System_testing), sometimes referred as [end-to-end testing](https://www.indeed.com/career-advice/career-development/end-to-end-testing) where we test the entire application - and many more +This documentation focuses on how to test Apostrophe modules, not Apostrophe itself using integration testing. + +Modules should be stand-alone npm packages. + +We will use a fictitious module named `article` to illustrate how to write tests for modules. + ## Requirements - A running MongoDB server @@ -33,11 +39,26 @@ You will need to add some new scripts to your `package.json`. ```json { + "name": "article", + "version": "1.0.0", + "description": "A fictitious Apostrophe module", + "main": "index.js", "scripts": { "lint": "npm run eslint", "eslint": "eslint .", "test": "npm run lint && mocha" - } + }, + "keywords": [], + "author": "", + "license": "ISC" +} +``` + +Add the following to `.eslintrc.json` to tell eslint to use ApostropheCMS ESLint confiuration. + +```json +{ + "extends": [ "apostrophe" ] } ``` @@ -45,7 +66,7 @@ When you call `npm test`, it will lint your files according to [eslint-config-ap ### Test folder -You will need a `test/package.json` file referencing the repository URL of your module. Please replace `%module-name%` & `%module-repository-url%` with your module informations. +You will need a `test/package.json` file referencing the repository URL of your module. Please replace `article` & `%article-repository-url%` with your module informations. e.g. for the module [@apostrophecms/login-hcaptcha](https://github.com/apostrophecms/login-hcaptcha) we use @@ -59,7 +80,7 @@ e.g. for the module [@apostrophecms/login-hcaptcha](https://github.com/apostroph " */": "exist in package.json at project level, which for a test is here", "dependencies": { "apostrophe": "^3.26.0", - "%module-name%": "%module-repository-url%" + "article": "%article-repository-url%" } } ``` @@ -89,7 +110,7 @@ Mocha does not play well with arrow-functions, more info at [https://mochajs.org // getAppConfig is used to set options for Apostrophe and the module you want to test const getAppConfig = function (options = {}) { return { - '%module-name%': { + article: { options: { // Pass the required options here, if your module doesn't have any options // please skip the `options` attribute @@ -100,14 +121,14 @@ Mocha does not play well with arrow-functions, more info at [https://mochajs.org }; }; - describe('%module-name%', function () { + describe('article', function () { let apos; this.timeout(t.timeout); before(async function () { apos = await t.create({ - shortName: '%module-name%', + shortName: 'article', testModule: true, modules: getAppConfig() }); @@ -118,7 +139,7 @@ Mocha does not play well with arrow-functions, more info at [https://mochajs.org }); it('should have module options', function () { - const actual = apos.modules['%module-name%'].options; + const actual = apos.modules.article.options; const expected = { apos, custom: true @@ -183,7 +204,7 @@ You can now test the additional methods you've provided with your module on [sel You can use any existing apostrophe modules with a `test` folder as a reference. -You'll find below a non exhaustive list of modules: +You'll find below a non exhaustive list of such modules: - [@apostrophecms/form](https://github.com/apostrophecms/form/blob/main/test/test.js) - [@apostrophecms/login-hcaptcha](https://github.com/apostrophecms/login-hcaptcha/blob/main/test/test.js) From d6fd36e7a230285183a583b6d2d09a2dec044f53 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Harouna=20Traor=C3=A9?= Date: Mon, 3 Oct 2022 15:00:12 +0200 Subject: [PATCH 7/9] add context to function call and AposCodeBlock to snippets --- docs/guide/writing-tests-for-modules.md | 131 +++++++++++++++--------- 1 file changed, 83 insertions(+), 48 deletions(-) diff --git a/docs/guide/writing-tests-for-modules.md b/docs/guide/writing-tests-for-modules.md index 86a03366..1635e6d0 100644 --- a/docs/guide/writing-tests-for-modules.md +++ b/docs/guide/writing-tests-for-modules.md @@ -1,13 +1,15 @@ # Writing tests for modules Tests are useful to guarantee that the requirements of your application are met over time. +They also ensure that code changes don't generate breaking artifacts. -You don't have to test over and over again the same scenarios, it's a time saving tool. +Automating tests for expected scenarios saves significant time over having to mock those same scenarios manually each +time there are code changes. -There are many kind of tests +There are many kinds of tests: - [unit testing](https://en.wikipedia.org/wiki/Unit_testing) where we test a single part of the application, a single - module, file commonly referred as a unit + module or file commonly referred as a unit - [integration testing](https://en.wikipedia.org/wiki/Integration_testing) where we test multiple parts of an application working together as a group - [system testing](https://en.wikipedia.org/wiki/System_testing), sometimes referred as [end-to-end testing](https://www.indeed.com/career-advice/career-development/end-to-end-testing) where we test the entire application @@ -15,9 +17,9 @@ There are many kind of tests This documentation focuses on how to test Apostrophe modules, not Apostrophe itself using integration testing. -Modules should be stand-alone npm packages. - -We will use a fictitious module named `article` to illustrate how to write tests for modules. +Modules should be stand-alone npm packages. They need to be hosted somewhere that our testing can access. For this +example, we are hosting this module in a github repo. We will use a fictitious module named `article` to illustrate how to +write tests for modules. ## Requirements @@ -37,30 +39,40 @@ npm install --save-dev apostrophe eslint eslint-config-apostrophe mocha You will need to add some new scripts to your `package.json`. -```json -{ - "name": "article", - "version": "1.0.0", - "description": "A fictitious Apostrophe module", - "main": "index.js", - "scripts": { - "lint": "npm run eslint", - "eslint": "eslint .", - "test": "npm run lint && mocha" - }, - "keywords": [], - "author": "", - "license": "ISC" -} -``` + + ```json + { + "name": "article", + "version": "1.0.0", + "description": "A fictitious Apostrophe module", + "main": "index.js", + "scripts": { + "lint": "npm run eslint", + "eslint": "eslint .", + "test": "npm run lint && mocha" + }, + "keywords": [], + "author": "", + "license": "ISC" + } + ``` + + Add the following to `.eslintrc.json` to tell eslint to use ApostropheCMS ESLint confiuration. -```json -{ - "extends": [ "apostrophe" ] -} -``` + + ```json + { + "extends": [ "apostrophe" ] + } + ``` + + When you call `npm test`, it will lint your files according to [eslint-config-apostrophe](https://www.npmjs.com/package/eslint-config-apostrophe) rules and run the tests using [mocha](https://www.npmjs.com/package/mocha). @@ -73,37 +85,49 @@ e.g. for the module [@apostrophecms/login-hcaptcha](https://github.com/apostroph > `"@apostrophecms/login-hcaptcha": "git://github.com/apostrophecms/login-hcaptcha.git"` > -```json -{ - "/**": "This package.json file is not actually installed.", - " * ": "Apostrophe requires that all npm modules to be loaded by moog", - " */": "exist in package.json at project level, which for a test is here", - "dependencies": { - "apostrophe": "^3.26.0", - "article": "%article-repository-url%" + + ```json + { + "/**": "This package.json file is not actually installed.", + " * ": "Apostrophe requires that all npm modules to be loaded by moog", + " */": "exist in package.json at project level, which for a test is here", + "dependencies": { + "apostrophe": "^3.26.0", + "article": "%article-repository-url%" + } } -} -``` + ``` + + You don’t want to commit test files artifacts to git, please add the following to your `.gitignore` file -```gitignore -# Test files -/test/apos-build -/test/public -/test/locales -``` + + ```gitignore + # Test files + /test/apos-build + /test/public + /test/locales + ``` + + ## Writing tests -We start with a single test file `test/index.js`. +We will start with a single test file `test/index.js`. -As your tests grows, you can break it down into multiple files based on your liking. +As your test grows, you can break them down into multiple files based on your liking. Mocha does not play well with arrow-functions, more info at [https://mochajs.org/#arrow-functions](https://mochajs.org/#arrow-functions) ```javascript + // We use assert strict assertion mode, value and type must be the same when doing a comparison, .i.e. === + // https://nodejs.org/api/assert.html#strict-assertion-mode const assert = require('assert').strict; const t = require('apostrophe/test-lib/util.js'); @@ -112,8 +136,9 @@ Mocha does not play well with arrow-functions, more info at [https://mochajs.org return { article: { options: { - // Pass the required options here, if your module doesn't have any options - // please skip the `options` attribute + // Pass the required options here + // In the example below, we will test for the presence of a `custom` option + // If your module doesn't have any options, please skip the `options` attribute ...options, custom: true } @@ -121,11 +146,19 @@ Mocha does not play well with arrow-functions, more info at [https://mochajs.org }; }; + // describe and it functions are provided by mocha + // Usually use to "structure" the test file + // They don't have a strict meaning from mocha's point of view + + // describe is a test suite and used to group tests + // You can have as many describe as you want in a test file + // describe can be nested describe('article', function () { let apos; this.timeout(t.timeout); + // before is a hook and will run once before every describe/it found below before(async function () { apos = await t.create({ shortName: 'article', @@ -134,10 +167,12 @@ Mocha does not play well with arrow-functions, more info at [https://mochajs.org }); }); + // after is a hook and will run once after every describe/it found below after(async function () { await t.destroy(apos); }); + // it is used for an individual test case, e.g. testing a single function it('should have module options', function () { const actual = apos.modules.article.options; const expected = { @@ -172,7 +207,7 @@ It exposes: ### Output -By running the test using `npm test` command, you should see the output below +By running the test using the example `@apostrophecms/login-hcaptcha` module details and the `npm test` command, you should see the output below ``` $ npm test From 195c2e28b1049d9a4115b85466d1db3aa4b29887 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Harouna=20Traor=C3=A9?= Date: Fri, 11 Nov 2022 15:46:26 +0100 Subject: [PATCH 8/9] fix typos --- docs/guide/writing-tests-for-modules.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/guide/writing-tests-for-modules.md b/docs/guide/writing-tests-for-modules.md index 1635e6d0..39b1e07b 100644 --- a/docs/guide/writing-tests-for-modules.md +++ b/docs/guide/writing-tests-for-modules.md @@ -3,8 +3,8 @@ Tests are useful to guarantee that the requirements of your application are met over time. They also ensure that code changes don't generate breaking artifacts. -Automating tests for expected scenarios saves significant time over having to mock those same scenarios manually each -time there are code changes. +Automating tests for expected scenarios saves significant time over having to manually execute a regression test plan +each time there are code changes. There are many kinds of tests: @@ -18,7 +18,7 @@ There are many kinds of tests: This documentation focuses on how to test Apostrophe modules, not Apostrophe itself using integration testing. Modules should be stand-alone npm packages. They need to be hosted somewhere that our testing can access. For this -example, we are hosting this module in a github repo. We will use a fictitious module named `article` to illustrate how to +example, we are hosting this module in a GitHub repo. We will use a fictitious module named `article` to illustrate how to write tests for modules. ## Requirements @@ -89,7 +89,7 @@ e.g. for the module [@apostrophecms/login-hcaptcha](https://github.com/apostroph ```json { "/**": "This package.json file is not actually installed.", - " * ": "Apostrophe requires that all npm modules to be loaded by moog", + " * ": "Apostrophe requires that all npm modules to be loaded", " */": "exist in package.json at project level, which for a test is here", "dependencies": { "apostrophe": "^3.26.0", @@ -147,10 +147,10 @@ Mocha does not play well with arrow-functions, more info at [https://mochajs.org }; // describe and it functions are provided by mocha - // Usually use to "structure" the test file + // Usually used to "structure" the test file // They don't have a strict meaning from mocha's point of view - // describe is a test suite and used to group tests + // describe is a test suite and is used to group tests // You can have as many describe as you want in a test file // describe can be nested describe('article', function () { From 9c6df58208f7a688ce9a6596da653865ea314ee4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Harouna=20Traor=C3=A9?= Date: Mon, 2 Jan 2023 11:57:14 +0100 Subject: [PATCH 9/9] adding linting details --- docs/guide/writing-tests-for-modules.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/guide/writing-tests-for-modules.md b/docs/guide/writing-tests-for-modules.md index 39b1e07b..5497bc2b 100644 --- a/docs/guide/writing-tests-for-modules.md +++ b/docs/guide/writing-tests-for-modules.md @@ -15,7 +15,7 @@ There are many kinds of tests: - [system testing](https://en.wikipedia.org/wiki/System_testing), sometimes referred as [end-to-end testing](https://www.indeed.com/career-advice/career-development/end-to-end-testing) where we test the entire application - and many more -This documentation focuses on how to test Apostrophe modules, not Apostrophe itself using integration testing. +This documentation focuses on how to test and lint Apostrophe modules, not Apostrophe itself using integration testing. Modules should be stand-alone npm packages. They need to be hosted somewhere that our testing can access. For this example, we are hosting this module in a GitHub repo. We will use a fictitious module named `article` to illustrate how to @@ -30,8 +30,8 @@ write tests for modules. This setup assumes you will use the following packages - [apostrophe](https://www.npmjs.com/package/apostrophe): *ApostropheCMS is a full-featured, open source CMS built with Node.js that seeks to empower organizations by combining in-context editing and headless architecture in a full-stack JS environment* -- [eslint](https://www.npmjs.com/package/eslint): *ESLint is a tool for identifying and reporting on patterns found in ECMAScript/JavaScript code* -- [eslint-config-apostrophe](https://www.npmjs.com/package/eslint-config-apostrophe): *An ESLint configuration for ApostropheCMS core and officials modules* +- [eslint](https://www.npmjs.com/package/eslint): *ESLint is a tool for identifying and reporting on patterns found in ECMAScript/JavaScript code, with the goal of making code more consistent and avoiding bugs.* +- [eslint-config-apostrophe](https://www.npmjs.com/package/eslint-config-apostrophe): *An ESLint configuration for ApostropheCMS core and officials modules*. You can use your own [eslint configuration](https://eslint.org/docs/latest/user-guide/configuring/) instead. - [mocha](https://www.npmjs.com/package/mocha): *Simple, flexible, fun JavaScript test framework for Node.js & The Browser* ```sh npm install --save-dev apostrophe eslint eslint-config-apostrophe mocha