[cypress] Rename deleteFolder to clarify function (#43663)

* [cypress] Rename deleteFolder to clarify function

- rename deleteFolder > deleteRelativePath
  - to respect the custom task also deletes files and it does it relative to cmsPath
- rename writeFile > writeRelativeFile
  - to unify task naming and to clarify it write relative to cmsPath
- additinal:
  - small comment enhancements
  - using const name 'path' from require('path');

- no functionality is changed, only method name, variable name and comment changes
- this is a follow-up to PR #43656
- tested on branch dev-4.4 successfully

* Change to writeRelativeFile in 2 samples too

tests/System/README.md

@@ -165,15 +165,15 @@ The Joomla System Tests come with some convenient [Cypress Tasks](https://docs.c
 
 - **queryDB** – Executes a query on the database
 - **cleanupDB** – Deletes the inserted items from the database
-- **writeFile** – Writes a file relative to the CMS root folder
-- **deleteFolder** – Deletes a folder relative to the CMS root folder
+- **writeRelativeFile** – Writes a file relative to the CMS root folder
+- **deleteRelativePath** – Deletes a file or folder relative to the CMS root folder
 - **startMailServer** – Starts the smtp-tester SMTP server
 - **getMails** – Get received mails from smtp-tester
 - **clearEmails** – Clear all smtp-tester received mails
 
 The following code in a test executes the writing file task with parameters:
 ```JavaScript
- cy.task('writeFile', { path: 'images/dummy.text', content: '1' }).then(() =>  { ... })
+ cy.task('writeRelativeFile', { path: 'images/dummy.text', content: '1' }).then(() =>  { ... })
 ```
 :point_right: As each task is asynchronous and must be chained, the result includes `.then()`.
 
@@ -273,7 +273,7 @@ If the Cypress installation step or the entire test suite is executed by a non-r
 ```
 1) Install Joomla
        Install Joomla:
-       CypressError: `cy.task('writeFile')` failed with the following error:
+       CypressError: `cy.task('writeRelativeFile')` failed with the following error:
        > EACCES: permission denied, open './configuration.php'
 ```
 Or on Microsoft Windows you will see:

tests/System/integration/api/com_media/Files.cy.js

@@ -1,7 +1,8 @@
 describe('Test that media files API endpoint', () => {
-  // Ensure test dir is available and has correct permissions
-  beforeEach(() => cy.task('writeFile', { path: 'images/test-dir/dummy.txt', content: '1' }));
-  afterEach(() => cy.task('deleteFolder', 'images/test-dir'));
+  // Ensure 'test-dir' (relative to cmsPath) is available and has correct permissions
+  beforeEach(() => cy.task('writeRelativeFile', { path: 'images/test-dir/dummy.txt', content: '1' }));
+  // If it exists, delete the 'test-dir' (relative to cmsPath) and its contents
+  afterEach(() => cy.task('deleteRelativePath', 'images/test-dir'));
 
   it('can deliver a list of files', () => {
     cy.api_get('/media/files')
@@ -101,7 +102,7 @@ describe('Test that media files API endpoint', () => {
   });
 
   it('can update a file without adapter', () => {
-    cy.task('writeFile', { path: 'images/test-dir/override.jpg', content: '1' })
+    cy.task('writeRelativeFile', { path: 'images/test-dir/override.jpg', content: '1' })
       .then(() => cy.readFile('tests/System/data/com_media/test-image-1.jpg', 'binary'))
       .then((data) => cy.api_patch(
         '/media/files/test-dir/override.jpg',
@@ -117,7 +118,7 @@ describe('Test that media files API endpoint', () => {
   });
 
   it('can update a folder without adapter', () => {
-    cy.task('writeFile', { path: 'images/test-dir/override/test.jpg', content: '1' })
+    cy.task('writeRelativeFile', { path: 'images/test-dir/override/test.jpg', content: '1' })
       .then(() => cy.api_patch('/media/files/test-dir/override', { path: 'test-dir/override-new' }))
       .then((response) => {
         cy.wrap(response).its('body').its('data').its('attributes')
@@ -130,7 +131,7 @@ describe('Test that media files API endpoint', () => {
   });
 
   it('can update a file with adapter', () => {
-    cy.task('writeFile', { path: 'images/test-dir/override.jpg', content: '1' })
+    cy.task('writeRelativeFile', { path: 'images/test-dir/override.jpg', content: '1' })
       .then(() => cy.readFile('tests/System/data/com_media/test-image-1.jpg', 'binary'))
       .then((data) => cy.api_patch(
         '/media/files/local-images:/test-dir/override.jpg',
@@ -146,7 +147,7 @@ describe('Test that media files API endpoint', () => {
   });
 
   it('can update a folder with adapter', () => {
-    cy.task('writeFile', { path: 'images/test-dir/override/test.jpg', content: '1' })
+    cy.task('writeRelativeFile', { path: 'images/test-dir/override/test.jpg', content: '1' })
       .then(() => cy.api_patch('/media/files/local-images:/test-dir/override', { path: 'local-images:/test-dir/override-new' }))
       .then((response) => {
         cy.wrap(response).its('body').its('data').its('attributes')
@@ -159,22 +160,22 @@ describe('Test that media files API endpoint', () => {
   });
 
   it('can delete a file without adapter', () => {
-    cy.task('writeFile', { path: 'images/test-dir/todelete.jpg', content: '1' })
+    cy.task('writeRelativeFile', { path: 'images/test-dir/todelete.jpg', content: '1' })
       .then(() => cy.api_delete('/media/files/test-dir/todelete.jpg'));
   });
 
   it('can delete a folder without adapter', () => {
-    cy.task('writeFile', { path: 'images/test-dir/todelete/dummy.txt', content: '1' })
+    cy.task('writeRelativeFile', { path: 'images/test-dir/todelete/dummy.txt', content: '1' })
       .then(() => cy.api_delete('/media/files/test-dir/todelete'));
   });
 
   it('can delete a file with adapter', () => {
-    cy.task('writeFile', { path: 'images/test-dir/todelete.jpg', content: '1' })
+    cy.task('writeRelativeFile', { path: 'images/test-dir/todelete.jpg', content: '1' })
       .then(() => cy.api_delete('/media/files/local-images:/test-dir/todelete.jpg'));
   });
 
   it('can delete a folder with adapter', () => {
-    cy.task('writeFile', { path: 'images/test-dir/todelete/dummy.txt', content: '1' })
+    cy.task('writeRelativeFile', { path: 'images/test-dir/todelete/dummy.txt', content: '1' })
       .then(() => cy.api_delete('/media/files/local-images:/test-dir/todelete'));
   });
 });

tests/System/integration/install/Installation.cy.js

@@ -15,7 +15,7 @@ describe('Install Joomla', () => {
     };
 
     // If exists, delete PHP configuration file to force a new installation
-    cy.task('deleteFolder', 'configuration.php');
+    cy.task('deleteRelativePath', 'configuration.php');
     cy.installJoomla(config);
 
     cy.doAdministratorLogin(config.username, config.password, false);

tests/System/plugins/fs.js

@@ -1,17 +1,20 @@
 const fs = require('fs');
-const fspath = require('path');
+const path = require('path');
 const { umask } = require('node:process');
 
 /**
- * Deletes a folder with the given path recursive.
+ * Synchronously deletes a file or folder, relative to cmsPath.
+ * If it is a folder and contains content, the content is deleted recursively.
+ * It ignores if the path doesn't exist.
  *
- * @param {string} path The path
- * @param {object} config The config
+ * @param {string} relativePath - File or folder, relative to cmsPath
+ * @param {object} config - The Cypress configuration object
  *
  * @returns null
  */
-function deleteFolder(path, config) {
-  fs.rmSync(`${config.env.cmsPath}/${path}`, { recursive: true, force: true });
+function deleteRelativePath(relativePath, config) {
+  const fullPath = path.join(config.env.cmsPath, relativePath);
+  fs.rmSync(fullPath, { recursive: true, force: true });
 
   return null;
 }
@@ -23,19 +26,19 @@ function deleteFolder(path, config) {
  * If the file already exists, it will be overwritten.
  * Finally, the given file mode or the default 0o444 is set for the given file.
  *
- * @param {string} path The relative file path (e.g. 'images/test-dir/override.jpg')
- * @param {mixed} content The file content
- * @param {object} config The Cypress configuration
- * @param {number} [mode=0o444] The file mode to be used (in octal)
+ * @param {string} relativePath - The relative file path (e.g. 'images/test-dir/override.jpg')
+ * @param {mixed} content - The file content
+ * @param {object} config - The Cypress configuration object
+ * @param {number} [mode=0o444] - The file mode to be used (in octal)
  *
  * @returns null
  */
-function writeFile(path, content, config, mode = 0o444) {
-  const fullPath = fspath.join(config.env.cmsPath, path);
+function writeRelativeFile(relativePath, content, config, mode = 0o444) {
+  const fullPath = path.join(config.env.cmsPath, relativePath);
   // Prologue: Reset process file mode creation mask to ensure the umask value is not subtracted
   const oldmask = umask(0);
   // Create missing parent directories with 'rwxrwxrwx'
-  fs.mkdirSync(fspath.dirname(fullPath), { recursive: true, mode: 0o777 });
+  fs.mkdirSync(path.dirname(fullPath), { recursive: true, mode: 0o777 });
   // Check if the file exists
   if (fs.existsSync(fullPath)) {
     // Set 'rw-rw-rw-' to be able to overwrite the file
@@ -51,4 +54,4 @@ function writeFile(path, content, config, mode = 0o444) {
   return null;
 }
 
-module.exports = { writeFile, deleteFolder };
+module.exports = { writeRelativeFile, deleteRelativePath };

tests/System/plugins/index.js

@@ -14,8 +14,8 @@ function setupPlugins(on, config) {
   on('task', {
     queryDB: (query) => db.queryTestDB(query, config),
     cleanupDB: () => db.deleteInsertedItems(config),
-    writeFile: ({ path, content, mode }) => fs.writeFile(path, content, config, mode),
-    deleteFolder: (path) => fs.deleteFolder(path, config),
+    writeRelativeFile: ({ path, content, mode }) => fs.writeRelativeFile(path, content, config, mode),
+    deleteRelativePath: (path) => fs.deleteRelativePath(path, config),
     getMails: () => mail.getMails(),
     clearEmails: () => mail.clearEmails(),
     startMailServer: () => mail.startMailServer(config),

tests/System/support/commands/config.js

@@ -12,6 +12,6 @@ Cypress.Commands.add('config_setParameter', (parameter, value) => {
     const content = fileContent.replace(regex, `public $${parameter} = ${newValue};`);
 
     // Write the modified content back to the configuration file relative to the CMS root folder
-    cy.task('writeFile', { path: 'configuration.php', content });
+    cy.task('writeRelativeFile', { path: 'configuration.php', content });
   });
 });