test(json-api-server-e2e): improve test descriptions and add comprehensive documentation for JSON-RPC, ACL, and JSON API functionalities

Author: klerick

apps/json-api-server-e2e/src/json-api/json-acl/1-get-all-acl-check.spec.ts

@@ -1,3 +1,25 @@
+/**
+ * ACL: GET All Resources - Permission and Field-Level Security
+ *
+ * This test suite verifies ACL (Access Control List) enforcement for fetching collections
+ * of resources. It tests three permission levels with different capabilities:
+ *
+ * 1. Admin Role: Full access without conditions
+ *    - Can read all resources and all fields
+ *    - Can include all relationships
+ *
+ * 2. Moderator Role: Full access with field restrictions
+ *    - Can read all resources
+ *    - Cannot read sensitive fields (salary, role in nested relations)
+ *    - Field filtering applied automatically by ACL
+ *
+ * 3. User Role: Conditional access with field restrictions
+ *    - Can read only public profiles OR their own profile
+ *    - Cannot read sensitive fields (salary, role, isPublic, createdAt, updatedAt)
+ *    - Can read own phone number but not others' phone numbers
+ *    - Row-level filtering applied automatically by ACL
+ */
+
 import {
   ContextTestAcl,
   UserRole,
@@ -9,8 +31,7 @@ import { JsonSdkPromise } from '@klerick/json-api-nestjs-sdk';
 import { creatSdk } from '../utils/run-application';
 import { AbilityBuilder, CheckFieldAndInclude } from '../utils/acl/acl';
 
-
-describe('ACL getAll:', () => {
+describe('ACL: GET All Resources (Collection Fetching)', () => {
   let contextTestAcl = new ContextTestAcl();
   let usersAcl: UsersAcl[];
   contextTestAcl.aclRules = { rules: [] };
@@ -28,7 +49,7 @@ describe('ACL getAll:', () => {
     await jsonSdk.jonApiSdkService.deleteOne(contextTestAcl);
   });
 
-  describe('Without conditional: admin', () => {
+  describe('Admin Role: Full Access Without Restrictions', () => {
     beforeEach(async () => {
       const adminUser = usersAcl.find((user) => user.login === 'admin');
       if (!adminUser) throw new Error('Daphne user not found');
@@ -38,18 +59,18 @@ describe('ACL getAll:', () => {
       await jsonSdk.jonApiSdkService.patchOne(contextTestAcl);
     });
 
-    it('get all profile', async () => {
+    it('should fetch all profiles with all fields (no ACL restrictions)', async () => {
       await jsonSdk.jonApiSdkService.getAll(UserProfileAcl)
     })
 
-    it('get all users with profile', async () => {
+    it('should fetch all users with included profiles with all fields', async () => {
       await jsonSdk.jonApiSdkService.getAll(UsersAcl, {
         include: ['profile'],
       });
     });
   })
 
-  describe('Without conditional but with fields: moderator', () => {
+  describe('Moderator Role: Full Access with Field-Level Restrictions', () => {
     beforeEach(async () => {
       const moderatorUser = usersAcl.find((user) => user.login === 'moderator');
       if (!moderatorUser) throw new Error('Sheila user not found');
@@ -59,7 +80,7 @@ describe('ACL getAll:', () => {
       await jsonSdk.jonApiSdkService.patchOne(contextTestAcl);
     });
 
-    it('get all profile', async () => {
+    it('should fetch all profiles but exclude sensitive fields (role, salary)', async () => {
       const result = await jsonSdk.jonApiSdkService.getAll(UserProfileAcl)
 
       for (const item of result) {
@@ -75,7 +96,7 @@ describe('ACL getAll:', () => {
       }
     })
 
-    it('get all users with profile', async () => {
+    it('should fetch all users with profiles but exclude salary from nested profile', async () => {
       const result = await jsonSdk.jonApiSdkService.getAll(UsersAcl, {
         include: ['profile'],
       });
@@ -87,7 +108,7 @@ describe('ACL getAll:', () => {
     });
   })
 
-  describe('With conditional: user', () => {
+  describe('User Role: Conditional Row-Level Access with Field Restrictions', () => {
     let countPublicProfile: UserProfileAcl[];
     beforeEach(async () => {
       countPublicProfile = await jsonSdk.jonApiSdkService.getAll(UserProfileAcl, {
@@ -106,7 +127,7 @@ describe('ACL getAll:', () => {
       await jsonSdk.jonApiSdkService.patchOne(contextTestAcl);
     });
 
-    it('should be able to get allow profile', async () => {
+    it('should fetch only public profiles and own profile, with field restrictions and conditional phone visibility', async () => {
 
       const result = await jsonSdk.jonApiSdkService.getAll(UserProfileAcl);
       expect(result.length).toBe(countPublicProfile.length + 1)

apps/json-api-server-e2e/src/json-api/json-acl/10-atomic-operation.spec.ts

@@ -1,3 +1,23 @@
+/**
+ * ACL: Atomic Operations - ACL Enforcement Across Batch Requests
+ *
+ * This test suite verifies ACL enforcement for atomic operations (batch requests)
+ * where multiple operations are executed together. ACL rules are evaluated for
+ * EACH individual operation within the atomic request.
+ *
+ * 1. Admin Role: Full atomic operation access
+ *    - Can execute multiple operations in one atomic request
+ *    - Can POST, PATCH, and DELETE in a single transaction
+ *    - All operations succeed when permissions allow
+ *
+ * 2. Moderator Role: Partial atomic operation access
+ *    - Can POST and PATCH in atomic request
+ *    - CANNOT DELETE (returns 403 Forbidden for entire atomic request)
+ *    - Atomic request fails if ANY operation violates ACL
+ *    - Error message indicates which operation failed (e.g., "deleteOne on ArticleAcl")
+ *    - Atomicity ensures either ALL operations succeed or ALL fail
+ */
+
 import { faker } from '@faker-js/faker';
 import {
   ArticleAcl,
@@ -12,9 +32,6 @@ import { JsonSdkPromise } from '@klerick/json-api-nestjs-sdk';
 import { creatSdk } from '../utils/run-application';
 import { AbilityBuilder, CheckFieldAndInclude } from '../utils/acl/acl';
 
-
-
-
 const getArticleData = () => ({
   title: faker.lorem.sentence(),
   content: faker.lorem.paragraphs(8),
@@ -30,7 +47,7 @@ const getArticleData = () => ({
   expiresAt: null,
 });
 
-describe('ACL atomic operation:', () => {
+describe('ACL: Atomic Operations (Batch Request ACL Enforcement)', () => {
   let contextTestAcl = new ContextTestAcl();
   let usersAcl: UsersAcl[];
   let articleAcl: ArticleAcl[];
@@ -51,7 +68,7 @@ describe('ACL atomic operation:', () => {
     await jsonSdk.jonApiSdkService.deleteOne(contextTestAcl);
   });
 
-  describe('Without conditional: admin', () => {
+  describe('Admin Role: Full Atomic Operation Access', () => {
     let bobUser: UsersAcl;
     beforeEach(async () => {
       const adminUser = usersAcl.find((user) => user.login === 'admin');
@@ -69,7 +86,7 @@ describe('ACL atomic operation:', () => {
       await jsonSdk.jonApiSdkService.patchOne(contextTestAcl);
     });
 
-    it('create one publish article with moderator author', async () => {
+    it('should execute atomic operation with POST, PATCH, and DELETE all succeeding', async () => {
       const articleForCreate = Object.assign(
         new ArticleAcl(),
         getArticleData(),
@@ -82,7 +99,7 @@ describe('ACL atomic operation:', () => {
     });
   });
 
-  describe('With conditional but with fields: moderator', () => {
+  describe('Moderator Role: Partial Atomic Operation Access with DELETE Restriction', () => {
 
     let bobUser: UsersAcl;
     let moderatorUser: UsersAcl;
@@ -104,7 +121,7 @@ describe('ACL atomic operation:', () => {
       await jsonSdk.jonApiSdkService.patchOne(contextTestAcl);
     });
 
-    it('allow create and patch but delete not allow', async () => {
+    it('should return 403 Forbidden for entire atomic request when DELETE operation violates ACL (POST and PATCH allowed but DELETE forbidden)', async () => {
       const articleForCreate = Object.assign(
         new ArticleAcl(),
         getArticleData()

apps/json-api-server-e2e/src/json-api/json-acl/2-get-one-acl-check.spec.ts

@@ -1,3 +1,26 @@
+/**
+ * ACL: GET One Resource - Permission and Field-Level Security
+ *
+ * This test suite verifies ACL enforcement for fetching individual resources by ID.
+ * It tests three permission levels with different capabilities:
+ *
+ * 1. Admin Role: Full access without conditions
+ *    - Can read any resource by ID with all fields
+ *    - Can include all relationships
+ *
+ * 2. Moderator Role: Full access with field restrictions
+ *    - Can read any resource by ID
+ *    - Cannot read sensitive fields (salary, role in nested relations)
+ *    - Field filtering applied automatically by ACL
+ *
+ * 3. User Role: Conditional row-level access with field restrictions
+ *    - Can read own profile with phone number visible
+ *    - Can read public profiles with phone number hidden
+ *    - CANNOT read private profiles (returns 404 Not Found)
+ *    - Cannot read sensitive fields (salary, role, isPublic, createdAt, updatedAt)
+ *    - Row-level filtering prevents access to forbidden resources
+ */
+
 import {
   ContextTestAcl,
   UserProfileAcl,
@@ -10,7 +33,7 @@ import { AxiosError } from 'axios';
 import { creatSdk } from '../utils/run-application';
 import { AbilityBuilder, CheckFieldAndInclude } from '../utils/acl/acl';
 
-describe('ACL getOne:', () => {
+describe('ACL: GET One Resource (Single Resource Fetching)', () => {
   let contextTestAcl = new ContextTestAcl();
   let usersAcl: UsersAcl[];
   contextTestAcl.aclRules = { rules: [] };
@@ -34,7 +57,7 @@ describe('ACL getOne:', () => {
     await jsonSdk.jonApiSdkService.deleteOne(contextTestAcl);
   });
 
-  describe('Without conditional: admin', () => {
+  describe('Admin Role: Full Access Without Restrictions', () => {
     beforeEach(async () => {
       const adminUser = usersAcl.find((user) => user.login === 'admin');
       if (!adminUser) throw new Error('Daphne user not found');
@@ -46,18 +69,18 @@ describe('ACL getOne:', () => {
       await jsonSdk.jonApiSdkService.patchOne(contextTestAcl);
     });
 
-    it('get one profile', async () => {
+    it('should fetch any user by ID with all fields (no ACL restrictions)', async () => {
       await jsonSdk.jonApiSdkService.getOne(UsersAcl, usersAcl[0].id);
     });
 
-    it('get one users with profile', async () => {
+    it('should fetch any user by ID with included profile with all fields', async () => {
       await jsonSdk.jonApiSdkService.getOne(UsersAcl, usersAcl[0].id, {
         include: ['profile'],
       });
     });
   });
 
-  describe('Without conditional but with fields: moderator', () => {
+  describe('Moderator Role: Full Access with Field-Level Restrictions', () => {
     beforeEach(async () => {
       const moderatorUser = usersAcl.find((user) => user.login === 'moderator');
       if (!moderatorUser) throw new Error('Sheila user not found');
@@ -69,7 +92,7 @@ describe('ACL getOne:', () => {
       await jsonSdk.jonApiSdkService.patchOne(contextTestAcl);
     });
 
-    it('get one profile', async () => {
+    it('should fetch any profile by ID but exclude sensitive fields (role, salary)', async () => {
       const item = await jsonSdk.jonApiSdkService.getOne(
         UserProfileAcl,
         usersAcl[0].id
@@ -85,7 +108,7 @@ describe('ACL getOne:', () => {
       expect(item.updatedAt).toBeDefined();
     });
 
-    it('get one users with profile', async () => {
+    it('should fetch any user by ID with profile but exclude salary from nested profile', async () => {
       const item = await jsonSdk.jonApiSdkService.getOne(
         UsersAcl,
         usersAcl[0].id,
@@ -99,7 +122,7 @@ describe('ACL getOne:', () => {
     });
   });
 
-  describe('With conditional: user', () => {
+  describe('User Role: Conditional Row-Level Access with Field Restrictions', () => {
     let bobUser: UsersAcl;
     beforeEach(async () => {
       const posibleBobUser = usersAcl.find((user) => user.login === 'bob');
@@ -112,7 +135,7 @@ describe('ACL getOne:', () => {
       await jsonSdk.jonApiSdkService.patchOne(contextTestAcl);
     });
 
-    it('should be able to get owner profile', async () => {
+    it('should fetch own profile with phone visible and sensitive fields excluded', async () => {
       const item = await jsonSdk.jonApiSdkService.getOne(
         UserProfileAcl,
         bobUser.profile.id
@@ -129,7 +152,7 @@ describe('ACL getOne:', () => {
       expect(item.bio).toBeDefined();
     });
 
-    it('should be able to get public profile', async () => {
+    it('should fetch public profile with phone hidden and sensitive fields excluded', async () => {
       const item = await jsonSdk.jonApiSdkService.getOne(
         UserProfileAcl,
         publicUser.profile.id
@@ -145,7 +168,7 @@ describe('ACL getOne:', () => {
       expect(item.avatar).toBeDefined();
       expect(item.bio).toBeDefined();
     });
-    it('should be not found to get not public profile', async () => {
+    it('should return 404 Not Found when attempting to fetch private profile of another user', async () => {
       try {
         await jsonSdk.jonApiSdkService.getOne(
           UserProfileAcl,