test: enhance test files with structured comments and file overviews (#…

…143)

This pull request adds file overview comments and organizes test files
for better readability across multiple packages. The changes primarily
include adding documentation comments and structuring sections within
the test files.

Documentation and structure improvements:

* Added file overview comments to test files in
`packages/clang-format-git-python/src` (`cli.test.js`, `index.test.js`,
`utils/gitClangFormatPath.test.js`).
[[1]](diffhunk://#diff-79e78a84119f7ca227770bfba1f5ad50ad52d43dab3b1ef9141de9bd7f55c3bfR1-R23)
[[2]](diffhunk://#diff-382f84767003602b6b2c41dcb6a862910495d91f30331d76139fbb8e9d0649c2R1-R17)
[[3]](diffhunk://#diff-41c3fa28ed17f0f9ce4b26fa451766e45f1ff88989d94a76cef0cdd408c6f72fR1-R18)
* Added file overview comments to test files in
`packages/clang-format-git/src` (`cli.test.js`, `index.test.js`,
`utils/getGitClangFormatPath.test.js`,
`utils/gitClangFormatPath.test.js`).
[[1]](diffhunk://#diff-79e78a84119f7ca227770bfba1f5ad50ad52d43dab3b1ef9141de9bd7f55c3bfR1-R23)
[[2]](diffhunk://#diff-68d369a6981c94dcba1fd976b7f7b3a4efc23045960fd29d230d25197a00a34dR1-R8)
[[3]](diffhunk://#diff-6865c3e7fd57fdb3bbd13544aa54199525d2490b0680146f6539b455e2eb28efR1-R8)
[[4]](diffhunk://#diff-587e60e089a55d517cb462d20ae4b5da664e59b71babc6cae989874237d6e48dR1-R19)
* Added file overview comments to test files in
`packages/clang-format-node/src` (`cli.test.js`, `index.test.js`,
`utils/clangFormatPath.test.js`, `utils/getClangFormatPath.test.js`).
[[1]](diffhunk://#diff-5dd8ea44391ea129a9c03d252e50d95c86343b7fe1b5208ad13b24ff31d82ab1R1-R23)
[[2]](diffhunk://#diff-3fca32871ee80cc88b9bf2428b777131769ee5890b3a64aab775cb2368f3236fR1-R8)
[[3]](diffhunk://#diff-4927c43bcf98afdf412ea51fe173b4920339c6f1e486599db35f028961d462b0R1-R19)
[[4]](diffhunk://#diff-780a2dec956bf21dd4f2639b029856703fc6849a8d38f5eedacb723b968face5R1-R17)

Structural organization:

* Added sections for "Require", "Declaration", and "Test" within test
files to improve readability and organization.
[[1]](diffhunk://#diff-79e78a84119f7ca227770bfba1f5ad50ad52d43dab3b1ef9141de9bd7f55c3bfR1-R23)
[[2]](diffhunk://#diff-382f84767003602b6b2c41dcb6a862910495d91f30331d76139fbb8e9d0649c2R1-R17)
[[3]](diffhunk://#diff-41c3fa28ed17f0f9ce4b26fa451766e45f1ff88989d94a76cef0cdd408c6f72fR1-R18)
[[4]](diffhunk://#diff-68d369a6981c94dcba1fd976b7f7b3a4efc23045960fd29d230d25197a00a34dR19-R22)
[[5]](diffhunk://#diff-6865c3e7fd57fdb3bbd13544aa54199525d2490b0680146f6539b455e2eb28efR17-R20)
[[6]](diffhunk://#diff-6865c3e7fd57fdb3bbd13544aa54199525d2490b0680146f6539b455e2eb28efR55-R58)
[[7]](diffhunk://#diff-587e60e089a55d517cb462d20ae4b5da664e59b71babc6cae989874237d6e48dR1-R19)
[[8]](diffhunk://#diff-3fca32871ee80cc88b9bf2428b777131769ee5890b3a64aab775cb2368f3236fR19-R22)
[[9]](diffhunk://#diff-4927c43bcf98afdf412ea51fe173b4920339c6f1e486599db35f028961d462b0R1-R19)
[[10]](diffhunk://#diff-780a2dec956bf21dd4f2639b029856703fc6849a8d38f5eedacb723b968face5R52-R55)

packages/clang-format-git-python/src/cli.test.js

@@ -1,10 +1,26 @@
+/**
+ * @fileoverview Test for `cli.js`.
+ */
+
+// --------------------------------------------------------------------------------
+// Require
+// --------------------------------------------------------------------------------
+
 const { doesNotThrow, throws } = require('node:assert');
 const { execSync } = require('node:child_process');
 const { resolve } = require('node:path');
 const { describe, it } = require('node:test');
 
+// --------------------------------------------------------------------------------
+// Declaration
+// --------------------------------------------------------------------------------
+
 const cli = resolve(__dirname, 'cli.js');
 
+// --------------------------------------------------------------------------------
+// Test
+// --------------------------------------------------------------------------------
+
 describe('cli doesNotThrow and throws testing', () => {
   // Correct
   it('node cli.js', () => {

packages/clang-format-git-python/src/index.test.js

@@ -1,8 +1,20 @@
+/**
+ * @fileoverview Test for `index.js`.
+ */
+
+// --------------------------------------------------------------------------------
+// Require
+// --------------------------------------------------------------------------------
+
 const { ok } = require('node:assert');
 const { describe, it } = require('node:test');
 
 const { gitClangFormatPath, clangFormatGitPythonPath } = require('./index');
 
+// --------------------------------------------------------------------------------
+// Test
+// --------------------------------------------------------------------------------
+
 describe('index ok testing', () => {
   it('gitClangFormatPath should be imported correctly', () => {
     ok(gitClangFormatPath);

packages/clang-format-git-python/src/utils/gitClangFormatPath.test.js

@@ -1,9 +1,21 @@
+/**
+ * @fileoverview Test for `gitClangFormatPath.js`.
+ */
+
+// --------------------------------------------------------------------------------
+// Require
+// --------------------------------------------------------------------------------
+
 const { strictEqual } = require('node:assert');
 const { resolve } = require('node:path');
 const { describe, it } = require('node:test');
 
 const { gitClangFormatPath, clangFormatGitPythonPath } = require('./gitClangFormatPath');
 
+// --------------------------------------------------------------------------------
+// Test
+// --------------------------------------------------------------------------------
+
 describe('gitClangFormatPath strictEqual testing', () => {
   it('gitClangFormatPath === clangFormatGitPythonPath', () => {
     strictEqual(gitClangFormatPath, clangFormatGitPythonPath);

packages/clang-format-git/src/cli.test.js

@@ -1,10 +1,26 @@
+/**
+ * @fileoverview Test for `cli.js`.
+ */
+
+// --------------------------------------------------------------------------------
+// Require
+// --------------------------------------------------------------------------------
+
 const { doesNotThrow, throws } = require('node:assert');
 const { execSync } = require('node:child_process');
 const { resolve } = require('node:path');
 const { describe, it } = require('node:test');
 
+// --------------------------------------------------------------------------------
+// Declaration
+// --------------------------------------------------------------------------------
+
 const cli = resolve(__dirname, 'cli.js');
 
+// --------------------------------------------------------------------------------
+// Test
+// --------------------------------------------------------------------------------
+
 describe('cli doesNotThrow and throws testing', () => {
   // Correct
   it('node cli.js', () => {

packages/clang-format-git/src/index.test.js

@@ -1,3 +1,11 @@
+/**
+ * @fileoverview Test for `index.js`.
+ */
+
+// --------------------------------------------------------------------------------
+// Require
+// --------------------------------------------------------------------------------
+
 const { ok } = require('node:assert');
 const { describe, it } = require('node:test');
 
@@ -8,6 +16,10 @@ const {
   clangFormatGitPath,
 } = require('./index');
 
+// --------------------------------------------------------------------------------
+// Test
+// --------------------------------------------------------------------------------
+
 describe('index ok testing', () => {
   it('getGitClangFormatPath should be imported correctly', () => {
     ok(getGitClangFormatPath);

packages/clang-format-git/src/utils/getGitClangFormatPath.test.js

@@ -1,3 +1,11 @@
+/**
+ * @fileoverview Test for `getGitClangFormatPath.js`.
+ */
+
+// --------------------------------------------------------------------------------
+// Require
+// --------------------------------------------------------------------------------
+
 const { doesNotThrow, throws } = require('node:assert');
 const { describe, it } = require('node:test');
 
@@ -6,6 +14,10 @@ const {
   getClangFormatGitPath,
 } = require('./getGitClangFormatPath');
 
+// --------------------------------------------------------------------------------
+// Declaration
+// --------------------------------------------------------------------------------
+
 /**
  * See possible values in {@link https://nodejs.org/api/os.html#osplatform}.
  */
@@ -40,6 +52,10 @@ const allowed = {
   win32: ['x64'],
 };
 
+// --------------------------------------------------------------------------------
+// Test
+// --------------------------------------------------------------------------------
+
 describe('getGitClangFormatPath doesNotThrow and throws testing', () => {
   osPlatforms.forEach(osPlatform => {
     architectures.forEach(architecture => {

packages/clang-format-git/src/utils/gitClangFormatPath.test.js

@@ -1,10 +1,22 @@
+/**
+ * @fileoverview Test for `gitClangFormatPath.js`.
+ */
+
+// --------------------------------------------------------------------------------
+// Require
+// --------------------------------------------------------------------------------
+
 const { strictEqual } = require('node:assert');
 const { platform, arch } = require('node:os');
 const { describe, it } = require('node:test');
 
 const { gitClangFormatPath, clangFormatGitPath } = require('./gitClangFormatPath');
 const { getGitClangFormatPath } = require('./getGitClangFormatPath');
 
+// --------------------------------------------------------------------------------
+// Test
+// --------------------------------------------------------------------------------
+
 describe('gitClangFormatPath strictEqual testing', () => {
   it('gitClangFormatPath === getGitClangFormatPath(platform(), arch())', () => {
     strictEqual(gitClangFormatPath, getGitClangFormatPath(platform(), arch()));

packages/clang-format-node/src/cli.test.js

@@ -1,10 +1,26 @@
+/**
+ * @fileoverview Test for `cli.js`.
+ */
+
+// --------------------------------------------------------------------------------
+// Require
+// --------------------------------------------------------------------------------
+
 const { doesNotThrow, throws } = require('node:assert');
 const { execSync } = require('node:child_process');
 const { resolve } = require('node:path');
 const { describe, it } = require('node:test');
 
+// --------------------------------------------------------------------------------
+// Declaration
+// --------------------------------------------------------------------------------
+
 const cli = resolve(__dirname, 'cli.js');
 
+// --------------------------------------------------------------------------------
+// Test
+// --------------------------------------------------------------------------------
+
 describe('cli doesNotThrow and throws testing', () => {
   // Correct
   it('node cli.js --help', () => {

packages/clang-format-node/src/index.test.js

@@ -1,3 +1,11 @@
+/**
+ * @fileoverview Test for `index.js`.
+ */
+
+// --------------------------------------------------------------------------------
+// Require
+// --------------------------------------------------------------------------------
+
 const { ok } = require('node:assert');
 const { describe, it } = require('node:test');
 
@@ -8,6 +16,10 @@ const {
   getClangFormatNodePath,
 } = require('./index');
 
+// --------------------------------------------------------------------------------
+// Test
+// --------------------------------------------------------------------------------
+
 describe('index ok testing', () => {
   it('clangFormatPath should be imported correctly', () => {
     ok(clangFormatPath);

packages/clang-format-node/src/utils/clangFormatPath.test.js

@@ -1,10 +1,22 @@
+/**
+ * @fileoverview Test for `clangFormatPath.js`.
+ */
+
+// --------------------------------------------------------------------------------
+// Require
+// --------------------------------------------------------------------------------
+
 const { strictEqual } = require('node:assert');
 const { platform, arch } = require('node:os');
 const { describe, it } = require('node:test');
 
 const { clangFormatPath, clangFormatNodePath } = require('./clangFormatPath');
 const { getClangFormatPath } = require('./getClangFormatPath');
 
+// --------------------------------------------------------------------------------
+// Test
+// --------------------------------------------------------------------------------
+
 describe('clangFormatPath strictEqual testing', () => {
   it('clangFormatPath === getClangFormatPath(platform(), arch())', () => {
     strictEqual(clangFormatPath, getClangFormatPath(platform(), arch()));

packages/clang-format-node/src/utils/getClangFormatPath.test.js

@@ -1,8 +1,20 @@
+/**
+ * @fileoverview Test for `getClangFormatPath.js`.
+ */
+
+// --------------------------------------------------------------------------------
+// Require
+// --------------------------------------------------------------------------------
+
 const { doesNotThrow, throws } = require('node:assert');
 const { describe, it } = require('node:test');
 
 const { getClangFormatPath, getClangFormatNodePath } = require('./getClangFormatPath');
 
+// --------------------------------------------------------------------------------
+// Declaration
+// --------------------------------------------------------------------------------
+
 /**
  * See possible values in {@link https://nodejs.org/api/os.html#osplatform}.
  */
@@ -37,6 +49,10 @@ const allowed = {
   win32: ['x64'],
 };
 
+// --------------------------------------------------------------------------------
+// Test
+// --------------------------------------------------------------------------------
+
 describe('getClangFormatPath doesNotThrow and throws testing', () => {
   osPlatforms.forEach(osPlatform => {
     architectures.forEach(architecture => {