Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Spring 2026 - E2615. Testing User model and Users controller

2026-04-28T23:09:14Z

Awainga:

== E2615: Full Implementation Wiki for User Model and UsersController Testing ==

{| class="wikitable" style="width:100%;"
|-
! colspan="2" style="background:#cee0f2; text-align:center;" | Project Information
|-
| Course || CSC/ECE 517 Spring 2026
|-
| Project || E2615 - Testing User Model and UsersController
|-
| Instructor || Ed Gehringer
|-
| Mentor || Aanand Sreekumaran Nair Jayakumari
|-
| Team Members || Atharva Waingankar, Krisha Darji, Saladin Al-Bataineh
|-
| Platform || Expertiza reimplementation back-end (Ruby on Rails)
|-
| Primary Testing Framework || RSpec
|-
| Target Components || User model and UsersController
|-
| Final Deliverables || Comprehensive model specs, comprehensive request specs, and targeted defect fixes
|}

== Why This Project Matters ==

The User domain is the backbone of Expertiza. It controls account identity, role-driven behavior, hierarchical relationships between users, and authentication-related workflows. If this layer breaks, many workflows break.

This project addressed a critical testing gap by replacing placeholder coverage with real, scenario-driven tests that validate both normal behavior and failure behavior for:
* Model rules and role logic
* API contracts and error handling
* Authentication-sensitive endpoints
* Regression-prone edge cases

== Objectives ==

* Build broad and meaningful tests for User model behavior.
* Build comprehensive request tests for all UsersController actions.
* Validate both happy paths and failure paths with explicit status and payload checks.
* Fix defects discovered during implementation and lock them with regression tests.
* Keep changes minimal, focused, and consistent with repository conventions.

== Final Scope Delivered ==

=== In Scope (Completed) ===
* spec/models/user_spec.rb
* spec/requests/api/v1/users_controller_spec.rb
* Targeted production changes tied to test evidence in:
* app/models/user.rb
* app/models/ta.rb
* app/controllers/users_controller.rb
* db/migrate/20260428000000_update_teams_participants_unique_index.rb
* db/schema.rb

=== Out of Scope ===
* Broad refactors unrelated to User and UsersController
* Frontend and UI work
* Unrelated controller rewrites

== User Role Structure ==

<pre>
┌───────────────────────┐
│ User │
│ (core account) │
└───────────┬───────────┘
│ belongs_to
▼
┌─────────────┐
│ Role │
└──────┬──────┘
│ hierarchy
┌────────────────────────┼────────────────────────┐
▼ ▼ ▼
Student Teaching Assistant Instructor
│
▼
Administrator
│
▼
Super Administrator
</pre>

== Test Design Strategy ==

=== Model Spec Plan (spec/models/user_spec.rb) ===

{| class="wikitable" style="width:100%;"
|-
! Area !! What Will Be Tested !! Expected Result
|-
| Validations || presence, format, and length checks for name, email, password, full_name || Invalid data is rejected with clear errors
|-
| Associations || role, institution, parent, child users, invitations, assignments, teams, participants || Associations are correctly defined and functional
|-
| Scopes || students, tas, instructors, administrators, superadministrators || Each scope returns users with matching role
|-
| Delegated role checks || student?, ta?, instructor?, administrator?, super_administrator? || Role query methods behave consistently
|-
| Defaults || initialization flags and email preference defaults || Defaults are set correctly on initialization
|-
| Authentication behavior || has_secure_password behavior, password digest creation, minimum length || Password workflows behave securely and predictably
|-
| Class methods || login_user, from_params, instantiate || Lookup and STI conversion logic works as intended
|-
| Instance methods || instructor_id, can_impersonate?, recursively_parent_of, teaching_assistant_for?, as_json, generate_jwt || Methods return correct values and enforce role rules
|-
| Regression checks || edge cases and known fragile areas discovered during implementation || Defects are detected and fixed
|}

=== Request Spec Plan (spec/requests/api/v1/users_controller_spec.rb) ===

{| class="wikitable" style="width:100%;"
|-
! Endpoint !! Scenarios !! Expected Result
|-
| GET /users || Authenticated request || 200 with user list payload
|-
| GET /users/:id || Existing and missing id || 200 for existing, 404 for missing
|-
| POST /users || Valid payload, invalid payload, missing user param || 201 for valid, 422 for invalid or missing params
|-
| PATCH/PUT /users/:id || Valid update, invalid update, missing id || 200 for valid, 422 or 404 for failures
|-
| DELETE /users/:id || Existing and missing id || No-content success path, 404 for missing
|-
| GET /users/institution/:id || Valid institution and missing institution || 200 with users, 404 when not found
|-
| GET /users/:id/managed || Student parent versus non-student parent || 422 for student parent, 200 for allowed roles
|-
| GET /users/role/:name || Valid role name and missing role || 200 for valid role, graceful failure behavior for invalid role
|}

== How the Plan Was Converted into Real Results ==

=== Phase 1: Build Baseline Scaffolding ===

Both target files were organized with repository-consistent patterns:
* Request specs include swagger helper and JWT helper.
* Role hierarchy is initialized with create_roles_hierarchy.
* Request specs use bearer token setup and structured response blocks.
* Model specs use factory-driven setup and behavior-oriented describe blocks.

=== Phase 2: Implement User Model Scenarios ===

The model suite was written category by category:
* Validation boundaries first
* Association definitions next
* Scope and role delegation behavior
* Password and default flag behavior
* Class method contracts
* Domain-level methods with role-aware and hierarchy-aware cases

This ensured early detection of behavior regressions in core user logic.

=== Phase 3: Implement UsersController Scenarios ===

The request suite was written route by route:
* Full CRUD route coverage
* Custom route coverage for institution, managed users, and role filtering
* Authorization failure checks with invalid token
* Missing parameter and missing record checks
* JSON contract checks for both success and failure responses

=== Phase 4: Apply Defect Fixes Found During Test Implementation ===

When scenario coverage exposed issues, targeted fixes were applied:
* Missing-role lookup now returns explicit 404 in role_users.
* teaching_assistant? now returns strict boolean values.
* TA model has parent_id presence validation and improved course query pattern.
* teams_participants unique index now aligns with scoped uniqueness intent.

=== Phase 5: Regression Lock-In ===

New or updated tests were added for discovered fragile paths so behavior remains stable after future changes.

== Code Snippets from Implemented Work ==

=== 1) Model Validation Scenario ===

Source: spec/models/user_spec.rb

<syntaxhighlight lang="ruby">
describe 'validations' do
it 'is invalid when name is not unique' do
create(:user, name: 'duplicate', role: role)
user = User.new(name: 'duplicate', email: 'other@example.com', full_name: 'Other User', role: role, password: 'password')
expect(user).not_to be_valid
expect(user.errors[:name]).to include('has already been taken')
end

it 'is invalid with a malformed email' do
user = User.new(name: 'testuser', email: 'not-an-email', full_name: 'Test User', role: role, password: 'password')
expect(user).not_to be_valid
expect(user.errors[:email]).to be_present
end
end
</syntaxhighlight>

What this proves:
* Invalid input is rejected with explicit errors.
* Validation expectations in the model plan are fully executed.

=== 2) Model Scope Scenario ===

Source: spec/models/user_spec.rb

<syntaxhighlight lang="ruby">
describe '.tas' do
it 'includes users with teaching assistant role and excludes others' do
ta = create(:user, role: ta_role)
student = create(:user, role: student_role)

expect(User.tas).to include(ta)
expect(User.tas).not_to include(student)
end
end
</syntaxhighlight>

What this proves:
* Role scopes are tested with inclusion and exclusion checks, not only one-sided checks.

=== 3) Model Instance Method Scenario ===

Source: spec/models/user_spec.rb

<syntaxhighlight lang="ruby">
describe '#instructor_id' do
it 'returns own id for instructor' do
instructor = create(:user, role: instructor_role, institution: institution)
expect(instructor.instructor_id).to eq(instructor.id)
end

it 'raises NotImplementedError for student role' do
student = create(:user, role: student_role, institution: institution)
expect { student.instructor_id }.to raise_error(NotImplementedError, /Unknown role/)
end
end
</syntaxhighlight>

What this proves:
* Role-dependent instance behavior is enforced.
* Error behavior for unsupported roles is explicit and tested.

=== 4) Request Authorization Scenario ===

Source: spec/requests/api/v1/users_controller_spec.rb

<syntaxhighlight lang="ruby">
response '401', 'Unauthorized when token is invalid' do
let(:Authorization) { 'Bearer invalid_token' }

run_test! do |response|
body = JSON.parse(response.body)
expect(body['error']).to eq('Not Authorized')
end
end
</syntaxhighlight>

What this proves:
* JWT-protected routes fail safely and consistently with invalid tokens.

=== 5) Request Missing Parameter Scenario ===

Source: spec/requests/api/v1/users_controller_spec.rb

<syntaxhighlight lang="ruby">
response '422', 'Rejects request when user param is missing' do
let(:payload) { {} }

run_test! do |response|
body = JSON.parse(response.body)
expect(body['error']).to eq('Parameter missing')
end
end
</syntaxhighlight>

What this proves:
* ParameterMissing handling is validated through API tests.

=== 6) Request Invalid Role Scenario ===

Source: spec/requests/api/v1/users_controller_spec.rb

<syntaxhighlight lang="ruby">
response '404', 'Returns not found for invalid role name' do
let(:name) { 'role_that_does_not_exist' }

run_test! do |response|
body = JSON.parse(response.body)
expect(body['error']).to eq("Role 'Role That Does Not Exist' not found")
end
end
</syntaxhighlight>

What this proves:
* The role filter endpoint now has a stable, graceful failure contract.

== Production Fix Snippets that Back the Tested Results ==

=== users_controller: role lookup guard ===

Source: app/controllers/users_controller.rb

<syntaxhighlight lang="ruby">
def role_users
name = params[:name].split('_').map(&:capitalize).join(' ')
role = Role.find_by(name:)
unless role
render json: { error: "Role '#{name}' not found" }, status: :not_found
return
end
users = role.users
render json: users, status: :ok
rescue ActiveRecord::RecordNotFound => e
render json: { error: e.message }, status: :not_found
end
</syntaxhighlight>

=== user: strict boolean predicate for role check ===

Source: app/models/user.rb

<syntaxhighlight lang="ruby">
def teaching_assistant?
!!role.ta?
end
</syntaxhighlight>

== Defects Found and Fixed ==

{| class="wikitable" style="width:100%;"
|-
! Area !! Defect Observed During Implementation !! Fix Applied !! Linked Test Outcome
|-
| Role-filter endpoint || Missing role lookup path was not safely handled || Added explicit 404 JSON guard in controller || Invalid role request now asserted as 404 with message
|-
| Role predicate return type || Predicate behavior needed strict true/false consistency || Enforced boolean coercion in User model || teaching_assistant? expectations are stable
|-
| TA support path || Model integrity and query pattern needed tightening || Added validation and improved query path || Supporting logic stabilized for tested user flows
|-
| teams_participants uniqueness || DB constraint mismatched scoped uniqueness expectation || Added composite unique index migration || Constraint behavior aligned with model intent
|}

== Test Commands ==

Primary command:
<syntaxhighlight lang="bash">
bundle exec rspec spec/models/user_spec.rb spec/requests/api/v1/users_controller_spec.rb
</syntaxhighlight>

== Demo Video Link ==

* Demo video: https://youtu.be/lwW9BuSOeUk

== Definition of Done Status ==

{| class="wikitable" style="width:100%;"
|-
! Completion Criteria !! Status
|-
| User model spec implemented with broad category coverage || Completed
|-
| UsersController request spec implemented for all target routes || Completed
|-
| Success and failure scenarios explicitly asserted || Completed
|-
| JWT-related authorization behavior covered || Completed
|-
| Defects discovered during testing fixed with targeted patches || Completed
|-
| Regression checks added for fragile paths || Completed
|-
| Reproducible verification command documented || Completed
|}

== Final Summary ==

E2615 is now a high-value quality layer for Expertiza user workflows. The project moved from negligible practical coverage to comprehensive, scenario-driven tests with concrete production hardening. The resulting test suites validate core contracts, enforce predictable API behavior, and provide a durable safety net for future development.

CSC/ECE 517 Spring 2026 - E2615. Testing User model and Users controller

2026-04-28T17:09:28Z

Awainga:

== E2615: Full Implementation Wiki for User Model and UsersController Testing ==

{| class="wikitable" style="width:100%;"
|-
! colspan="2" style="background:#cee0f2; text-align:center;" | Project Information
|-
| Course || CSC/ECE 517 Spring 2026
|-
| Project || E2615 - Testing User Model and UsersController
|-
| Instructor || Ed Gehringer
|-
| Mentor || Aanand Sreekumaran Nair Jayakumari
|-
| Team Members || Atharva Waingankar, Krisha Darji, Saladin Al-Bataineh
|-
| Platform || Expertiza reimplementation back-end (Ruby on Rails)
|-
| Primary Testing Framework || RSpec
|-
| Target Components || User model and UsersController
|-
| Final Deliverables || Comprehensive model specs, comprehensive request specs, and targeted defect fixes
|}

== Demo Video Link ==

* Demo video: INSERT_DEMO_VIDEO_LINK_HERE

== Why This Project Matters ==

The User domain is the backbone of Expertiza. It controls account identity, role-driven behavior, hierarchical relationships between users, and authentication-related workflows. If this layer breaks, many workflows break.

This project addressed a critical testing gap by replacing placeholder coverage with real, scenario-driven tests that validate both normal behavior and failure behavior for:
* Model rules and role logic
* API contracts and error handling
* Authentication-sensitive endpoints
* Regression-prone edge cases

== Objectives ==

* Build broad and meaningful tests for User model behavior.
* Build comprehensive request tests for all UsersController actions.
* Validate both happy paths and failure paths with explicit status and payload checks.
* Fix defects discovered during implementation and lock them with regression tests.
* Keep changes minimal, focused, and consistent with repository conventions.

== Final Scope Delivered ==

=== In Scope (Completed) ===
* spec/models/user_spec.rb
* spec/requests/api/v1/users_controller_spec.rb
* Targeted production changes tied to test evidence in:
* app/models/user.rb
* app/models/ta.rb
* app/controllers/users_controller.rb
* db/migrate/20260428000000_update_teams_participants_unique_index.rb
* db/schema.rb

=== Out of Scope ===
* Broad refactors unrelated to User and UsersController
* Frontend and UI work
* Unrelated controller rewrites

== User Role Structure ==

<pre>
┌───────────────────────┐
│ User │
│ (core account) │
└───────────┬───────────┘
│ belongs_to
▼
┌─────────────┐
│ Role │
└──────┬──────┘
│ hierarchy
┌────────────────────────┼────────────────────────┐
▼ ▼ ▼
Student Teaching Assistant Instructor
│
▼
Administrator
│
▼
Super Administrator
</pre>

== Test Design Strategy ==

=== Model Spec Plan (spec/models/user_spec.rb) ===

{| class="wikitable" style="width:100%;"
|-
! Area !! What Will Be Tested !! Expected Result
|-
| Validations || presence, format, and length checks for name, email, password, full_name || Invalid data is rejected with clear errors
|-
| Associations || role, institution, parent, child users, invitations, assignments, teams, participants || Associations are correctly defined and functional
|-
| Scopes || students, tas, instructors, administrators, superadministrators || Each scope returns users with matching role
|-
| Delegated role checks || student?, ta?, instructor?, administrator?, super_administrator? || Role query methods behave consistently
|-
| Defaults || initialization flags and email preference defaults || Defaults are set correctly on initialization
|-
| Authentication behavior || has_secure_password behavior, password digest creation, minimum length || Password workflows behave securely and predictably
|-
| Class methods || login_user, from_params, instantiate || Lookup and STI conversion logic works as intended
|-
| Instance methods || instructor_id, can_impersonate?, recursively_parent_of, teaching_assistant_for?, as_json, generate_jwt || Methods return correct values and enforce role rules
|-
| Regression checks || edge cases and known fragile areas discovered during implementation || Defects are detected and fixed
|}

=== Request Spec Plan (spec/requests/api/v1/users_controller_spec.rb) ===

{| class="wikitable" style="width:100%;"
|-
! Endpoint !! Scenarios !! Expected Result
|-
| GET /users || Authenticated request || 200 with user list payload
|-
| GET /users/:id || Existing and missing id || 200 for existing, 404 for missing
|-
| POST /users || Valid payload, invalid payload, missing user param || 201 for valid, 422 for invalid or missing params
|-
| PATCH/PUT /users/:id || Valid update, invalid update, missing id || 200 for valid, 422 or 404 for failures
|-
| DELETE /users/:id || Existing and missing id || No-content success path, 404 for missing
|-
| GET /users/institution/:id || Valid institution and missing institution || 200 with users, 404 when not found
|-
| GET /users/:id/managed || Student parent versus non-student parent || 422 for student parent, 200 for allowed roles
|-
| GET /users/role/:name || Valid role name and missing role || 200 for valid role, graceful failure behavior for invalid role
|}

== How the Plan Was Converted into Real Results ==

=== Phase 1: Build Baseline Scaffolding ===

Both target files were organized with repository-consistent patterns:
* Request specs include swagger helper and JWT helper.
* Role hierarchy is initialized with create_roles_hierarchy.
* Request specs use bearer token setup and structured response blocks.
* Model specs use factory-driven setup and behavior-oriented describe blocks.

=== Phase 2: Implement User Model Scenarios ===

The model suite was written category by category:
* Validation boundaries first
* Association definitions next
* Scope and role delegation behavior
* Password and default flag behavior
* Class method contracts
* Domain-level methods with role-aware and hierarchy-aware cases

This ensured early detection of behavior regressions in core user logic.

=== Phase 3: Implement UsersController Scenarios ===

The request suite was written route by route:
* Full CRUD route coverage
* Custom route coverage for institution, managed users, and role filtering
* Authorization failure checks with invalid token
* Missing parameter and missing record checks
* JSON contract checks for both success and failure responses

=== Phase 4: Apply Defect Fixes Found During Test Implementation ===

When scenario coverage exposed issues, targeted fixes were applied:
* Missing-role lookup now returns explicit 404 in role_users.
* teaching_assistant? now returns strict boolean values.
* TA model has parent_id presence validation and improved course query pattern.
* teams_participants unique index now aligns with scoped uniqueness intent.

=== Phase 5: Regression Lock-In ===

New or updated tests were added for discovered fragile paths so behavior remains stable after future changes.

== Code Snippets from Implemented Work ==

=== 1) Model Validation Scenario ===

Source: spec/models/user_spec.rb

<syntaxhighlight lang="ruby">
describe 'validations' do
it 'is invalid when name is not unique' do
create(:user, name: 'duplicate', role: role)
user = User.new(name: 'duplicate', email: 'other@example.com', full_name: 'Other User', role: role, password: 'password')
expect(user).not_to be_valid
expect(user.errors[:name]).to include('has already been taken')
end

it 'is invalid with a malformed email' do
user = User.new(name: 'testuser', email: 'not-an-email', full_name: 'Test User', role: role, password: 'password')
expect(user).not_to be_valid
expect(user.errors[:email]).to be_present
end
end
</syntaxhighlight>

What this proves:
* Invalid input is rejected with explicit errors.
* Validation expectations in the model plan are fully executed.

=== 2) Model Scope Scenario ===

Source: spec/models/user_spec.rb

<syntaxhighlight lang="ruby">
describe '.tas' do
it 'includes users with teaching assistant role and excludes others' do
ta = create(:user, role: ta_role)
student = create(:user, role: student_role)

expect(User.tas).to include(ta)
expect(User.tas).not_to include(student)
end
end
</syntaxhighlight>

What this proves:
* Role scopes are tested with inclusion and exclusion checks, not only one-sided checks.

=== 3) Model Instance Method Scenario ===

Source: spec/models/user_spec.rb

<syntaxhighlight lang="ruby">
describe '#instructor_id' do
it 'returns own id for instructor' do
instructor = create(:user, role: instructor_role, institution: institution)
expect(instructor.instructor_id).to eq(instructor.id)
end

it 'raises NotImplementedError for student role' do
student = create(:user, role: student_role, institution: institution)
expect { student.instructor_id }.to raise_error(NotImplementedError, /Unknown role/)
end
end
</syntaxhighlight>

What this proves:
* Role-dependent instance behavior is enforced.
* Error behavior for unsupported roles is explicit and tested.

=== 4) Request Authorization Scenario ===

Source: spec/requests/api/v1/users_controller_spec.rb

<syntaxhighlight lang="ruby">
response '401', 'Unauthorized when token is invalid' do
let(:Authorization) { 'Bearer invalid_token' }

run_test! do |response|
body = JSON.parse(response.body)
expect(body['error']).to eq('Not Authorized')
end
end
</syntaxhighlight>

What this proves:
* JWT-protected routes fail safely and consistently with invalid tokens.

=== 5) Request Missing Parameter Scenario ===

Source: spec/requests/api/v1/users_controller_spec.rb

<syntaxhighlight lang="ruby">
response '422', 'Rejects request when user param is missing' do
let(:payload) { {} }

run_test! do |response|
body = JSON.parse(response.body)
expect(body['error']).to eq('Parameter missing')
end
end
</syntaxhighlight>

What this proves:
* ParameterMissing handling is validated through API tests.

=== 6) Request Invalid Role Scenario ===

Source: spec/requests/api/v1/users_controller_spec.rb

<syntaxhighlight lang="ruby">
response '404', 'Returns not found for invalid role name' do
let(:name) { 'role_that_does_not_exist' }

run_test! do |response|
body = JSON.parse(response.body)
expect(body['error']).to eq("Role 'Role That Does Not Exist' not found")
end
end
</syntaxhighlight>

What this proves:
* The role filter endpoint now has a stable, graceful failure contract.

== Production Fix Snippets that Back the Tested Results ==

=== users_controller: role lookup guard ===

Source: app/controllers/users_controller.rb

<syntaxhighlight lang="ruby">
def role_users
name = params[:name].split('_').map(&:capitalize).join(' ')
role = Role.find_by(name:)
unless role
render json: { error: "Role '#{name}' not found" }, status: :not_found
return
end
users = role.users
render json: users, status: :ok
rescue ActiveRecord::RecordNotFound => e
render json: { error: e.message }, status: :not_found
end
</syntaxhighlight>

=== user: strict boolean predicate for role check ===

Source: app/models/user.rb

<syntaxhighlight lang="ruby">
def teaching_assistant?
!!role.ta?
end
</syntaxhighlight>

== Defects Found and Fixed ==

{| class="wikitable" style="width:100%;"
|-
! Area !! Defect Observed During Implementation !! Fix Applied !! Linked Test Outcome
|-
| Role-filter endpoint || Missing role lookup path was not safely handled || Added explicit 404 JSON guard in controller || Invalid role request now asserted as 404 with message
|-
| Role predicate return type || Predicate behavior needed strict true/false consistency || Enforced boolean coercion in User model || teaching_assistant? expectations are stable
|-
| TA support path || Model integrity and query pattern needed tightening || Added validation and improved query path || Supporting logic stabilized for tested user flows
|-
| teams_participants uniqueness || DB constraint mismatched scoped uniqueness expectation || Added composite unique index migration || Constraint behavior aligned with model intent
|}

== Test Commands ==

Primary command:
<syntaxhighlight lang="bash">
bundle exec rspec spec/models/user_spec.rb spec/requests/api/v1/users_controller_spec.rb
</syntaxhighlight>

== Definition of Done Status ==

{| class="wikitable" style="width:100%;"
|-
! Completion Criteria !! Status
|-
| User model spec implemented with broad category coverage || Completed
|-
| UsersController request spec implemented for all target routes || Completed
|-
| Success and failure scenarios explicitly asserted || Completed
|-
| JWT-related authorization behavior covered || Completed
|-
| Defects discovered during testing fixed with targeted patches || Completed
|-
| Regression checks added for fragile paths || Completed
|-
| Reproducible verification command documented || Completed
|}

== Final Summary ==

E2615 is now a high-value quality layer for Expertiza user workflows. The project moved from negligible practical coverage to comprehensive, scenario-driven tests with concrete production hardening. The resulting test suites validate core contracts, enforce predictable API behavior, and provide a durable safety net for future development.

CSC/ECE 517 Spring 2026 - E2615. Testing User model and Users controller

2026-04-11T01:33:34Z

Awainga:

== About This Project ==

{| class="wikitable"; margin-left:20px; width:380px;"
|-
! colspan="2" style="background:#cee0f2; text-align:center;" | Project Info
|-
| '''Course''' || CSC/ECE 517 Spring 2026
|-
| '''Project''' || E2615 — Testing User Model and UsersController
|-
| '''Instructor''' || Ed Gehringer
|-
| '''Mentor''' || Aanand Sreekumaran Nair Jayakumari
|-
| '''Team Members''' || Atharva Waingankar, Krisha Darji, Saladin Al-Bataineh
|-
| '''Platform''' || Expertiza (Ruby on Rails)
|-
| '''Primary Test Framework''' || RSpec
|-
| '''Target Components''' || User model, UsersController
|-
| '''Current Coverage''' || No meaningful tests (stub files only)
|-
| '''Deliverables''' || Comprehensive model + request specs
|}

== Why This Project Matters ==

The User entity is the backbone of Expertiza. It controls identity, authentication, role-based behavior, and account management relationships.
The User model and UsersController currently have no meaningful tests in scope (legacy placeholders only), so regressions in critical user workflows can slip through unnoticed.

== Problem Statement ==

The current codebase has essentially zero useful automated test coverage for:

* User model behavior
* UsersController API behavior

Legacy minitest placeholders exist but are commented out and should be treated as empty. Without coverage for user creation, updates, role handling, and authorization-sensitive endpoints, regressions in core identity flows can go undetected.

== Background ==

=== What the User Class Represents ===

The <code>User</code> model stores core account information such as:

* username (<code>name</code>)
* <code>full_name</code>
* <code>email</code>
* <code>password_digest</code> (bcrypt-backed)
* role association (<code>role_id</code>)
* institution association (<code>institution_id</code>)
* self-referential manager relationship (<code>parent_id</code>)
* notification and preference flags

It also includes business logic for:

* role delegation helpers (student, TA, instructor, admin, super admin checks)
* role-scoped queries (students, tas, instructors, administrators, superadministrators)
* identity lookup (<code>login_user</code>)
* JWT creation (<code>generate_jwt</code>)
* impersonation and parent-chain checks
* JSON serialization contract for API responses

=== User Role Structure ===

<pre>
┌───────────────────────┐
│ User │
│ (core account) │
└───────────┬───────────┘
│ belongs_to
▼
┌─────────────┐
│ Role │
└──────┬──────┘
│ hierarchy
┌────────────────────────┼────────────────────────┐
▼ ▼ ▼
Student Teaching Assistant Instructor
│
▼
Administrator
│
▼
Super Administrator
</pre>

=== UsersController Functions ===

UsersController is a RESTful controller with standard CRUD and three custom collection routes.

{| class="wikitable" style="width:100%;"
|-
! Category !! Action !! Route !! Purpose
|-
| CRUD || index || GET /users || List all users
|-
| CRUD || show || GET /users/:id || Show one user
|-
| CRUD || create || POST /users || Create a user (applies default password when omitted)
|-
| CRUD || update || PATCH/PUT /users/:id || Update user attributes
|-
| CRUD || destroy || DELETE /users/:id || Delete a user
|-
| Custom || institution_users || GET /users/institution/:id || List users belonging to an institution
|-
| Custom || managed_users || GET /users/:id/managed || List users managed by a given user
|-
| Custom || role_users || GET /users/role/:name || List users by role name
|}

The controller also includes explicit rescue handlers for missing records and missing required parameters, which should be validated in request specs.

== Objectives ==

* Create comprehensive RSpec tests for User model validations, associations, scopes, authentication behavior, and domain methods.
* Create comprehensive request specs for all UsersController RESTful endpoints and custom collection routes.
* Verify HTTP status codes, response payload shape, and failure behavior for invalid input and missing records.
* Confirm role hierarchy setup and JWT-authenticated access patterns using repository conventions.
* Identify and fix defects uncovered by tests so the new suite is stable and passing.
* Ensure all work uses American English spelling and matches existing repository testing patterns.

== Scope ==

=== In Scope ===

* New model spec file for User behavior
* New request spec file for UsersController endpoints
* Necessary factory updates for reliable setup
* Small, targeted production-code fixes if tests expose defects

=== Out of Scope ===

* Broad refactors unrelated to User and UsersController
* Rewriting unrelated controllers or models
* UI or frontend behavior

== Files To Create ==

Following repository conventions under <code>spec/</code>:

* <code>spec/models/user_spec.rb</code>
* <code>spec/requests/api/v1/users_controller_spec.rb</code>

Potential supporting update:

* <code>spec/factories.rb</code> (extend existing user factory only if needed)

== Test Design Strategy ==

=== Model Spec Plan (<code>spec/models/user_spec.rb</code>) ===

{| class="wikitable" style="width:100%;"
|-
! Area !! What Will Be Tested !! Expected Result
|-
| Validations || presence, format, and length checks for <code>name</code>, <code>email</code>, <code>password</code>, <code>full_name</code> || Invalid data is rejected with clear errors
|-
| Associations || role, institution, parent, child users, invitations, assignments, teams, participants || Associations are correctly defined and functional
|-
| Scopes || students, tas, instructors, administrators, superadministrators || Each scope returns users with matching role
|-
| Delegated role checks || <code>student?</code>, <code>ta?</code>, <code>instructor?</code>, <code>administrator?</code>, <code>super_administrator?</code> || Role query methods behave consistently
|-
| Defaults || initialization flags and email preference defaults || Defaults are set correctly on initialization
|-
| Authentication behavior || <code>has_secure_password</code> behavior, password digest creation, minimum length || Password workflows behave securely and predictably
|-
| Class methods || <code>login_user</code>, <code>from_params</code>, <code>instantiate</code> || Lookup and STI conversion logic works as intended
|-
| Instance methods || <code>instructor_id</code>, <code>can_impersonate?</code>, <code>recursively_parent_of</code>, <code>teaching_assistant_for?</code>, <code>as_json</code>, <code>generate_jwt</code> || Methods return correct values and enforce role rules
|-
| Regression checks || edge cases and known fragile areas discovered during implementation || Defects are detected and fixed
|}

=== Request Spec Plan (<code>spec/requests/api/v1/users_controller_spec.rb</code>) ===

{| class="wikitable" style="width:100%;"
|-
! Endpoint !! Scenarios !! Expected Result
|-
| GET /users || Authenticated request || 200 with user list payload
|-
| GET /users/:id || Existing and missing id || 200 for existing, 404 for missing
|-
| POST /users || Valid payload, invalid payload, missing user param || 201 for valid, 422 for invalid or missing params
|-
| PATCH/PUT /users/:id || Valid update, invalid update, missing id || 200 for valid, 422 or 404 for failures
|-
| DELETE /users/:id || Existing and missing id || No-content success path, 404 for missing
|-
| GET /users/institution/:id || Valid institution and missing institution || 200 with users, 404 when not found
|-
| GET /users/:id/managed || Student parent versus non-student parent || 422 for student parent, 200 for allowed roles
|-
| GET /users/role/:name || Valid role name and missing role || 200 for valid role, graceful failure behavior for invalid role
|}

== Test Setup Conventions ==

Both new spec files will follow established repository patterns:

* <code>require 'swagger_helper'</code>
* <code>require 'json_web_token'</code>
* <code>create_roles_hierarchy</code> from <code>spec/support/roles_helper.rb</code>
* FactoryBot for test data
* JWT bearer token in Authorization header for request specs
* DatabaseCleaner behavior from <code>spec/rails_helper.rb</code> (already configured)

== Planned Work Breakdown ==

=== Task 1: Baseline and Test Scaffolding ===

* Create both target spec files with proper requires and role setup helpers
* Add shared setup helpers for authenticated requests and role seeds

=== Task 2: User Model Coverage ===

* Implement validation, association, scope, and method tests
* Add edge-case and regression-focused examples

=== Task 3: UsersController Coverage ===

* Implement request specs for all REST and custom routes
* Assert status codes and response body contracts

=== Task 4: Bug Fixes Uncovered by Tests ===

* Patch defects exposed by new tests (only where needed)
* Keep fixes minimal, targeted, and documented in commit history

=== Task 5: Stabilization and Pass Verification ===

* Run:
<syntaxhighlight lang="bash">
bundle exec rspec spec/models/user_spec.rb spec/requests/api/v1/users_controller_spec.rb
</syntaxhighlight>
* Ensure both files pass cleanly and do not introduce regressions in touched behavior

== Risks and Likely Defect Areas ==

Based on code review before implementation, the following areas are high risk and should be validated early:

* Role predicate behavior and delegated role checks
* STI conversion in <code>User.instantiate</code>
* <code>reset_password</code> implementation correctness
* Managed users logic across role hierarchy
* Error behavior when role lookup returns nil in role-filtered endpoint
* Authorization and authentication interactions on request endpoints

== Expected Results ==

By project completion, we expect:

* Two comprehensive, maintainable RSpec files covering the User model and UsersController
* Meaningful coverage of normal flows, invalid input, and edge cases for core user operations
* Verified behavior for JWT-authenticated requests and role-driven responses
* Any discovered defects in tested paths fixed and covered by regression tests
* A reproducible command that passes:
<syntaxhighlight lang="bash">
bundle exec rspec spec/models/user_spec.rb spec/requests/api/v1/users_controller_spec.rb
</syntaxhighlight>

== Definition of Done ==

* <code>spec/models/user_spec.rb</code> exists and covers core model behavior comprehensively
* <code>spec/requests/api/v1/users_controller_spec.rb</code> exists and covers all controller routes comprehensively
* Tests follow repository conventions and use role hierarchy helpers plus FactoryBot
* All tests in the project scope pass locally
* Documented expected behaviors align with Expertiza domain rules for users and roles

== Summary ==

E2615 establishes confidence in one of Expertiza’s most critical areas by introducing full automated coverage for user-domain logic and user API endpoints. The project focuses on correctness, authorization-aware behavior, robust error handling, and long-term maintainability through high-value RSpec tests and targeted defect fixes.

CSC/ECE 517 Spring 2026 - E2615. Testing User model and Users controller

2026-04-11T00:56:06Z

Awainga:

== About This Project ==

{| class="wikitable"; margin-left:20px; width:380px;"
|-
! colspan="2" style="background:#cee0f2; text-align:center;" | Project Info
|-
| '''Course''' || CSC/ECE 517 Spring 2026
|-
| '''Project''' || E2615 — Testing User Model and Users Controller
|-
| '''Instructor''' || Ed Gehringer
|-
| '''Mentor''' || Aanand Sreekumaran Nair Jayakumari
|-
| '''Team Members''' || Atharva Waingankar, Krisha Darji, Saladin Al-Bataineh
|-
| '''Platform''' || Expertiza (Ruby on Rails)
|-
| '''Primary Test Framework''' || RSpec
|-
| '''Target Components''' || User model, UsersController
|-
| '''Current Coverage''' || No meaningful tests (stub files only)
|-
| '''Deliverables''' || Comprehensive model + request specs
|}

== Why This Project Matters ==

The User entity is the backbone of Expertiza. It controls identity, authentication, role-based behavior, and account management relationships.
The User model and UsersController currently have no meaningful tests in scope (legacy placeholders only), so regressions in critical user workflows can slip through unnoticed.

== Problem Statement ==

The current codebase has essentially zero useful automated test coverage for:
* User model behavior
* UsersController API behavior

Legacy minitest placeholders exist but are commented out and should be treated as empty. Without coverage for user creation, updates, role handling, and authorization-sensitive endpoints, regressions in core identity flows can go undetected.

== Background: User Class ==

=== What User Represents ===
The `User` model stores core account information such as:

* username (`name`)
* `full_name`
* `email`
* `password_digest` (bcrypt-backed)
* role association (`role_id`)
* institution association (`institution_id`)
* self-referential manager relationship (`parent_id`)
* notification and preference flags

It also includes business logic for:

* role delegation helpers (student, TA, instructor, admin, super admin checks)
* role-scoped queries (students, tas, instructors, administrators, superadministrators)
* identity lookup (`login_user`)
* JWT creation (`generate_jwt`)
* impersonation and parent-chain checks
* JSON serialization contract for API responses

=== User Role Structure ===
<pre>
┌───────────────────────┐
│ User │
│ (core account) │
└───────────┬───────────┘
│ belongs_to
▼
┌─────────────┐
│ Role │
└──────┬──────┘
│ hierarchy
┌────────────────────────┼────────────────────────┐
▼ ▼ ▼
Student Teaching Assistant Instructor
│
▼
Administrator
│
▼
Super Administrator
</pre>

== Objectives ==

* Create comprehensive RSpec tests for User model validations, associations, scopes, authentication behavior, and domain methods.
* Create comprehensive request specs for all UsersController RESTful endpoints and custom collection routes.
* Verify HTTP status codes, response payload shape, and failure behavior for invalid input and missing records.
* Confirm role hierarchy setup and JWT-authenticated access patterns using repository conventions.
* Identify and fix defects uncovered by tests so the new suite is stable and passing.
* Ensure all work uses American English spelling and matches existing repository testing patterns.

== Scope ==

=== In Scope ===
* New model spec file for User behavior.
* New request spec file for UsersController endpoints.
* Necessary factory updates for reliable setup.
* Small, targeted production-code fixes if tests expose defects.

=== Out of Scope ===
* Broad refactors unrelated to User and UsersController.
* Rewriting unrelated controllers or models.
* UI/frontend behavior.

== Files To Create ==

Following repository conventions under spec/:

* spec/models/user_spec.rb
* spec/requests/api/v1/users_controller_spec.rb

Potential supporting update:

* spec/factories.rb (extend existing user factory only if needed)

== Background: User Domain Responsibilities ==

The User model is responsible for:
* Password hashing and authentication support (bcrypt / has_secure_password)
* Role linkage and role-based behavior
* Parent-child user relationships for managed accounts
* JWT generation support
* Participant/team/invitation associations
* Serialization of core user fields and related role/parent/institution data

UsersController is responsible for:
* Standard REST actions: index, show, create, update, destroy
* Custom collection endpoints:
** institution users listing
** managed users listing
** role-filtered users listing
* Error handling for missing records and missing parameters

== Test Design Strategy ==

=== Model Spec Plan (spec/models/user_spec.rb) ===

{| class="wikitable" style="width:100%;"
|-
! Area !! What Will Be Tested !! Expected Result
|-
| Validations || presence/format/length checks for name, email, password, full_name || invalid data is rejected with clear errors
|-
| Associations || role, institution, parent, child users, invitations, assignments, teams, participants || associations are correctly defined and functional
|-
| Scopes || students, tas, instructors, administrators, superadministrators || each scope returns users with matching role
|-
| Delegated role checks || student?/ta?/instructor?/administrator?/super_administrator? || role query methods behave consistently
|-
| Defaults || initialization flags and email preference defaults || defaults are set correctly on initialization
|-
| Authentication behavior || has_secure_password behavior, password digest creation, minimum length || password workflows behave securely and predictably
|-
| Class methods || login_user, from_params, instantiate || lookup and STI conversion logic works as intended
|-
| Instance methods || instructor_id, can_impersonate?, recursively_parent_of, teaching_assistant_for?, as_json, generate_jwt || methods return correct values and enforce role rules
|-
| Regression checks || edge cases and known fragile areas discovered during implementation || defects are detected and fixed
|}

=== Request Spec Plan (spec/requests/api/v1/users_controller_spec.rb) ===

{| class="wikitable" style="width:100%;"
|-
! Endpoint !! Scenarios !! Expected Result
|-
| GET /users || authenticated request || 200 with user list payload
|-
| GET /users/:id || existing and missing id || 200 for existing, 404 for missing
|-
| POST /users || valid payload, invalid payload, missing user param || 201 for valid, 422 for invalid/missing params
|-
| PATCH/PUT /users/:id || valid update, invalid update, missing id || 200 for valid, 422/404 for failures
|-
| DELETE /users/:id || existing and missing id || no-content success path, 404 for missing
|-
| GET /users/institution/:id || valid institution and missing institution || 200 with users, 404 when not found
|-
| GET /users/:id/managed || student parent vs non-student parent || 422 for student parent, 200 for allowed roles
|-
| GET /users/role/:name || valid role name and missing role || 200 for valid role, graceful failure behavior for invalid role
|}

== Test Setup Conventions ==

Both new spec files will follow established repository patterns:
* require 'swagger_helper'
* require 'json_web_token'
* create_roles_hierarchy from spec/support/roles_helper.rb
* FactoryBot for test data
* JWT bearer token in Authorization header for request specs
* DatabaseCleaner behavior from spec/rails_helper.rb (already configured)

== Planned Work Breakdown ==

=== Task 1: Baseline and Test Scaffolding ===
* Create both target spec files with proper requires and role setup helpers.
* Add shared setup helpers for authenticated requests and role seeds.

=== Task 2: User Model Coverage ===
* Implement validation, association, scope, and method tests.
* Add edge-case and regression-focused examples.

=== Task 3: UsersController Coverage ===
* Implement request specs for all REST and custom routes.
* Assert status codes and response body contracts.

=== Task 4: Bug Fixes Uncovered by Tests ===
* Patch defects exposed by new tests (only where needed).
* Keep fixes minimal, targeted, and documented in commit history.

=== Task 5: Stabilization and Pass Verification ===
* Run:
<syntaxhighlight lang="bash">
bundle exec rspec spec/models/user_spec.rb spec/requests/api/v1/users_controller_spec.rb
</syntaxhighlight>
* Ensure both files pass cleanly and do not introduce regressions in touched behavior.

== Risks and Likely Defect Areas ==

Based on code review before implementation, the following areas are high risk and should be validated early:

* Role predicate behavior and delegated role checks
* STI conversion in User.instantiate
* reset_password implementation correctness
* managed users logic across role hierarchy
* Error behavior when role lookup returns nil in role-filtered endpoint
* Authorization and authentication interactions on request endpoints

== Expected Results ==

By project completion, we expect:

* Two comprehensive, maintainable RSpec files covering the User model and UsersController.
* Meaningful coverage of normal flows, invalid input, and edge cases for core user operations.
* Verified behavior for JWT-authenticated requests and role-driven responses.
* Any discovered defects in tested paths fixed and covered by regression tests.
* A reproducible command that passes:
<syntaxhighlight lang="bash">
bundle exec rspec spec/models/user_spec.rb spec/requests/api/v1/users_controller_spec.rb
</syntaxhighlight>

== Definition of Done ==

* spec/models/user_spec.rb exists and covers core model behavior comprehensively.
* spec/requests/api/v1/users_controller_spec.rb exists and covers all controller routes comprehensively.
* Tests follow repository conventions and use role hierarchy helpers plus FactoryBot.
* All tests in the project scope pass locally.
* Documented expected behaviors align with Expertiza domain rules for users and roles.

== Summary ==

E2615 establishes confidence in one of Expertiza’s most critical areas by introducing full automated coverage for user-domain logic and user API endpoints. The project focuses on correctness, authorization-aware behavior, robust error handling, and long-term maintainability through high-value RSpec tests and targeted defect fixes.

CSC/ECE 517 Spring 2026 - E2615. Testing User model and Users controller

2026-04-11T00:43:59Z

Awainga:

== About This Project ==

{| class="wikitable"; margin-left:20px; width:380px;"
|-
! colspan="2" style="background:#cee0f2; text-align:center;" | Project Info
|-
| '''Course''' || CSC/ECE 517 Spring 2026
|-
| '''Project''' || E2615 — Testing User Model and Users Controller
|-
| '''Instructor''' || Ed Gehringer
|-
| '''Mentor''' || Aanand Sreekumaran Nair Jayakumari
|-
| '''Platform''' || Expertiza (Ruby on Rails)
|-
| '''Primary Test Framework''' || RSpec
|-
| '''Target Components''' || User model, UsersController
|-
| '''Current Coverage''' || No meaningful tests (stub files only)
|-
| '''Deliverables''' || Comprehensive model + request specs
|}

== Why This Project Matters ==

The User entity is the backbone of Expertiza. It controls identity, authentication, role-based behavior, and account management relationships.
The User model and UsersController currently have no meaningful tests in scope (legacy placeholders only), so regressions in critical user workflows can slip through unnoticed.

== Problem Statement ==

The current codebase has essentially zero useful automated test coverage for:
* User model behavior
* UsersController API behavior

Legacy minitest placeholders exist but are commented out and should be treated as empty. Without coverage for user creation, updates, role handling, and authorization-sensitive endpoints, regressions in core identity flows can go undetected.

== Background: User Class ==

=== What User Represents ===
The `User` model stores core account information such as:

* username (`name`)
* `full_name`
* `email`
* `password_digest` (bcrypt-backed)
* role association (`role_id`)
* institution association (`institution_id`)
* self-referential manager relationship (`parent_id`)
* notification and preference flags

It also includes business logic for:

* role delegation helpers (student, TA, instructor, admin, super admin checks)
* role-scoped queries (students, tas, instructors, administrators, superadministrators)
* identity lookup (`login_user`)
* JWT creation (`generate_jwt`)
* impersonation and parent-chain checks
* JSON serialization contract for API responses

=== User Role Structure ===
<pre>
┌───────────────────────┐
│ User │
│ (core account) │
└───────────┬───────────┘
│ belongs_to
▼
┌─────────────┐
│ Role │
└──────┬──────┘
│ hierarchy
┌────────────────────────┼────────────────────────┐
▼ ▼ ▼
Student Teaching Assistant Instructor
│
▼
Administrator
│
▼
Super Administrator
</pre>

== Objectives ==

* Create comprehensive RSpec tests for User model validations, associations, scopes, authentication behavior, and domain methods.
* Create comprehensive request specs for all UsersController RESTful endpoints and custom collection routes.
* Verify HTTP status codes, response payload shape, and failure behavior for invalid input and missing records.
* Confirm role hierarchy setup and JWT-authenticated access patterns using repository conventions.
* Identify and fix defects uncovered by tests so the new suite is stable and passing.
* Ensure all work uses American English spelling and matches existing repository testing patterns.

== Scope ==

=== In Scope ===
* New model spec file for User behavior.
* New request spec file for UsersController endpoints.
* Necessary factory updates for reliable setup.
* Small, targeted production-code fixes if tests expose defects.

=== Out of Scope ===
* Broad refactors unrelated to User and UsersController.
* Rewriting unrelated controllers or models.
* UI/frontend behavior.

== Files To Create ==

Following repository conventions under spec/:

* spec/models/user_spec.rb
* spec/requests/api/v1/users_controller_spec.rb

Potential supporting update:

* spec/factories.rb (extend existing user factory only if needed)

== Background: User Domain Responsibilities ==

The User model is responsible for:
* Password hashing and authentication support (bcrypt / has_secure_password)
* Role linkage and role-based behavior
* Parent-child user relationships for managed accounts
* JWT generation support
* Participant/team/invitation associations
* Serialization of core user fields and related role/parent/institution data

UsersController is responsible for:
* Standard REST actions: index, show, create, update, destroy
* Custom collection endpoints:
** institution users listing
** managed users listing
** role-filtered users listing
* Error handling for missing records and missing parameters

== Test Design Strategy ==

=== Model Spec Plan (spec/models/user_spec.rb) ===

{| class="wikitable" style="width:100%;"
|-
! Area !! What Will Be Tested !! Expected Result
|-
| Validations || presence/format/length checks for name, email, password, full_name || invalid data is rejected with clear errors
|-
| Associations || role, institution, parent, child users, invitations, assignments, teams, participants || associations are correctly defined and functional
|-
| Scopes || students, tas, instructors, administrators, superadministrators || each scope returns users with matching role
|-
| Delegated role checks || student?/ta?/instructor?/administrator?/super_administrator? || role query methods behave consistently
|-
| Defaults || initialization flags and email preference defaults || defaults are set correctly on initialization
|-
| Authentication behavior || has_secure_password behavior, password digest creation, minimum length || password workflows behave securely and predictably
|-
| Class methods || login_user, from_params, instantiate || lookup and STI conversion logic works as intended
|-
| Instance methods || instructor_id, can_impersonate?, recursively_parent_of, teaching_assistant_for?, as_json, generate_jwt || methods return correct values and enforce role rules
|-
| Regression checks || edge cases and known fragile areas discovered during implementation || defects are detected and fixed
|}

=== Request Spec Plan (spec/requests/api/v1/users_controller_spec.rb) ===

{| class="wikitable" style="width:100%;"
|-
! Endpoint !! Scenarios !! Expected Result
|-
| GET /users || authenticated request || 200 with user list payload
|-
| GET /users/:id || existing and missing id || 200 for existing, 404 for missing
|-
| POST /users || valid payload, invalid payload, missing user param || 201 for valid, 422 for invalid/missing params
|-
| PATCH/PUT /users/:id || valid update, invalid update, missing id || 200 for valid, 422/404 for failures
|-
| DELETE /users/:id || existing and missing id || no-content success path, 404 for missing
|-
| GET /users/institution/:id || valid institution and missing institution || 200 with users, 404 when not found
|-
| GET /users/:id/managed || student parent vs non-student parent || 422 for student parent, 200 for allowed roles
|-
| GET /users/role/:name || valid role name and missing role || 200 for valid role, graceful failure behavior for invalid role
|}

== Test Setup Conventions ==

Both new spec files will follow established repository patterns:
* require 'swagger_helper'
* require 'json_web_token'
* create_roles_hierarchy from spec/support/roles_helper.rb
* FactoryBot for test data
* JWT bearer token in Authorization header for request specs
* DatabaseCleaner behavior from spec/rails_helper.rb (already configured)

== Planned Work Breakdown ==

=== Task 1: Baseline and Test Scaffolding ===
* Create both target spec files with proper requires and role setup helpers.
* Add shared setup helpers for authenticated requests and role seeds.

=== Task 2: User Model Coverage ===
* Implement validation, association, scope, and method tests.
* Add edge-case and regression-focused examples.

=== Task 3: UsersController Coverage ===
* Implement request specs for all REST and custom routes.
* Assert status codes and response body contracts.

=== Task 4: Bug Fixes Uncovered by Tests ===
* Patch defects exposed by new tests (only where needed).
* Keep fixes minimal, targeted, and documented in commit history.

=== Task 5: Stabilization and Pass Verification ===
* Run:
<syntaxhighlight lang="bash">
bundle exec rspec spec/models/user_spec.rb spec/requests/api/v1/users_controller_spec.rb
</syntaxhighlight>
* Ensure both files pass cleanly and do not introduce regressions in touched behavior.

== Risks and Likely Defect Areas ==

Based on code review before implementation, the following areas are high risk and should be validated early:

* Role predicate behavior and delegated role checks
* STI conversion in User.instantiate
* reset_password implementation correctness
* managed users logic across role hierarchy
* Error behavior when role lookup returns nil in role-filtered endpoint
* Authorization and authentication interactions on request endpoints

== Expected Results ==

By project completion, we expect:

* Two comprehensive, maintainable RSpec files covering the User model and UsersController.
* Meaningful coverage of normal flows, invalid input, and edge cases for core user operations.
* Verified behavior for JWT-authenticated requests and role-driven responses.
* Any discovered defects in tested paths fixed and covered by regression tests.
* A reproducible command that passes:
<syntaxhighlight lang="bash">
bundle exec rspec spec/models/user_spec.rb spec/requests/api/v1/users_controller_spec.rb
</syntaxhighlight>

== Definition of Done ==

* spec/models/user_spec.rb exists and covers core model behavior comprehensively.
* spec/requests/api/v1/users_controller_spec.rb exists and covers all controller routes comprehensively.
* Tests follow repository conventions and use role hierarchy helpers plus FactoryBot.
* All tests in the project scope pass locally.
* Documented expected behaviors align with Expertiza domain rules for users and roles.

== Summary ==

E2615 establishes confidence in one of Expertiza’s most critical areas by introducing full automated coverage for user-domain logic and user API endpoints. The project focuses on correctness, authorization-aware behavior, robust error handling, and long-term maintainability through high-value RSpec tests and targeted defect fixes.

CSC/ECE 517 Spring 2026 - E2615. Testing User model and Users controller

2026-04-11T00:30:52Z

Awainga:

== About This Project ==

{| class="wikitable"; margin-left:20px; width:390px;"
|-
! colspan="2" style="background:#cee0f2; text-align:center;" | Project Info
|-
| '''Course''' || CSC/ECE 517 Spring 2026
|-
| '''Project''' || E2615 — Testing User Model and UsersController
|-
| '''Instructor''' || Ed Gehringer
|-
| '''Mentor''' || Aanand Sreekumaran Nair Jayakumari
|-
| '''Platform''' || Expertiza (Ruby on Rails)
|-
| '''Framework''' || RSpec
|-
| '''Project Status''' || Planning phase (implementation not started)
|}

This page is a '''design document''' for E2615.
No implementation work has started yet. This document defines what we will test, why it matters, and what outcomes we expect when the project is complete.

== Why This Project Matters ==

The User entity is the backbone of Expertiza. It controls identity, authentication, role-based behavior, and account management relationships.
The User model and UsersController currently have no meaningful tests in scope (legacy placeholders only), so regressions in critical user workflows can slip through unnoticed.

== Project Objectives ==

* Build complete RSpec coverage for the User model.
* Build complete request-level RSpec coverage for UsersController.
* Validate role-aware behavior, authentication flow assumptions, and API error handling.
* Follow existing repository test patterns for setup and data creation.
* Deliver stable, passing tests that can serve as a baseline for future user-related changes.

== Background: User Class ==

=== What User Represents ===
The `User` model stores core account information such as:

* username (`name`)
* `full_name`
* `email`
* `password_digest` (bcrypt-backed)
* role association (`role_id`)
* institution association (`institution_id`)
* self-referential manager relationship (`parent_id`)
* notification and preference flags

It also includes business logic for:

* role delegation helpers (student, TA, instructor, admin, super admin checks)
* role-scoped queries (students, tas, instructors, administrators, superadministrators)
* identity lookup (`login_user`)
* JWT creation (`generate_jwt`)
* impersonation and parent-chain checks
* JSON serialization contract for API responses

=== User Role Structure (Conceptual) ===
<pre>
┌───────────────────────┐
│ User │
│ (core account) │
└───────────┬───────────┘
│ belongs_to
▼
┌─────────────┐
│ Role │
└──────┬──────┘
│ hierarchy
┌────────────────────────┼────────────────────────┐
▼ ▼ ▼
Student Teaching Assistant Instructor
│
▼
Administrator
│
▼
Super Administrator
</pre>

=== Management Relationship (Self-Reference) ===
Users can manage other users through a parent-child relation:

<pre>
User (parent manager) 1 ────────* User (managed account)
via parent_id on child record
</pre>

This relationship is important for endpoints like managed user listing and impersonation checks.

== Background: UsersController ==

UsersController is a RESTful API controller with standard CRUD behavior plus three custom collection routes.

=== Standard REST Endpoints ===
{| class="wikitable" style="width:100%;"
|-
! Action !! Route !! Purpose
|-
| index || GET /users || List all users
|-
| show || GET /users/:id || Show one user
|-
| create || POST /users || Create a user (defaults password when omitted)
|-
| update || PATCH/PUT /users/:id || Update user attributes
|-
| destroy || DELETE /users/:id || Delete a user
|}

=== Custom Collection Endpoints ===
{| class="wikitable" style="width:100%;"
|-
! Action !! Route !! Purpose
|-
| institution_users || GET /users/institution/:id || List users for one institution
|-
| managed_users || GET /users/:id/managed || List users managed by a given user
|-
| role_users || GET /users/role/:name || List users by role name
|}

=== Error Handling Behavior to Validate ===
* Not found handling for missing records.
* Parameter missing handling for invalid payloads.
* Correct HTTP codes for success and failure scenarios.
* Stable response payload structure for client compatibility.

== Testing Scope (Planned) ==

== 1) Model Tests ==
File to create: `spec/models/user_spec.rb`

Planned coverage:

* validations (presence, format, length)
* associations (role, institution, parent/children, related has_many links)
* scopes by role
* delegated role predicate methods
* default attribute initialization
* class methods (`instantiate`, `login_user`, `from_params`)
* instance methods (`instructor_id`, `generate_jwt`, `as_json`, impersonation logic)
* edge cases and regression guards for fragile logic

== 2) Request Tests ==
File to create: `spec/requests/api/v1/users_controller_spec.rb`

Planned coverage:

* full CRUD endpoint behavior
* institution_users, managed_users, role_users
* response status codes and body shape
* invalid input and missing record behavior
* authentication-header-driven request setup using project conventions

== Test Conventions We Will Follow ==

* `require 'swagger_helper'`
* `require 'json_web_token'`
* `create_roles_hierarchy` from `spec/support/roles_helper.rb`
* FactoryBot for data setup
* Existing cleaning strategy from `spec/rails_helper.rb`

== Deliverables ==

* `spec/models/user_spec.rb` with comprehensive model coverage.
* `spec/requests/api/v1/users_controller_spec.rb` with comprehensive endpoint coverage.
* Updates to `spec/factories.rb` only if needed for clean setup.
* Bug fixes only when tests reveal real defects in User/UsersController behavior.

== Expected Results ==

At the end of the project, we expect:

* reliable automated coverage for User model and UsersController
* clear pass/fail confidence for core user workflows
* reduced regression risk in authentication, role handling, and account management APIs
* successful execution of:

<syntaxhighlight lang="bash">
bundle exec rspec spec/models/user_spec.rb spec/requests/api/v1/users_controller_spec.rb
</syntaxhighlight>

CSC/ECE 517 Spring 2026 - E2615. Testing User model and Users controller

2026-04-11T00:29:46Z

Awainga: Created page with "== About This Project == {| class="wikitable"; margin-left:20px; width:390px;" |- ! colspan="2" style="background:#cee0f2; text-align:center;" | Project Info |- | '''Course''' || CSC/ECE 517 Spring 2026 |- | '''Project''' || E2615 — Testing User Model and UsersController |- | '''Instructor''' || Ed Gehringer |- | '''Mentor''' || Aanand Sreekumaran Nair Jayakumari |- | '''Platform''' || Expertiza (Ruby on Rails) |- | '''Framework''' || RSpec |- | '''Project Status''' |..."

CSC/ECE 517 Spring 2026

2026-04-11T00:29:22Z

Awainga:

* [[CSC/ECE 517 Spring 2026 - E2600. Reimplement review_mapping_controller]]
* [[CSC/ECE 517 Spring 2026 - E2601. Reimplement student quizzes]]
* [[CSC/ECE 517 Spring 2026 - E2602. Reimplement student task view]]
* [[CSC/ECE 517 Spring 2026 - E2603. Implement ViewSubmissions frontend]]
* [[CSC/ECE 517 Spring 2026 - E2604. Finish Password Resets]]
* [[CSC/ECE 517 Spring 2026 - E2606. Finishing Import and Export helper module]]
* [[CSC/ECE 517 Spring 2026 - E2607. ResponseController Frontend]]
* [[CSC/ECE 517 Spring 2026 - E2609. Review calibration]]
* [[CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing]]
* [[CSC/ECE 517 Spring 2026 - E2615. Testing User model and Users controller]]
* [[CSC/ECE 517 Spring 2026 - E2617. Testing Questionnaire and Course Models]]

CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing

2026-03-31T00:46:33Z

Awainga:

== About This Project ==

{| class="wikitable"; margin-left:20px; width:320px;"
|-
! colspan="2" style="background:#cee0f2; text-align:center;" | Project Info
|-
| '''Course''' || CSC/ECE 517 Spring 2026
|-
| '''Project''' || E2610 — Teams Hierarchy Testing
|-
| '''Instructor''' || Ed Gehringer
|-
| '''Mentor''' || Vihar Manojkumar Shah
|-
| '''Collaborators''' || Atharva Waingankar, Krisha Darji, Saladin Al-Bataineh
|-
| '''Platform''' || Expertiza (Ruby on Rails)
|-
| '''Test Framework''' || RSpec
|-
| '''Root Class''' || <code>Team</code> (STI superclass)
|-
| '''Subclasses''' || <code>CourseTeam</code>, <code>AssignmentTeam</code>, <code>MentoredTeam</code>
|-
| '''Membership Join Model''' || <code>TeamsParticipant</code>

|}

The Expertiza platform organises student collaboration through a structured class hierarchy dedicated to managing teams. Teams are the fundamental unit of participation: they allow students to reserve topics, collaborate on coursework, and submit assignments for evaluation.

This project focuses on ensuring the correctness of the Team hierarchy and strengthening automated test coverage. The work emphasises membership validity (enrolment-based participation), preventing duplicate membership across teams, enforcing capacity limits when configured, ensuring MentoredTeam uses duty-based mentor identification, and validating controller authorisation and HTTP response behaviour.

== Background ==

=== The Team Hierarchy ===
The hierarchy is composed of exactly four classes:

* <code>Team</code> — STI superclass providing shared associations and common behaviours
* <code>CourseTeam</code> — course-scoped teams that persist across a course
* <code>AssignmentTeam</code> — assignment-scoped teams created for a single assignment
* <code>MentoredTeam</code> — subclass of <code>AssignmentTeam</code> with a designated mentor

Two broad kinds of team exist:

* '''Course teams''' (<code>CourseTeam</code>) persist throughout a course. In some instructional designs (e.g., Team-Based Learning), these teams are reused for multiple assignments.
* '''Assignment teams''' (<code>AssignmentTeam</code>) exist only for a single assignment. When mentors are used, assignment teams are instantiated as <code>MentoredTeam</code>.

=== Class Hierarchy Diagram ===
<pre>
┌─────────────────┐
│ Team │
│ (STI parent) │
└────────┬────────┘
│
┌─────────────────┴──────────────────┐
│ │
┌────────┴────────┐ ┌──────────┴──────────┐
│ CourseTeam │ │ AssignmentTeam │
│ (course-scoped) │ │ (assignment-scoped) │
└─────────────────┘ └──────────┬──────────┘
│
┌──────────┴──────────┐
│ MentoredTeam │
│ (mentor via duty) │
└─────────────────────┘
</pre>

=== Subclass Responsibilities ===
{| class="wikitable" style="width:100%;"
|-
! Class !! Scope !! Key Constraint !! Notes
|-
| <code>Team</code> || — || Shared membership/associations || Parent class for all team types (STI)
|-
| <code>CourseTeam</code> || Course || Member must be a course participant || Can be converted to/from assignment teams
|-
| <code>AssignmentTeam</code> || Assignment || Member must be an assignment participant || Capacity comes from <code>Assignment#max_team_size</code>
|-
| <code>MentoredTeam</code> || Assignment || Mentor identified by participant duty || Uses <code>Duty</code> + participant <code>duty_id</code>
|}

== Duty vs. Role Distinction ==

A critical design point (and a core source of bugs in this area) is the separation between a user's '''role''' and a participant's '''duty'''.

{| class="wikitable" style="width:100%;"
|-
! Concept !! Definition !! Examples
|-
| '''Role''' || System-level permission level assigned to a user account || <code>Instructor</code>, <code>Teaching Assistant</code>, <code>Student</code>
|-
| '''Duty''' || A function assigned to a participant ''within a specific team'' || <code>Submitter</code>, <code>Reviewer</code>, <code>Mentor</code>
|}

In Expertiza, mentors are not privileged system accounts; they are normal users assigned the duty of Mentor on one team. Therefore, mentor logic must use participant duty rather than user role.

== Previous Implementation ==

=== 1) MentoredTeam used role-based assumptions ===
The incorrect approach was to treat “mentor” as a system-level role check. This is incompatible with Expertiza’s domain model, where mentor is a team-level duty assigned to a participant.

'''What we changed:''' MentoredTeam mentor assignment and mentor discovery use <code>Duty</code> and the participant’s <code>duty_id</code>.

=== 2) Capacity enforcement was inconsistent / bypassable ===
Membership could be created through multiple paths (domain method, controllers, join-request acceptance). If enforcement only happened in one place, direct creation of <code>TeamsParticipant</code> could bypass capacity checks.

'''What we changed:''' Capacity is enforced at both:
* the domain method level (<code>Team#add_member</code>)
* the join model level (<code>TeamsParticipant</code> validation backstop)

Join-request acceptance also checks capacity inside a lock for race-safety.

=== 3) TeamsController authorisation was not explicit ===
The authorisation framework existed (global before_action), but <code>TeamsController</code> did not implement an explicit access policy. As a result, student actions could succeed where they should be forbidden.

'''What we changed:''' TeamsController now defines <code>action_allowed?</code>, and request specs verify correct <code>403 Forbidden</code> behaviour.

=== 4) CourseTeam capacity was assumed without schema support ===
The current schema does not provide a <code>max_team_size</code> attribute for courses. Attempting to enforce CourseTeam capacity via <code>course.max_team_size</code> results in runtime errors and breaks previously passing tests.

'''What we changed:''' Capacity enforcement is based on assignment configuration (<code>Assignment#max_team_size</code>). CourseTeams remain uncapped by default unless the schema is extended in the future.

== Implementation Summary ==

=== 1) Enrollment-based membership ===
Membership is grounded in valid participation. A user can only be added if the appropriate participant record exists in the correct parent scope.

<syntaxhighlight lang="ruby">
# app/models/team.rb
participant_type = is_a?(AssignmentTeam) ? AssignmentParticipant : CourseParticipant
participant_type.find_by(user_id: participant_or_user.id, parent_id: parent_id)
</syntaxhighlight>

=== 2) Prevent duplicate membership across teams ===
The join model prevents a participant from appearing on multiple teams:

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validates :participant_id, uniqueness: true
</syntaxhighlight>

A unique index migration reinforces this at the database level.

=== 3) Capacity enforcement (configured via Assignment) ===
Capacity is enforced via the assignment’s <code>max_team_size</code>. When at capacity, attempts to add are rejected with an error.

<syntaxhighlight lang="ruby">
# app/models/team.rb
def full?
max = max_size
return false if max.blank?
participants.count >= max
end
</syntaxhighlight>

<syntaxhighlight lang="ruby">
# app/models/team.rb
return { success: false, error: "Unable to add participant: team is at full capacity." } if full?
</syntaxhighlight>

=== 4) Join-model capacity backstop ===
Even direct join-table creation is blocked when a team is at capacity.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validate :team_not_full, on: :create

def team_not_full
return unless team
max = team.max_size
return if max.blank?

if team.participants.count >= max
errors.add(:base, "Team is at full capacity (max #{max}).")
end
end
</syntaxhighlight>

=== 5) Race-safe join request acceptance ===
Acceptance checks capacity while holding a lock to prevent two concurrent acceptances from overfilling a team.

<syntaxhighlight lang="ruby">
# app/controllers/join_team_requests_controller.rb (accept)
ActiveRecord::Base.transaction do
team.with_lock do
if team.full?
# reject accept
end
result = team.add_member(participant)
# reject if result failed
end

@join_team_request.update!(reply_status: ACCEPTED)
end
</syntaxhighlight>

=== 6) TeamsController authorisation and HTTP codes ===
TeamsController now declares an explicit policy:

* Teaching staff (TA and above): allowed
* Students: cannot list all teams, cannot manage membership, can only view teams they belong to

Request specs assert that restricted actions return <code>403</code> with an error payload.

== RSpec Test Coverage ==

The test suite is organised into model specs (domain rules) and request specs (API behaviour + HTTP status codes).

=== Model Specs ===
{| class="wikitable" style="width:100%;"
|-
! Area !! Spec File(s) !! What is validated
|-
| Team membership + validations || <code>spec/models/team_spec.rb</code> || Type/parent validation, membership checks, <code>full?</code>, <code>add_member</code>
|-
| Capacity behaviour || <code>spec/models/team_capacity_spec.rb</code> || AssignmentTeam capacity and error rejection
|-
| Association integrity || <code>spec/models/team_association_spec.rb</code> || Parent linkage and membership scoping
|-
| Conversion behaviour || <code>spec/models/team_conversion_spec.rb</code> || CourseTeam ⇄ AssignmentTeam conversions and member copying
|-
| MentoredTeam duty behaviour || <code>spec/models/mentored_team_spec.rb</code> || Mentor duty assignment/removal and mentor lookup by duty
|-
| Join model constraints || <code>spec/models/teams_participant_spec.rb</code> || Uniqueness, presence, and capacity backstop (no bypass)
|}

=== Request Specs ===
{| class="wikitable" style="width:100%;"
|-
! Endpoint Area !! Spec File(s) !! What is validated
|-
| Teams API || <code>spec/requests/api/v1/teams_controller_spec.rb</code> || Index/show/members/add/remove + authorisation status codes
|-
| JoinTeamRequests API || <code>spec/requests/api/v1/join_team_requests_controller_spec.rb</code> || Authorisation, create/accept/decline, capacity rejection and rollback behaviour
|-
| TeamsParticipants API || <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code> || Duty update authorisation, list/add/delete flows
|}

=== Important Example Tests ===

==== Capacity and size limits ====
<syntaxhighlight lang="ruby">
# spec/models/team_capacity_spec.rb
it 'rejects member when team is full' do
2.times { |i| team.add_member(make_participant("full#{i}")) }
extra = make_participant('extra')

result = team.add_member(extra)

expect(result[:success]).to be false
expect(result[:error]).to match(/capacity/i)
end
</syntaxhighlight>

Purpose: verifies domain-level capacity enforcement returns a structured failure and a meaningful error.

<syntaxhighlight lang="ruby">
# spec/models/teams_participant_spec.rb
describe 'capacity validation (team_not_full)' do
it 'raises when creating beyond capacity' do
assignment.update!(max_team_size: 1)
team = AssignmentTeam.create!(name: 'Cap Team2', parent_id: assignment.id)

u1 = make_user('cap2_u1')
p1 = AssignmentParticipant.create!(user: u1, parent_id: assignment.id, handle: u1.name)
TeamsParticipant.create!(team: team, participant: p1, user: u1)

u2 = make_user('cap2_u2')
p2 = AssignmentParticipant.create!(user: u2, parent_id: assignment.id, handle: u2.name)

expect {
TeamsParticipant.create!(team: team, participant: p2, user: u2)
}.to raise_error(ActiveRecord::RecordInvalid)
end
end
</syntaxhighlight>

Purpose: ensures capacity cannot be bypassed by direct join-table creation.

==== Join request acceptance rollback correctness ====
<syntaxhighlight lang="ruby">
# spec/requests/api/v1/join_team_requests_controller_spec.rb
it 'does not change reply_status or add participant when team is full' do
assignment.update!(max_team_size: 1)

patch "/join_team_requests/#{join_team_request.id}/accept", headers: team_member_headers

expect(response).to have_http_status(:unprocessable_entity)
expect(join_team_request.reload.reply_status).to eq('PENDING')
expect(team1.participants.reload).not_to include(participant2)
end
</syntaxhighlight>

Purpose: verifies the accept endpoint rejects at capacity and does not mutate state.

==== TeamsController authorisation / HTTP status codes ====
<syntaxhighlight lang="ruby">
# spec/requests/api/v1/teams_controller_spec.rb
it 'returns 403 for student on GET /teams' do
student_token = JsonWebToken.encode(id: other_user.id)
student_headers = { Authorization: "Bearer #{student_token}" }

get '/teams', headers: student_headers

expect(response).to have_http_status(:forbidden)
expect(JSON.parse(response.body)).to have_key('error')
end
</syntaxhighlight>

Purpose: ensures a student cannot list teams and receives <code>403</code> with an error payload.

==== MentoredTeam duty-based mentor behaviour ====
<syntaxhighlight lang="ruby">
# spec/models/mentored_team_spec.rb
it 'identifies mentor by duty not by role' do
mentor_duty
participant = make_participant('duty_mentor')
team.add_member(participant)
team.assign_mentor(participant.user)

expect(team.send(:mentor)).to eq(participant.user)
expect(participant.reload.duty).to eq(mentor_duty)
end
</syntaxhighlight>

Purpose: proves mentor identification is duty-based, matching Expertiza’s domain model.
== Demo Video==
https://www.youtube.com/watch?v=KZh-Kwhduok
== Summary ==
This project strengthens the Teams hierarchy by ensuring membership is grounded in enrolment, preventing duplicate membership, enforcing assignment team capacity with both domain-level checks and a join-table backstop, making join-request acceptance race-safe with locking, and implementing explicit TeamsController authorisation rules with request specs that validate correct HTTP response codes. MentoredTeam is tested to rely on participant duty (Mentor) rather than user role.

== References ==
* Expertiza project specification — Teams hierarchy testing (Mentor: Vihar Manojkumar Shah)
* Rails Guides — Active Record Associations
* RSpec Documentation

CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing

2026-03-30T01:17:25Z

Awainga: /* 2) Capacity enforcement was inconsistent */

== About This Project ==

{| class="wikitable"; margin-left:20px; width:320px;"
|-
! colspan="2" style="background:#cee0f2; text-align:center;" | Project Info
|-
| '''Course''' || CSC/ECE 517 Spring 2026
|-
| '''Project''' || E2610 — Teams Hierarchy Testing
|-
| '''Instructor''' || Ed Gehringer
|-
| '''Mentor''' || Vihar Manojkumar Shah
|-
| '''Collaborators''' || Atharva Waingankar, Krisha Darji, Saladin Al-Bataineh
|-
| '''Platform''' || Expertiza (Ruby on Rails)
|-
| '''Test Framework''' || RSpec
|-
| '''Root Class''' || <code>Team</code> (STI superclass)
|-
| '''Subclasses''' || <code>CourseTeam</code>, <code>AssignmentTeam</code>, <code>MentoredTeam</code>
|-
| '''Membership Join Model''' || <code>TeamsParticipant</code>

|}

The Expertiza platform organises student collaboration through a structured class hierarchy dedicated to managing teams. Teams are the fundamental unit of participation: they allow students to reserve topics, collaborate on coursework, and submit assignments for evaluation.

This project focuses on ensuring the correctness of the Team hierarchy and strengthening automated test coverage. The work emphasises membership validity (enrolment-based participation), preventing duplicate membership across teams, enforcing capacity limits when configured, ensuring MentoredTeam uses duty-based mentor identification, and validating controller authorisation and HTTP response behaviour.

== Background ==

=== The Team Hierarchy ===
The hierarchy is composed of exactly four classes:

* <code>Team</code> — STI superclass providing shared associations and common behaviours
* <code>CourseTeam</code> — course-scoped teams that persist across a course
* <code>AssignmentTeam</code> — assignment-scoped teams created for a single assignment
* <code>MentoredTeam</code> — subclass of <code>AssignmentTeam</code> with a designated mentor

Two broad kinds of team exist:

* '''Course teams''' (<code>CourseTeam</code>) persist throughout a course. In some instructional designs (e.g., Team-Based Learning), these teams are reused for multiple assignments.
* '''Assignment teams''' (<code>AssignmentTeam</code>) exist only for a single assignment. When mentors are used, assignment teams are instantiated as <code>MentoredTeam</code>.

=== Class Hierarchy Diagram ===
<pre>
┌─────────────────┐
│ Team │
│ (STI parent) │
└────────┬────────┘
│
┌─────────────────┴──────────────────┐
│ │
┌────────┴────────┐ ┌──────────┴──────────┐
│ CourseTeam │ │ AssignmentTeam │
│ (course-scoped) │ │ (assignment-scoped) │
└─────────────────┘ └──────────┬──────────┘
│
┌──────────┴──────────┐
│ MentoredTeam │
│ (mentor via duty) │
└─────────────────────┘
</pre>

=== Subclass Responsibilities ===
{| class="wikitable" style="width:100%;"
|-
! Class !! Scope !! Key Constraint !! Notes
|-
| <code>Team</code> || — || Shared membership/associations || Parent class for all team types (STI)
|-
| <code>CourseTeam</code> || Course || Member must be a course participant || Can be converted to/from assignment teams
|-
| <code>AssignmentTeam</code> || Assignment || Member must be an assignment participant || Capacity comes from <code>Assignment#max_team_size</code>
|-
| <code>MentoredTeam</code> || Assignment || Mentor identified by participant duty || Uses <code>Duty</code> + participant <code>duty_id</code>
|}

== Duty vs. Role Distinction ==

A critical design point (and a core source of bugs in this area) is the separation between a user's '''role''' and a participant's '''duty'''.

{| class="wikitable" style="width:100%;"
|-
! Concept !! Definition !! Examples
|-
| '''Role''' || System-level permission level assigned to a user account || <code>Instructor</code>, <code>Teaching Assistant</code>, <code>Student</code>
|-
| '''Duty''' || A function assigned to a participant ''within a specific team'' || <code>Submitter</code>, <code>Reviewer</code>, <code>Mentor</code>
|}

In Expertiza, mentors are not privileged system accounts; they are normal users assigned the duty of Mentor on one team. Therefore, mentor logic must use participant duty rather than user role.

== Previous Implementation ==

=== 1) MentoredTeam used role-based assumptions ===
The incorrect approach was to treat “mentor” as a system-level role check. This is incompatible with Expertiza’s domain model, where mentor is a team-level duty assigned to a participant.

'''What we changed:''' MentoredTeam mentor assignment and mentor discovery use <code>Duty</code> and the participant’s <code>duty_id</code>.

=== 2) Capacity enforcement was inconsistent / bypassable ===
Membership could be created through multiple paths (domain method, controllers, join-request acceptance). If enforcement only happened in one place, direct creation of <code>TeamsParticipant</code> could bypass capacity checks.

'''What we changed:''' Capacity is enforced at both:
* the domain method level (<code>Team#add_member</code>)
* the join model level (<code>TeamsParticipant</code> validation backstop)

Join-request acceptance also checks capacity inside a lock for race-safety.

=== 3) TeamsController authorisation was not explicit ===
The authorisation framework existed (global before_action), but <code>TeamsController</code> did not implement an explicit access policy. As a result, student actions could succeed where they should be forbidden.

'''What we changed:''' TeamsController now defines <code>action_allowed?</code>, and request specs verify correct <code>403 Forbidden</code> behaviour.

=== 4) CourseTeam capacity was assumed without schema support ===
The current schema does not provide a <code>max_team_size</code> attribute for courses. Attempting to enforce CourseTeam capacity via <code>course.max_team_size</code> results in runtime errors and breaks previously passing tests.

'''What we changed:''' Capacity enforcement is based on assignment configuration (<code>Assignment#max_team_size</code>). CourseTeams remain uncapped by default unless the schema is extended in the future.

== Implementation Summary ==

=== 1) Enrollment-based membership ===
Membership is grounded in valid participation. A user can only be added if the appropriate participant record exists in the correct parent scope.

<syntaxhighlight lang="ruby">
# app/models/team.rb
participant_type = is_a?(AssignmentTeam) ? AssignmentParticipant : CourseParticipant
participant_type.find_by(user_id: participant_or_user.id, parent_id: parent_id)
</syntaxhighlight>

=== 2) Prevent duplicate membership across teams ===
The join model prevents a participant from appearing on multiple teams:

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validates :participant_id, uniqueness: true
</syntaxhighlight>

A unique index migration reinforces this at the database level.

=== 3) Capacity enforcement (configured via Assignment) ===
Capacity is enforced via the assignment’s <code>max_team_size</code>. When at capacity, attempts to add are rejected with an error.

<syntaxhighlight lang="ruby">
# app/models/team.rb
def full?
max = max_size
return false if max.blank?
participants.count >= max
end
</syntaxhighlight>

<syntaxhighlight lang="ruby">
# app/models/team.rb
return { success: false, error: "Unable to add participant: team is at full capacity." } if full?
</syntaxhighlight>

=== 4) Join-model capacity backstop ===
Even direct join-table creation is blocked when a team is at capacity.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validate :team_not_full, on: :create

def team_not_full
return unless team
max = team.max_size
return if max.blank?

if team.participants.count >= max
errors.add(:base, "Team is at full capacity (max #{max}).")
end
end
</syntaxhighlight>

=== 5) Race-safe join request acceptance ===
Acceptance checks capacity while holding a lock to prevent two concurrent acceptances from overfilling a team.

<syntaxhighlight lang="ruby">
# app/controllers/join_team_requests_controller.rb (accept)
ActiveRecord::Base.transaction do
team.with_lock do
if team.full?
# reject accept
end
result = team.add_member(participant)
# reject if result failed
end

@join_team_request.update!(reply_status: ACCEPTED)
end
</syntaxhighlight>

=== 6) TeamsController authorisation and HTTP codes ===
TeamsController now declares an explicit policy:

* Teaching staff (TA and above): allowed
* Students: cannot list all teams, cannot manage membership, can only view teams they belong to

Request specs assert that restricted actions return <code>403</code> with an error payload.

== RSpec Test Coverage ==

The test suite is organised into model specs (domain rules) and request specs (API behaviour + HTTP status codes).

=== Model Specs ===
{| class="wikitable" style="width:100%;"
|-
! Area !! Spec File(s) !! What is validated
|-
| Team membership + validations || <code>spec/models/team_spec.rb</code> || Type/parent validation, membership checks, <code>full?</code>, <code>add_member</code>
|-
| Capacity behaviour || <code>spec/models/team_capacity_spec.rb</code> || AssignmentTeam capacity and error rejection
|-
| Association integrity || <code>spec/models/team_association_spec.rb</code> || Parent linkage and membership scoping
|-
| Conversion behaviour || <code>spec/models/team_conversion_spec.rb</code> || CourseTeam ⇄ AssignmentTeam conversions and member copying
|-
| MentoredTeam duty behaviour || <code>spec/models/mentored_team_spec.rb</code> || Mentor duty assignment/removal and mentor lookup by duty
|-
| Join model constraints || <code>spec/models/teams_participant_spec.rb</code> || Uniqueness, presence, and capacity backstop (no bypass)
|}

=== Request Specs ===
{| class="wikitable" style="width:100%;"
|-
! Endpoint Area !! Spec File(s) !! What is validated
|-
| Teams API || <code>spec/requests/api/v1/teams_controller_spec.rb</code> || Index/show/members/add/remove + authorisation status codes
|-
| JoinTeamRequests API || <code>spec/requests/api/v1/join_team_requests_controller_spec.rb</code> || Authorisation, create/accept/decline, capacity rejection and rollback behaviour
|-
| TeamsParticipants API || <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code> || Duty update authorisation, list/add/delete flows
|}

=== Important Example Tests ===

==== Capacity and size limits ====
<syntaxhighlight lang="ruby">
# spec/models/team_capacity_spec.rb
it 'rejects member when team is full' do
2.times { |i| team.add_member(make_participant("full#{i}")) }
extra = make_participant('extra')

result = team.add_member(extra)

expect(result[:success]).to be false
expect(result[:error]).to match(/capacity/i)
end
</syntaxhighlight>

Purpose: verifies domain-level capacity enforcement returns a structured failure and a meaningful error.

<syntaxhighlight lang="ruby">
# spec/models/teams_participant_spec.rb
describe 'capacity validation (team_not_full)' do
it 'raises when creating beyond capacity' do
assignment.update!(max_team_size: 1)
team = AssignmentTeam.create!(name: 'Cap Team2', parent_id: assignment.id)

u1 = make_user('cap2_u1')
p1 = AssignmentParticipant.create!(user: u1, parent_id: assignment.id, handle: u1.name)
TeamsParticipant.create!(team: team, participant: p1, user: u1)

u2 = make_user('cap2_u2')
p2 = AssignmentParticipant.create!(user: u2, parent_id: assignment.id, handle: u2.name)

expect {
TeamsParticipant.create!(team: team, participant: p2, user: u2)
}.to raise_error(ActiveRecord::RecordInvalid)
end
end
</syntaxhighlight>

Purpose: ensures capacity cannot be bypassed by direct join-table creation.

==== Join request acceptance rollback correctness ====
<syntaxhighlight lang="ruby">
# spec/requests/api/v1/join_team_requests_controller_spec.rb
it 'does not change reply_status or add participant when team is full' do
assignment.update!(max_team_size: 1)

patch "/join_team_requests/#{join_team_request.id}/accept", headers: team_member_headers

expect(response).to have_http_status(:unprocessable_entity)
expect(join_team_request.reload.reply_status).to eq('PENDING')
expect(team1.participants.reload).not_to include(participant2)
end
</syntaxhighlight>

Purpose: verifies the accept endpoint rejects at capacity and does not mutate state.

==== TeamsController authorisation / HTTP status codes ====
<syntaxhighlight lang="ruby">
# spec/requests/api/v1/teams_controller_spec.rb
it 'returns 403 for student on GET /teams' do
student_token = JsonWebToken.encode(id: other_user.id)
student_headers = { Authorization: "Bearer #{student_token}" }

get '/teams', headers: student_headers

expect(response).to have_http_status(:forbidden)
expect(JSON.parse(response.body)).to have_key('error')
end
</syntaxhighlight>

Purpose: ensures a student cannot list teams and receives <code>403</code> with an error payload.

==== MentoredTeam duty-based mentor behaviour ====
<syntaxhighlight lang="ruby">
# spec/models/mentored_team_spec.rb
it 'identifies mentor by duty not by role' do
mentor_duty
participant = make_participant('duty_mentor')
team.add_member(participant)
team.assign_mentor(participant.user)

expect(team.send(:mentor)).to eq(participant.user)
expect(participant.reload.duty).to eq(mentor_duty)
end
</syntaxhighlight>

Purpose: proves mentor identification is duty-based, matching Expertiza’s domain model.

== Summary ==
This project strengthens the Teams hierarchy by ensuring membership is grounded in enrolment, preventing duplicate membership, enforcing assignment team capacity with both domain-level checks and a join-table backstop, making join-request acceptance race-safe with locking, and implementing explicit TeamsController authorisation rules with request specs that validate correct HTTP response codes. MentoredTeam is tested to rely on participant duty (Mentor) rather than user role.

== References ==
* Expertiza project specification — Teams hierarchy testing (Mentor: Vihar Manojkumar Shah)
* Rails Guides — Active Record Associations
* RSpec Documentation

CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing

2026-03-30T01:17:17Z

Awainga: /* 2) Capacity enforcement was inconsistent */

== About This Project ==

{| class="wikitable"; margin-left:20px; width:320px;"
|-
! colspan="2" style="background:#cee0f2; text-align:center;" | Project Info
|-
| '''Course''' || CSC/ECE 517 Spring 2026
|-
| '''Project''' || E2610 — Teams Hierarchy Testing
|-
| '''Instructor''' || Ed Gehringer
|-
| '''Mentor''' || Vihar Manojkumar Shah
|-
| '''Collaborators''' || Atharva Waingankar, Krisha Darji, Saladin Al-Bataineh
|-
| '''Platform''' || Expertiza (Ruby on Rails)
|-
| '''Test Framework''' || RSpec
|-
| '''Root Class''' || <code>Team</code> (STI superclass)
|-
| '''Subclasses''' || <code>CourseTeam</code>, <code>AssignmentTeam</code>, <code>MentoredTeam</code>
|-
| '''Membership Join Model''' || <code>TeamsParticipant</code>

|}

The Expertiza platform organises student collaboration through a structured class hierarchy dedicated to managing teams. Teams are the fundamental unit of participation: they allow students to reserve topics, collaborate on coursework, and submit assignments for evaluation.

This project focuses on ensuring the correctness of the Team hierarchy and strengthening automated test coverage. The work emphasises membership validity (enrolment-based participation), preventing duplicate membership across teams, enforcing capacity limits when configured, ensuring MentoredTeam uses duty-based mentor identification, and validating controller authorisation and HTTP response behaviour.

== Background ==

=== The Team Hierarchy ===
The hierarchy is composed of exactly four classes:

* <code>Team</code> — STI superclass providing shared associations and common behaviours
* <code>CourseTeam</code> — course-scoped teams that persist across a course
* <code>AssignmentTeam</code> — assignment-scoped teams created for a single assignment
* <code>MentoredTeam</code> — subclass of <code>AssignmentTeam</code> with a designated mentor

Two broad kinds of team exist:

* '''Course teams''' (<code>CourseTeam</code>) persist throughout a course. In some instructional designs (e.g., Team-Based Learning), these teams are reused for multiple assignments.
* '''Assignment teams''' (<code>AssignmentTeam</code>) exist only for a single assignment. When mentors are used, assignment teams are instantiated as <code>MentoredTeam</code>.

=== Class Hierarchy Diagram ===
<pre>
┌─────────────────┐
│ Team │
│ (STI parent) │
└────────┬────────┘
│
┌─────────────────┴──────────────────┐
│ │
┌────────┴────────┐ ┌──────────┴──────────┐
│ CourseTeam │ │ AssignmentTeam │
│ (course-scoped) │ │ (assignment-scoped) │
└─────────────────┘ └──────────┬──────────┘
│
┌──────────┴──────────┐
│ MentoredTeam │
│ (mentor via duty) │
└─────────────────────┘
</pre>

=== Subclass Responsibilities ===
{| class="wikitable" style="width:100%;"
|-
! Class !! Scope !! Key Constraint !! Notes
|-
| <code>Team</code> || — || Shared membership/associations || Parent class for all team types (STI)
|-
| <code>CourseTeam</code> || Course || Member must be a course participant || Can be converted to/from assignment teams
|-
| <code>AssignmentTeam</code> || Assignment || Member must be an assignment participant || Capacity comes from <code>Assignment#max_team_size</code>
|-
| <code>MentoredTeam</code> || Assignment || Mentor identified by participant duty || Uses <code>Duty</code> + participant <code>duty_id</code>
|}

== Duty vs. Role Distinction ==

A critical design point (and a core source of bugs in this area) is the separation between a user's '''role''' and a participant's '''duty'''.

{| class="wikitable" style="width:100%;"
|-
! Concept !! Definition !! Examples
|-
| '''Role''' || System-level permission level assigned to a user account || <code>Instructor</code>, <code>Teaching Assistant</code>, <code>Student</code>
|-
| '''Duty''' || A function assigned to a participant ''within a specific team'' || <code>Submitter</code>, <code>Reviewer</code>, <code>Mentor</code>
|}

In Expertiza, mentors are not privileged system accounts; they are normal users assigned the duty of Mentor on one team. Therefore, mentor logic must use participant duty rather than user role.

== Previous Implementation ==

=== 1) MentoredTeam used role-based assumptions ===
The incorrect approach was to treat “mentor” as a system-level role check. This is incompatible with Expertiza’s domain model, where mentor is a team-level duty assigned to a participant.

'''What we changed:''' MentoredTeam mentor assignment and mentor discovery use <code>Duty</code> and the participant’s <code>duty_id</code>.

=== 2) Capacity enforcement was inconsistent ===
Membership could be created through multiple paths (domain method, controllers, join-request acceptance). If enforcement only happened in one place, direct creation of <code>TeamsParticipant</code> could bypass capacity checks.

'''What we changed:''' Capacity is enforced at both:
* the domain method level (<code>Team#add_member</code>)
* the join model level (<code>TeamsParticipant</code> validation backstop)

Join-request acceptance also checks capacity inside a lock for race-safety.

=== 3) TeamsController authorisation was not explicit ===
The authorisation framework existed (global before_action), but <code>TeamsController</code> did not implement an explicit access policy. As a result, student actions could succeed where they should be forbidden.

'''What we changed:''' TeamsController now defines <code>action_allowed?</code>, and request specs verify correct <code>403 Forbidden</code> behaviour.

=== 4) CourseTeam capacity was assumed without schema support ===
The current schema does not provide a <code>max_team_size</code> attribute for courses. Attempting to enforce CourseTeam capacity via <code>course.max_team_size</code> results in runtime errors and breaks previously passing tests.

'''What we changed:''' Capacity enforcement is based on assignment configuration (<code>Assignment#max_team_size</code>). CourseTeams remain uncapped by default unless the schema is extended in the future.

== Implementation Summary ==

=== 1) Enrollment-based membership ===
Membership is grounded in valid participation. A user can only be added if the appropriate participant record exists in the correct parent scope.

<syntaxhighlight lang="ruby">
# app/models/team.rb
participant_type = is_a?(AssignmentTeam) ? AssignmentParticipant : CourseParticipant
participant_type.find_by(user_id: participant_or_user.id, parent_id: parent_id)
</syntaxhighlight>

=== 2) Prevent duplicate membership across teams ===
The join model prevents a participant from appearing on multiple teams:

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validates :participant_id, uniqueness: true
</syntaxhighlight>

A unique index migration reinforces this at the database level.

=== 3) Capacity enforcement (configured via Assignment) ===
Capacity is enforced via the assignment’s <code>max_team_size</code>. When at capacity, attempts to add are rejected with an error.

<syntaxhighlight lang="ruby">
# app/models/team.rb
def full?
max = max_size
return false if max.blank?
participants.count >= max
end
</syntaxhighlight>

<syntaxhighlight lang="ruby">
# app/models/team.rb
return { success: false, error: "Unable to add participant: team is at full capacity." } if full?
</syntaxhighlight>

=== 4) Join-model capacity backstop ===
Even direct join-table creation is blocked when a team is at capacity.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validate :team_not_full, on: :create

def team_not_full
return unless team
max = team.max_size
return if max.blank?

if team.participants.count >= max
errors.add(:base, "Team is at full capacity (max #{max}).")
end
end
</syntaxhighlight>

=== 5) Race-safe join request acceptance ===
Acceptance checks capacity while holding a lock to prevent two concurrent acceptances from overfilling a team.

<syntaxhighlight lang="ruby">
# app/controllers/join_team_requests_controller.rb (accept)
ActiveRecord::Base.transaction do
team.with_lock do
if team.full?
# reject accept
end
result = team.add_member(participant)
# reject if result failed
end

@join_team_request.update!(reply_status: ACCEPTED)
end
</syntaxhighlight>

=== 6) TeamsController authorisation and HTTP codes ===
TeamsController now declares an explicit policy:

* Teaching staff (TA and above): allowed
* Students: cannot list all teams, cannot manage membership, can only view teams they belong to

Request specs assert that restricted actions return <code>403</code> with an error payload.

== RSpec Test Coverage ==

The test suite is organised into model specs (domain rules) and request specs (API behaviour + HTTP status codes).

=== Model Specs ===
{| class="wikitable" style="width:100%;"
|-
! Area !! Spec File(s) !! What is validated
|-
| Team membership + validations || <code>spec/models/team_spec.rb</code> || Type/parent validation, membership checks, <code>full?</code>, <code>add_member</code>
|-
| Capacity behaviour || <code>spec/models/team_capacity_spec.rb</code> || AssignmentTeam capacity and error rejection
|-
| Association integrity || <code>spec/models/team_association_spec.rb</code> || Parent linkage and membership scoping
|-
| Conversion behaviour || <code>spec/models/team_conversion_spec.rb</code> || CourseTeam ⇄ AssignmentTeam conversions and member copying
|-
| MentoredTeam duty behaviour || <code>spec/models/mentored_team_spec.rb</code> || Mentor duty assignment/removal and mentor lookup by duty
|-
| Join model constraints || <code>spec/models/teams_participant_spec.rb</code> || Uniqueness, presence, and capacity backstop (no bypass)
|}

=== Request Specs ===
{| class="wikitable" style="width:100%;"
|-
! Endpoint Area !! Spec File(s) !! What is validated
|-
| Teams API || <code>spec/requests/api/v1/teams_controller_spec.rb</code> || Index/show/members/add/remove + authorisation status codes
|-
| JoinTeamRequests API || <code>spec/requests/api/v1/join_team_requests_controller_spec.rb</code> || Authorisation, create/accept/decline, capacity rejection and rollback behaviour
|-
| TeamsParticipants API || <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code> || Duty update authorisation, list/add/delete flows
|}

=== Important Example Tests ===

==== Capacity and size limits ====
<syntaxhighlight lang="ruby">
# spec/models/team_capacity_spec.rb
it 'rejects member when team is full' do
2.times { |i| team.add_member(make_participant("full#{i}")) }
extra = make_participant('extra')

result = team.add_member(extra)

expect(result[:success]).to be false
expect(result[:error]).to match(/capacity/i)
end
</syntaxhighlight>

Purpose: verifies domain-level capacity enforcement returns a structured failure and a meaningful error.

<syntaxhighlight lang="ruby">
# spec/models/teams_participant_spec.rb
describe 'capacity validation (team_not_full)' do
it 'raises when creating beyond capacity' do
assignment.update!(max_team_size: 1)
team = AssignmentTeam.create!(name: 'Cap Team2', parent_id: assignment.id)

u1 = make_user('cap2_u1')
p1 = AssignmentParticipant.create!(user: u1, parent_id: assignment.id, handle: u1.name)
TeamsParticipant.create!(team: team, participant: p1, user: u1)

u2 = make_user('cap2_u2')
p2 = AssignmentParticipant.create!(user: u2, parent_id: assignment.id, handle: u2.name)

expect {
TeamsParticipant.create!(team: team, participant: p2, user: u2)
}.to raise_error(ActiveRecord::RecordInvalid)
end
end
</syntaxhighlight>

Purpose: ensures capacity cannot be bypassed by direct join-table creation.

==== Join request acceptance rollback correctness ====
<syntaxhighlight lang="ruby">
# spec/requests/api/v1/join_team_requests_controller_spec.rb
it 'does not change reply_status or add participant when team is full' do
assignment.update!(max_team_size: 1)

patch "/join_team_requests/#{join_team_request.id}/accept", headers: team_member_headers

expect(response).to have_http_status(:unprocessable_entity)
expect(join_team_request.reload.reply_status).to eq('PENDING')
expect(team1.participants.reload).not_to include(participant2)
end
</syntaxhighlight>

Purpose: verifies the accept endpoint rejects at capacity and does not mutate state.

==== TeamsController authorisation / HTTP status codes ====
<syntaxhighlight lang="ruby">
# spec/requests/api/v1/teams_controller_spec.rb
it 'returns 403 for student on GET /teams' do
student_token = JsonWebToken.encode(id: other_user.id)
student_headers = { Authorization: "Bearer #{student_token}" }

get '/teams', headers: student_headers

expect(response).to have_http_status(:forbidden)
expect(JSON.parse(response.body)).to have_key('error')
end
</syntaxhighlight>

Purpose: ensures a student cannot list teams and receives <code>403</code> with an error payload.

==== MentoredTeam duty-based mentor behaviour ====
<syntaxhighlight lang="ruby">
# spec/models/mentored_team_spec.rb
it 'identifies mentor by duty not by role' do
mentor_duty
participant = make_participant('duty_mentor')
team.add_member(participant)
team.assign_mentor(participant.user)

expect(team.send(:mentor)).to eq(participant.user)
expect(participant.reload.duty).to eq(mentor_duty)
end
</syntaxhighlight>

Purpose: proves mentor identification is duty-based, matching Expertiza’s domain model.

== Summary ==
This project strengthens the Teams hierarchy by ensuring membership is grounded in enrolment, preventing duplicate membership, enforcing assignment team capacity with both domain-level checks and a join-table backstop, making join-request acceptance race-safe with locking, and implementing explicit TeamsController authorisation rules with request specs that validate correct HTTP response codes. MentoredTeam is tested to rely on participant duty (Mentor) rather than user role.

== References ==
* Expertiza project specification — Teams hierarchy testing (Mentor: Vihar Manojkumar Shah)
* Rails Guides — Active Record Associations
* RSpec Documentation

CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing

2026-03-30T01:16:04Z

Awainga:

== About This Project ==

{| class="wikitable"; margin-left:20px; width:320px;"
|-
! colspan="2" style="background:#cee0f2; text-align:center;" | Project Info
|-
| '''Course''' || CSC/ECE 517 Spring 2026
|-
| '''Project''' || E2610 — Teams Hierarchy Testing
|-
| '''Instructor''' || Ed Gehringer
|-
| '''Mentor''' || Vihar Manojkumar Shah
|-
| '''Collaborators''' || Atharva Waingankar, Krisha Darji, Saladin Al-Bataineh
|-
| '''Platform''' || Expertiza (Ruby on Rails)
|-
| '''Test Framework''' || RSpec
|-
| '''Root Class''' || <code>Team</code> (STI superclass)
|-
| '''Subclasses''' || <code>CourseTeam</code>, <code>AssignmentTeam</code>, <code>MentoredTeam</code>
|-
| '''Membership Join Model''' || <code>TeamsParticipant</code>

|}

The Expertiza platform organises student collaboration through a structured class hierarchy dedicated to managing teams. Teams are the fundamental unit of participation: they allow students to reserve topics, collaborate on coursework, and submit assignments for evaluation.

This project focuses on ensuring the correctness of the Team hierarchy and strengthening automated test coverage. The work emphasises membership validity (enrolment-based participation), preventing duplicate membership across teams, enforcing capacity limits when configured, ensuring MentoredTeam uses duty-based mentor identification, and validating controller authorisation and HTTP response behaviour.

== Background ==

=== The Team Hierarchy ===
The hierarchy is composed of exactly four classes:

* <code>Team</code> — STI superclass providing shared associations and common behaviours
* <code>CourseTeam</code> — course-scoped teams that persist across a course
* <code>AssignmentTeam</code> — assignment-scoped teams created for a single assignment
* <code>MentoredTeam</code> — subclass of <code>AssignmentTeam</code> with a designated mentor

Two broad kinds of team exist:

* '''Course teams''' (<code>CourseTeam</code>) persist throughout a course. In some instructional designs (e.g., Team-Based Learning), these teams are reused for multiple assignments.
* '''Assignment teams''' (<code>AssignmentTeam</code>) exist only for a single assignment. When mentors are used, assignment teams are instantiated as <code>MentoredTeam</code>.

=== Class Hierarchy Diagram ===
<pre>
┌─────────────────┐
│ Team │
│ (STI parent) │
└────────┬────────┘
│
┌─────────────────┴──────────────────┐
│ │
┌────────┴────────┐ ┌──────────┴──────────┐
│ CourseTeam │ │ AssignmentTeam │
│ (course-scoped) │ │ (assignment-scoped) │
└─────────────────┘ └──────────┬──────────┘
│
┌──────────┴──────────┐
│ MentoredTeam │
│ (mentor via duty) │
└─────────────────────┘
</pre>

=== Subclass Responsibilities ===
{| class="wikitable" style="width:100%;"
|-
! Class !! Scope !! Key Constraint !! Notes
|-
| <code>Team</code> || — || Shared membership/associations || Parent class for all team types (STI)
|-
| <code>CourseTeam</code> || Course || Member must be a course participant || Can be converted to/from assignment teams
|-
| <code>AssignmentTeam</code> || Assignment || Member must be an assignment participant || Capacity comes from <code>Assignment#max_team_size</code>
|-
| <code>MentoredTeam</code> || Assignment || Mentor identified by participant duty || Uses <code>Duty</code> + participant <code>duty_id</code>
|}

== Duty vs. Role Distinction ==

A critical design point (and a core source of bugs in this area) is the separation between a user's '''role''' and a participant's '''duty'''.

{| class="wikitable" style="width:100%;"
|-
! Concept !! Definition !! Examples
|-
| '''Role''' || System-level permission level assigned to a user account || <code>Instructor</code>, <code>Teaching Assistant</code>, <code>Student</code>
|-
| '''Duty''' || A function assigned to a participant ''within a specific team'' || <code>Submitter</code>, <code>Reviewer</code>, <code>Mentor</code>
|}

In Expertiza, mentors are not privileged system accounts; they are normal users assigned the duty of Mentor on one team. Therefore, mentor logic must use participant duty rather than user role.

== Previous Implementation ==

=== 1) MentoredTeam used role-based assumptions ===
The incorrect approach was to treat “mentor” as a system-level role check. This is incompatible with Expertiza’s domain model, where mentor is a team-level duty assigned to a participant.

'''What we changed:''' MentoredTeam mentor assignment and mentor discovery use <code>Duty</code> and the participant’s <code>duty_id</code>.

=== 2) Capacity enforcement was inconsistent / bypassable ===
Membership could be created through multiple paths (domain method, controllers, join-request acceptance). If enforcement only happened in one place, direct creation of <code>TeamsParticipant</code> could bypass capacity checks.

'''What we changed:''' Capacity is enforced at both:
* the domain method level (<code>Team#add_member</code>)
* the join model level (<code>TeamsParticipant</code> validation backstop)

Join-request acceptance also checks capacity inside a lock for race-safety.

=== 3) TeamsController authorisation was not explicit ===
The authorisation framework existed (global before_action), but <code>TeamsController</code> did not implement an explicit access policy. As a result, student actions could succeed where they should be forbidden.

'''What we changed:''' TeamsController now defines <code>action_allowed?</code>, and request specs verify correct <code>403 Forbidden</code> behaviour.

=== 4) CourseTeam capacity was assumed without schema support ===
The current schema does not provide a <code>max_team_size</code> attribute for courses. Attempting to enforce CourseTeam capacity via <code>course.max_team_size</code> results in runtime errors and breaks previously passing tests.

'''What we changed:''' Capacity enforcement is based on assignment configuration (<code>Assignment#max_team_size</code>). CourseTeams remain uncapped by default unless the schema is extended in the future.

== Implementation Summary ==

=== 1) Enrollment-based membership ===
Membership is grounded in valid participation. A user can only be added if the appropriate participant record exists in the correct parent scope.

<syntaxhighlight lang="ruby">
# app/models/team.rb
participant_type = is_a?(AssignmentTeam) ? AssignmentParticipant : CourseParticipant
participant_type.find_by(user_id: participant_or_user.id, parent_id: parent_id)
</syntaxhighlight>

=== 2) Prevent duplicate membership across teams ===
The join model prevents a participant from appearing on multiple teams:

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validates :participant_id, uniqueness: true
</syntaxhighlight>

A unique index migration reinforces this at the database level.

=== 3) Capacity enforcement (configured via Assignment) ===
Capacity is enforced via the assignment’s <code>max_team_size</code>. When at capacity, attempts to add are rejected with an error.

<syntaxhighlight lang="ruby">
# app/models/team.rb
def full?
max = max_size
return false if max.blank?
participants.count >= max
end
</syntaxhighlight>

<syntaxhighlight lang="ruby">
# app/models/team.rb
return { success: false, error: "Unable to add participant: team is at full capacity." } if full?
</syntaxhighlight>

=== 4) Join-model capacity backstop ===
Even direct join-table creation is blocked when a team is at capacity.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validate :team_not_full, on: :create

def team_not_full
return unless team
max = team.max_size
return if max.blank?

if team.participants.count >= max
errors.add(:base, "Team is at full capacity (max #{max}).")
end
end
</syntaxhighlight>

=== 5) Race-safe join request acceptance ===
Acceptance checks capacity while holding a lock to prevent two concurrent acceptances from overfilling a team.

<syntaxhighlight lang="ruby">
# app/controllers/join_team_requests_controller.rb (accept)
ActiveRecord::Base.transaction do
team.with_lock do
if team.full?
# reject accept
end
result = team.add_member(participant)
# reject if result failed
end

@join_team_request.update!(reply_status: ACCEPTED)
end
</syntaxhighlight>

=== 6) TeamsController authorisation and HTTP codes ===
TeamsController now declares an explicit policy:

* Teaching staff (TA and above): allowed
* Students: cannot list all teams, cannot manage membership, can only view teams they belong to

Request specs assert that restricted actions return <code>403</code> with an error payload.

== RSpec Test Coverage ==

The test suite is organised into model specs (domain rules) and request specs (API behaviour + HTTP status codes).

=== Model Specs ===
{| class="wikitable" style="width:100%;"
|-
! Area !! Spec File(s) !! What is validated
|-
| Team membership + validations || <code>spec/models/team_spec.rb</code> || Type/parent validation, membership checks, <code>full?</code>, <code>add_member</code>
|-
| Capacity behaviour || <code>spec/models/team_capacity_spec.rb</code> || AssignmentTeam capacity and error rejection
|-
| Association integrity || <code>spec/models/team_association_spec.rb</code> || Parent linkage and membership scoping
|-
| Conversion behaviour || <code>spec/models/team_conversion_spec.rb</code> || CourseTeam ⇄ AssignmentTeam conversions and member copying
|-
| MentoredTeam duty behaviour || <code>spec/models/mentored_team_spec.rb</code> || Mentor duty assignment/removal and mentor lookup by duty
|-
| Join model constraints || <code>spec/models/teams_participant_spec.rb</code> || Uniqueness, presence, and capacity backstop (no bypass)
|}

=== Request Specs ===
{| class="wikitable" style="width:100%;"
|-
! Endpoint Area !! Spec File(s) !! What is validated
|-
| Teams API || <code>spec/requests/api/v1/teams_controller_spec.rb</code> || Index/show/members/add/remove + authorisation status codes
|-
| JoinTeamRequests API || <code>spec/requests/api/v1/join_team_requests_controller_spec.rb</code> || Authorisation, create/accept/decline, capacity rejection and rollback behaviour
|-
| TeamsParticipants API || <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code> || Duty update authorisation, list/add/delete flows
|}

=== Important Example Tests ===

==== Capacity and size limits ====
<syntaxhighlight lang="ruby">
# spec/models/team_capacity_spec.rb
it 'rejects member when team is full' do
2.times { |i| team.add_member(make_participant("full#{i}")) }
extra = make_participant('extra')

result = team.add_member(extra)

expect(result[:success]).to be false
expect(result[:error]).to match(/capacity/i)
end
</syntaxhighlight>

Purpose: verifies domain-level capacity enforcement returns a structured failure and a meaningful error.

<syntaxhighlight lang="ruby">
# spec/models/teams_participant_spec.rb
describe 'capacity validation (team_not_full)' do
it 'raises when creating beyond capacity' do
assignment.update!(max_team_size: 1)
team = AssignmentTeam.create!(name: 'Cap Team2', parent_id: assignment.id)

u1 = make_user('cap2_u1')
p1 = AssignmentParticipant.create!(user: u1, parent_id: assignment.id, handle: u1.name)
TeamsParticipant.create!(team: team, participant: p1, user: u1)

u2 = make_user('cap2_u2')
p2 = AssignmentParticipant.create!(user: u2, parent_id: assignment.id, handle: u2.name)

expect {
TeamsParticipant.create!(team: team, participant: p2, user: u2)
}.to raise_error(ActiveRecord::RecordInvalid)
end
end
</syntaxhighlight>

Purpose: ensures capacity cannot be bypassed by direct join-table creation.

==== Join request acceptance rollback correctness ====
<syntaxhighlight lang="ruby">
# spec/requests/api/v1/join_team_requests_controller_spec.rb
it 'does not change reply_status or add participant when team is full' do
assignment.update!(max_team_size: 1)

patch "/join_team_requests/#{join_team_request.id}/accept", headers: team_member_headers

expect(response).to have_http_status(:unprocessable_entity)
expect(join_team_request.reload.reply_status).to eq('PENDING')
expect(team1.participants.reload).not_to include(participant2)
end
</syntaxhighlight>

Purpose: verifies the accept endpoint rejects at capacity and does not mutate state.

==== TeamsController authorisation / HTTP status codes ====
<syntaxhighlight lang="ruby">
# spec/requests/api/v1/teams_controller_spec.rb
it 'returns 403 for student on GET /teams' do
student_token = JsonWebToken.encode(id: other_user.id)
student_headers = { Authorization: "Bearer #{student_token}" }

get '/teams', headers: student_headers

expect(response).to have_http_status(:forbidden)
expect(JSON.parse(response.body)).to have_key('error')
end
</syntaxhighlight>

Purpose: ensures a student cannot list teams and receives <code>403</code> with an error payload.

==== MentoredTeam duty-based mentor behaviour ====
<syntaxhighlight lang="ruby">
# spec/models/mentored_team_spec.rb
it 'identifies mentor by duty not by role' do
mentor_duty
participant = make_participant('duty_mentor')
team.add_member(participant)
team.assign_mentor(participant.user)

expect(team.send(:mentor)).to eq(participant.user)
expect(participant.reload.duty).to eq(mentor_duty)
end
</syntaxhighlight>

Purpose: proves mentor identification is duty-based, matching Expertiza’s domain model.

== Summary ==
This project strengthens the Teams hierarchy by ensuring membership is grounded in enrolment, preventing duplicate membership, enforcing assignment team capacity with both domain-level checks and a join-table backstop, making join-request acceptance race-safe with locking, and implementing explicit TeamsController authorisation rules with request specs that validate correct HTTP response codes. MentoredTeam is tested to rely on participant duty (Mentor) rather than user role.

== References ==
* Expertiza project specification — Teams hierarchy testing (Mentor: Vihar Manojkumar Shah)
* Rails Guides — Active Record Associations
* RSpec Documentation

CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing

2026-03-30T00:50:28Z

Awainga:

== About This Project ==

{| class="wikitable"; margin-left:20px; width:320px;"
|-
! colspan="2" style="background:#cee0f2; text-align:center;" | Project Info
|-
| '''Course''' || CSC/ECE 517 Spring 2026
|-
| '''Project''' || E2610 — Teams Hierarchy Testing
|-
| '''Instructor''' || Ed Gehringer
|-
| '''Mentor''' || Vihar Manojkumar Shah
|-
| '''Collaborators''' || Atharva Waingankar, Krisha Darji, Saladin Al-Bataineh
|-
| '''Platform''' || Expertiza (Ruby on Rails)
|-
| '''Test Framework''' || RSpec
|-
| '''Root Class''' || <code>Team</code> (STI superclass)
|-
| '''Subclasses''' || <code>CourseTeam</code>, <code>AssignmentTeam</code>, <code>MentoredTeam</code>
|-
| '''Membership Join Model''' || <code>TeamsParticipant</code>

|}

The Expertiza platform organises student collaboration through a structured class hierarchy dedicated to managing teams. Teams are the unit used to reserve topics, collaborate on coursework, and submit work. This project focuses on validating the correctness of the Team hierarchy and providing thorough RSpec test coverage for team membership rules, conversions between team types, capacity enforcement, and MentoredTeam mentor logic (duty-based rather than role-based).

== Background ==

=== The Team Hierarchy ===
The hierarchy consists of exactly four classes: <code>Team</code> (superclass), <code>CourseTeam</code>, <code>AssignmentTeam</code>, and <code>MentoredTeam</code>. Teams are stored using Rails STI (single table inheritance) via the <code>type</code> column.

Two broad kinds of teams exist:

* '''Course teams''' (<code>CourseTeam</code>) — persist for the duration of an entire course and can be reused across multiple assignments.
* '''Assignment teams''' (<code>AssignmentTeam</code>) — formed for a single assignment. When mentor assignment is enabled, teams are instantiated as <code>MentoredTeam</code>, a subclass of <code>AssignmentTeam</code>.

=== Class Hierarchy Diagram ===
<pre>
┌─────────────────┐
│ Team │
│ (STI parent) │
└────────┬────────┘
│
┌─────────────────┴──────────────────┐
│ │
┌────────┴────────┐ ┌──────────┴──────────┐
│ CourseTeam │ │ AssignmentTeam │
│ (course-scoped) │ │ (assignment-scoped) │
└─────────────────┘ └──────────┬──────────┘
│
┌──────────┴──────────┐
│ MentoredTeam │
│ (mentor via duty) │
└─────────────────────┘
</pre>

=== Subclass Responsibilities ===
{| class="wikitable" style="width:100%;"
|-
! Class !! Scope !! Key Constraint !! Notes
|-
| <code>Team</code> || — || STI superclass, shared associations/logic || Holds membership helpers and core add/remove methods
|-
| <code>CourseTeam</code> || Course || Members must be course participants || Supports conversion to/from assignment teams
|-
| <code>AssignmentTeam</code> || Assignment || Members must be assignment participants || Capacity comes from <code>Assignment#max_team_size</code>
|-
| <code>MentoredTeam</code> || Assignment || Mentor identified by participant duty || Uses <code>Duty</code> + participant <code>duty_id</code>
|}

== Duty vs. Role Distinction ==
A critical design point is the separation between a user's '''role''' and their '''duty''' within a team.

{| class="wikitable" style="width:100%;"
|-
! Concept !! Definition !! Examples
|-
| '''Role''' || System-level permission level for a user account || <code>Instructor</code>, <code>Teaching Assistant</code>, <code>Student</code>
|-
| '''Duty''' || Team-level function of a participant on a specific team || <code>Submitter</code>, <code>Reviewer</code>, <code>Mentor</code>
|}

In Expertiza, mentors are not special system accounts. A mentor is a normal user whose '''participant record''' has been assigned the '''Mentor duty''' for a particular team. This project enforces and tests mentor identification by duty (not user role).

== Project Goals Implemented ==

=== Membership grounded in valid participation ===
Membership is mediated through <code>Participant</code> records:
* CourseTeam: must be a <code>CourseParticipant</code> for the same course (<code>parent_id</code>).
* AssignmentTeam / MentoredTeam: must be an <code>AssignmentParticipant</code> for the same assignment (<code>parent_id</code>).

This is enforced in <code>Team#add_member</code> by resolving the correct participant type based on the team’s subclass and the team’s <code>parent_id</code>.

<syntaxhighlight lang="ruby">
# app/models/team.rb
def add_member(participant_or_user)
participant =
if participant_or_user.is_a?(AssignmentParticipant) || participant_or_user.is_a?(CourseParticipant)
participant_or_user
elsif participant_or_user.is_a?(User)
participant_type = is_a?(AssignmentTeam) ? AssignmentParticipant : CourseParticipant
participant_type.find_by(user_id: participant_or_user.id, parent_id: parent_id)
else
nil
end

return { success: false, error: "#{participant_or_user.name} is not a participant in this #{is_a?(AssignmentTeam) ? 'assignment' : 'course'}" } if participant.nil?
return { success: false, error: "Participant already on the team" } if participants.exists?(id: participant.id)
return { success: false, error: "Unable to add participant: team is at full capacity." } if full?

team_participant = TeamsParticipant.create(
participant_id: participant.id,
team_id: id,
user_id: participant.user_id
)

team_participant.persisted? ? { success: true } : { success: false, error: team_participant.errors.full_messages.join(', ') }
end
</syntaxhighlight>

=== No user should appear on multiple teams in the same scope ===
The membership join model includes a uniqueness rule that prevents the same participant from being on multiple teams.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validates :participant_id, uniqueness: true
</syntaxhighlight>

A corresponding database migration adds a unique index on <code>participant_id</code> to make this constraint durable at the DB level.

=== Team size limits respected (capacity enforcement) ===
Capacity is enforced in two layers:

1) '''Domain-level check''': <code>Team#add_member</code> rejects when <code>full?</code> is true (returns <code>{success:false, error: ...}</code>).

2) '''Join-model backstop''': direct creation of <code>TeamsParticipant</code> is prevented if the team is already full.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validate :team_not_full, on: :create

def team_not_full
return unless team

max = team.max_size
return if max.blank?

if team.participants.count >= max
errors.add(:base, "Team is at full capacity (max #{max}).")
end
end
</syntaxhighlight>

This prevents bypassing capacity by calling <code>TeamsParticipant.create!</code> directly.

=== Join request acceptance is race-safe ===
The join request acceptance flow is guarded using a transaction and a lock, so that capacity is checked at the time of insertion.

<syntaxhighlight lang="ruby">
# app/controllers/join_team_requests_controller.rb
ActiveRecord::Base.transaction do
team.with_lock do
raise ActiveRecord::RecordInvalid, tp if team.full?
result = team.add_member(participant)
raise ActiveRecord::RecordInvalid, tp unless result[:success]
end

@join_team_request.update!(reply_status: ACCEPTED)
render json: { message: 'Join team request accepted successfully', ... }, status: :ok
end
</syntaxhighlight>

== MentoredTeam ==
MentoredTeam mentor identification and assignment are based on participant duty:

* A mentor duty is represented by a <code>Duty</code> record with name <code>'Mentor'</code>.
* The mentor is the participant on the team whose <code>duty_id</code> equals that duty.

<syntaxhighlight lang="ruby">
# app/models/mentored_team.rb
def assign_mentor(user)
mentor_duty = Duty.find_by(name: 'Mentor')
return false unless mentor_duty

participant = AssignmentParticipant.find_by(user_id: user.id, parent_id: parent_id)
return false unless participant

participant.update(duty_id: mentor_duty.id)
end
</syntaxhighlight>

<syntaxhighlight lang="ruby">
# app/models/mentored_team.rb (mentor lookup)
AssignmentParticipant
.joins('INNER JOIN teams_participants ON teams_participants.participant_id = participants.id')
.where('teams_participants.team_id = ? AND participants.duty_id = ?', id, mentor_duty.id)
.first&.user
</syntaxhighlight>

== RSpec Test Coverage (Actual Specs in This Project) ==

=== Model Specs ===
{| class="wikitable" style="width:100%;"
|-
! Area !! Spec File(s) !! What is validated
|-
| Team validations + membership rules || <code>spec/models/team_spec.rb</code> || Presence/type validation, <code>full?</code>, <code>add_member</code>, eligibility rules
|-
| Capacity behavior || <code>spec/models/team_capacity_spec.rb</code> || Assignment capacity behavior; course teams expected to be uncapped by default
|-
| Association integrity || <code>spec/models/team_association_spec.rb</code> || Team-parent linkage and membership scoping
|-
| Conversion behavior || <code>spec/models/team_conversion_spec.rb</code> || CourseTeam ⇄ AssignmentTeam conversions and member copying
|-
| MentoredTeam duty behavior || <code>spec/models/mentored_team_spec.rb</code> || Mentor duty assignment/removal, mentor lookup by duty, capacity inheritance from AssignmentTeam
|-
| Join model constraints || <code>spec/models/teams_participant_spec.rb</code> || Uniqueness/presence validations; enrollment rules via <code>Team#add_member</code>
|}

=== Request Specs (API/Controllers) ===
{| class="wikitable" style="width:100%;"
|-
! Endpoint Area !! Spec File(s) !! What is validated
|-
| Teams API || <code>spec/requests/api/v1/teams_controller_spec.rb</code> || Index/show/members/add/remove behavior (HTTP codes + JSON shape)
|-
| JoinTeamRequests API || <code>spec/requests/api/v1/join_team_requests_controller_spec.rb</code> || Authorization rules, creating requests, accepting/declining, “team full” responses
|-
| TeamsParticipants API || <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code> || Update duty authorization, list/add/delete participant endpoints
|}

== Summary ==
This project strengthens the teams hierarchy by enforcing enrollment-based membership, preventing duplicate participation across teams, enforcing assignment team capacity with a join-model backstop, and implementing/testing MentoredTeam mentor behavior using participant duty rather than user role. Comprehensive RSpec coverage spans models, conversions, and API request behaviors.

== References ==
* Expertiza project specification — Teams hierarchy testing
* Rails Guides — Active Record Associations
* RSpec Documentation

CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing

2026-03-30T00:49:39Z

Awainga:

== About This Project ==

{| class="wikitable" style="float:right; margin-left:20px; width:320px;"
|-
! colspan="2" style="background:#cee0f2; text-align:center;" | Project Info
|-
| '''Course''' || CSC/ECE 517 Spring 2026
|-
| '''Project''' || E2610 — Teams Hierarchy Testing
|-
| '''Instructor''' || Ed Gehringer
|-
| '''Mentor''' || Vihar Manojkumar Shah
|-
| '''Collaborators''' || Atharva Waingankar, Krisha Darji, Saladin Al-Bataineh
|-
| '''Platform''' || Expertiza (Ruby on Rails)
|-
| '''Test Framework''' || RSpec
|-
| '''Root Class''' || <code>Team</code> (STI superclass)
|-
| '''Subclasses''' || <code>CourseTeam</code>, <code>AssignmentTeam</code>, <code>MentoredTeam</code>
|-
| '''Membership Join Model''' || <code>TeamsParticipant</code>

|}

The Expertiza platform organises student collaboration through a structured class hierarchy dedicated to managing teams. Teams are the unit used to reserve topics, collaborate on coursework, and submit work. This project focuses on validating the correctness of the Team hierarchy and providing thorough RSpec test coverage for team membership rules, conversions between team types, capacity enforcement, and MentoredTeam mentor logic (duty-based rather than role-based).

== Background ==

=== The Team Hierarchy ===
The hierarchy consists of exactly four classes: <code>Team</code> (superclass), <code>CourseTeam</code>, <code>AssignmentTeam</code>, and <code>MentoredTeam</code>. Teams are stored using Rails STI (single table inheritance) via the <code>type</code> column.

Two broad kinds of teams exist:

* '''Course teams''' (<code>CourseTeam</code>) — persist for the duration of an entire course and can be reused across multiple assignments.
* '''Assignment teams''' (<code>AssignmentTeam</code>) — formed for a single assignment. When mentor assignment is enabled, teams are instantiated as <code>MentoredTeam</code>, a subclass of <code>AssignmentTeam</code>.

=== Class Hierarchy Diagram ===
<pre>
┌─────────────────┐
│ Team │
│ (STI parent) │
└────────┬────────┘
│
┌─────────────────┴──────────────────┐
│ │
┌────────┴────────┐ ┌──────────┴──────────┐
│ CourseTeam │ │ AssignmentTeam │
│ (course-scoped) │ │ (assignment-scoped) │
└─────────────────┘ └──────────┬──────────┘
│
┌──────────┴──────────┐
│ MentoredTeam │
│ (mentor via duty) │
└─────────────────────┘
</pre>

=== Subclass Responsibilities ===
{| class="wikitable" style="width:100%;"
|-
! Class !! Scope !! Key Constraint !! Notes
|-
| <code>Team</code> || — || STI superclass, shared associations/logic || Holds membership helpers and core add/remove methods
|-
| <code>CourseTeam</code> || Course || Members must be course participants || Supports conversion to/from assignment teams
|-
| <code>AssignmentTeam</code> || Assignment || Members must be assignment participants || Capacity comes from <code>Assignment#max_team_size</code>
|-
| <code>MentoredTeam</code> || Assignment || Mentor identified by participant duty || Uses <code>Duty</code> + participant <code>duty_id</code>
|}

== Duty vs. Role Distinction ==
A critical design point is the separation between a user's '''role''' and their '''duty''' within a team.

{| class="wikitable" style="width:100%;"
|-
! Concept !! Definition !! Examples
|-
| '''Role''' || System-level permission level for a user account || <code>Instructor</code>, <code>Teaching Assistant</code>, <code>Student</code>
|-
| '''Duty''' || Team-level function of a participant on a specific team || <code>Submitter</code>, <code>Reviewer</code>, <code>Mentor</code>
|}

In Expertiza, mentors are not special system accounts. A mentor is a normal user whose '''participant record''' has been assigned the '''Mentor duty''' for a particular team. This project enforces and tests mentor identification by duty (not user role).

== Project Goals Implemented ==

=== Membership grounded in valid participation ===
Membership is mediated through <code>Participant</code> records:
* CourseTeam: must be a <code>CourseParticipant</code> for the same course (<code>parent_id</code>).
* AssignmentTeam / MentoredTeam: must be an <code>AssignmentParticipant</code> for the same assignment (<code>parent_id</code>).

This is enforced in <code>Team#add_member</code> by resolving the correct participant type based on the team’s subclass and the team’s <code>parent_id</code>.

<syntaxhighlight lang="ruby">
# app/models/team.rb
def add_member(participant_or_user)
participant =
if participant_or_user.is_a?(AssignmentParticipant) || participant_or_user.is_a?(CourseParticipant)
participant_or_user
elsif participant_or_user.is_a?(User)
participant_type = is_a?(AssignmentTeam) ? AssignmentParticipant : CourseParticipant
participant_type.find_by(user_id: participant_or_user.id, parent_id: parent_id)
else
nil
end

return { success: false, error: "#{participant_or_user.name} is not a participant in this #{is_a?(AssignmentTeam) ? 'assignment' : 'course'}" } if participant.nil?
return { success: false, error: "Participant already on the team" } if participants.exists?(id: participant.id)
return { success: false, error: "Unable to add participant: team is at full capacity." } if full?

team_participant = TeamsParticipant.create(
participant_id: participant.id,
team_id: id,
user_id: participant.user_id
)

team_participant.persisted? ? { success: true } : { success: false, error: team_participant.errors.full_messages.join(', ') }
end
</syntaxhighlight>

=== No user should appear on multiple teams in the same scope ===
The membership join model includes a uniqueness rule that prevents the same participant from being on multiple teams.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validates :participant_id, uniqueness: true
</syntaxhighlight>

A corresponding database migration adds a unique index on <code>participant_id</code> to make this constraint durable at the DB level.

=== Team size limits respected (capacity enforcement) ===
Capacity is enforced in two layers:

1) '''Domain-level check''': <code>Team#add_member</code> rejects when <code>full?</code> is true (returns <code>{success:false, error: ...}</code>).

2) '''Join-model backstop''': direct creation of <code>TeamsParticipant</code> is prevented if the team is already full.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validate :team_not_full, on: :create

def team_not_full
return unless team

max = team.max_size
return if max.blank?

if team.participants.count >= max
errors.add(:base, "Team is at full capacity (max #{max}).")
end
end
</syntaxhighlight>

This prevents bypassing capacity by calling <code>TeamsParticipant.create!</code> directly.

=== Join request acceptance is race-safe ===
The join request acceptance flow is guarded using a transaction and a lock, so that capacity is checked at the time of insertion.

<syntaxhighlight lang="ruby">
# app/controllers/join_team_requests_controller.rb
ActiveRecord::Base.transaction do
team.with_lock do
raise ActiveRecord::RecordInvalid, tp if team.full?
result = team.add_member(participant)
raise ActiveRecord::RecordInvalid, tp unless result[:success]
end

@join_team_request.update!(reply_status: ACCEPTED)
render json: { message: 'Join team request accepted successfully', ... }, status: :ok
end
</syntaxhighlight>

== MentoredTeam ==
MentoredTeam mentor identification and assignment are based on participant duty:

* A mentor duty is represented by a <code>Duty</code> record with name <code>'Mentor'</code>.
* The mentor is the participant on the team whose <code>duty_id</code> equals that duty.

<syntaxhighlight lang="ruby">
# app/models/mentored_team.rb
def assign_mentor(user)
mentor_duty = Duty.find_by(name: 'Mentor')
return false unless mentor_duty

participant = AssignmentParticipant.find_by(user_id: user.id, parent_id: parent_id)
return false unless participant

participant.update(duty_id: mentor_duty.id)
end
</syntaxhighlight>

<syntaxhighlight lang="ruby">
# app/models/mentored_team.rb (mentor lookup)
AssignmentParticipant
.joins('INNER JOIN teams_participants ON teams_participants.participant_id = participants.id')
.where('teams_participants.team_id = ? AND participants.duty_id = ?', id, mentor_duty.id)
.first&.user
</syntaxhighlight>

== RSpec Test Coverage (Actual Specs in This Project) ==

=== Model Specs ===
{| class="wikitable" style="width:100%;"
|-
! Area !! Spec File(s) !! What is validated
|-
| Team validations + membership rules || <code>spec/models/team_spec.rb</code> || Presence/type validation, <code>full?</code>, <code>add_member</code>, eligibility rules
|-
| Capacity behavior || <code>spec/models/team_capacity_spec.rb</code> || Assignment capacity behavior; course teams expected to be uncapped by default
|-
| Association integrity || <code>spec/models/team_association_spec.rb</code> || Team-parent linkage and membership scoping
|-
| Conversion behavior || <code>spec/models/team_conversion_spec.rb</code> || CourseTeam ⇄ AssignmentTeam conversions and member copying
|-
| MentoredTeam duty behavior || <code>spec/models/mentored_team_spec.rb</code> || Mentor duty assignment/removal, mentor lookup by duty, capacity inheritance from AssignmentTeam
|-
| Join model constraints || <code>spec/models/teams_participant_spec.rb</code> || Uniqueness/presence validations; enrollment rules via <code>Team#add_member</code>
|}

=== Request Specs (API/Controllers) ===
{| class="wikitable" style="width:100%;"
|-
! Endpoint Area !! Spec File(s) !! What is validated
|-
| Teams API || <code>spec/requests/api/v1/teams_controller_spec.rb</code> || Index/show/members/add/remove behavior (HTTP codes + JSON shape)
|-
| JoinTeamRequests API || <code>spec/requests/api/v1/join_team_requests_controller_spec.rb</code> || Authorization rules, creating requests, accepting/declining, “team full” responses
|-
| TeamsParticipants API || <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code> || Update duty authorization, list/add/delete participant endpoints
|}

== Summary ==
This project strengthens the teams hierarchy by enforcing enrollment-based membership, preventing duplicate participation across teams, enforcing assignment team capacity with a join-model backstop, and implementing/testing MentoredTeam mentor behavior using participant duty rather than user role. Comprehensive RSpec coverage spans models, conversions, and API request behaviors.

== References ==
* Expertiza project specification — Teams hierarchy testing
* Rails Guides — Active Record Associations
* RSpec Documentation

CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing

2026-03-30T00:49:17Z

Awainga:

== About This Project ==

{| class="wikitable" style="float:left; margin-left:20px; width:320px;"
|-
! colspan="2" style="background:#cee0f2; text-align:center;" | Project Info
|-
| '''Course''' || CSC/ECE 517 Spring 2026
|-
| '''Project''' || E2610 — Teams Hierarchy Testing
|-
| '''Instructor''' || Ed Gehringer
|-
| '''Mentor''' || Vihar Manojkumar Shah
|-
| '''Collaborators''' || Atharva Waingankar, Krisha Darji, Saladin Al-Bataineh
|-
| '''Platform''' || Expertiza (Ruby on Rails)
|-
| '''Test Framework''' || RSpec
|-
| '''Root Class''' || <code>Team</code> (STI superclass)
|-
| '''Subclasses''' || <code>CourseTeam</code>, <code>AssignmentTeam</code>, <code>MentoredTeam</code>
|-
| '''Membership Join Model''' || <code>TeamsParticipant</code>

|}

The Expertiza platform organises student collaboration through a structured class hierarchy dedicated to managing teams. Teams are the unit used to reserve topics, collaborate on coursework, and submit work. This project focuses on validating the correctness of the Team hierarchy and providing thorough RSpec test coverage for team membership rules, conversions between team types, capacity enforcement, and MentoredTeam mentor logic (duty-based rather than role-based).

== Background ==

=== The Team Hierarchy ===
The hierarchy consists of exactly four classes: <code>Team</code> (superclass), <code>CourseTeam</code>, <code>AssignmentTeam</code>, and <code>MentoredTeam</code>. Teams are stored using Rails STI (single table inheritance) via the <code>type</code> column.

Two broad kinds of teams exist:

* '''Course teams''' (<code>CourseTeam</code>) — persist for the duration of an entire course and can be reused across multiple assignments.
* '''Assignment teams''' (<code>AssignmentTeam</code>) — formed for a single assignment. When mentor assignment is enabled, teams are instantiated as <code>MentoredTeam</code>, a subclass of <code>AssignmentTeam</code>.

=== Class Hierarchy Diagram ===
<pre>
┌─────────────────┐
│ Team │
│ (STI parent) │
└────────┬────────┘
│
┌─────────────────┴──────────────────┐
│ │
┌────────┴────────┐ ┌──────────┴──────────┐
│ CourseTeam │ │ AssignmentTeam │
│ (course-scoped) │ │ (assignment-scoped) │
└─────────────────┘ └──────────┬──────────┘
│
┌──────────┴──────────┐
│ MentoredTeam │
│ (mentor via duty) │
└─────────────────────┘
</pre>

=== Subclass Responsibilities ===
{| class="wikitable" style="width:100%;"
|-
! Class !! Scope !! Key Constraint !! Notes
|-
| <code>Team</code> || — || STI superclass, shared associations/logic || Holds membership helpers and core add/remove methods
|-
| <code>CourseTeam</code> || Course || Members must be course participants || Supports conversion to/from assignment teams
|-
| <code>AssignmentTeam</code> || Assignment || Members must be assignment participants || Capacity comes from <code>Assignment#max_team_size</code>
|-
| <code>MentoredTeam</code> || Assignment || Mentor identified by participant duty || Uses <code>Duty</code> + participant <code>duty_id</code>
|}

== Duty vs. Role Distinction ==
A critical design point is the separation between a user's '''role''' and their '''duty''' within a team.

{| class="wikitable" style="width:100%;"
|-
! Concept !! Definition !! Examples
|-
| '''Role''' || System-level permission level for a user account || <code>Instructor</code>, <code>Teaching Assistant</code>, <code>Student</code>
|-
| '''Duty''' || Team-level function of a participant on a specific team || <code>Submitter</code>, <code>Reviewer</code>, <code>Mentor</code>
|}

In Expertiza, mentors are not special system accounts. A mentor is a normal user whose '''participant record''' has been assigned the '''Mentor duty''' for a particular team. This project enforces and tests mentor identification by duty (not user role).

== Project Goals Implemented ==

=== Membership grounded in valid participation ===
Membership is mediated through <code>Participant</code> records:
* CourseTeam: must be a <code>CourseParticipant</code> for the same course (<code>parent_id</code>).
* AssignmentTeam / MentoredTeam: must be an <code>AssignmentParticipant</code> for the same assignment (<code>parent_id</code>).

This is enforced in <code>Team#add_member</code> by resolving the correct participant type based on the team’s subclass and the team’s <code>parent_id</code>.

<syntaxhighlight lang="ruby">
# app/models/team.rb
def add_member(participant_or_user)
participant =
if participant_or_user.is_a?(AssignmentParticipant) || participant_or_user.is_a?(CourseParticipant)
participant_or_user
elsif participant_or_user.is_a?(User)
participant_type = is_a?(AssignmentTeam) ? AssignmentParticipant : CourseParticipant
participant_type.find_by(user_id: participant_or_user.id, parent_id: parent_id)
else
nil
end

return { success: false, error: "#{participant_or_user.name} is not a participant in this #{is_a?(AssignmentTeam) ? 'assignment' : 'course'}" } if participant.nil?
return { success: false, error: "Participant already on the team" } if participants.exists?(id: participant.id)
return { success: false, error: "Unable to add participant: team is at full capacity." } if full?

team_participant = TeamsParticipant.create(
participant_id: participant.id,
team_id: id,
user_id: participant.user_id
)

team_participant.persisted? ? { success: true } : { success: false, error: team_participant.errors.full_messages.join(', ') }
end
</syntaxhighlight>

=== No user should appear on multiple teams in the same scope ===
The membership join model includes a uniqueness rule that prevents the same participant from being on multiple teams.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validates :participant_id, uniqueness: true
</syntaxhighlight>

A corresponding database migration adds a unique index on <code>participant_id</code> to make this constraint durable at the DB level.

=== Team size limits respected (capacity enforcement) ===
Capacity is enforced in two layers:

1) '''Domain-level check''': <code>Team#add_member</code> rejects when <code>full?</code> is true (returns <code>{success:false, error: ...}</code>).

2) '''Join-model backstop''': direct creation of <code>TeamsParticipant</code> is prevented if the team is already full.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validate :team_not_full, on: :create

def team_not_full
return unless team

max = team.max_size
return if max.blank?

if team.participants.count >= max
errors.add(:base, "Team is at full capacity (max #{max}).")
end
end
</syntaxhighlight>

This prevents bypassing capacity by calling <code>TeamsParticipant.create!</code> directly.

=== Join request acceptance is race-safe ===
The join request acceptance flow is guarded using a transaction and a lock, so that capacity is checked at the time of insertion.

<syntaxhighlight lang="ruby">
# app/controllers/join_team_requests_controller.rb
ActiveRecord::Base.transaction do
team.with_lock do
raise ActiveRecord::RecordInvalid, tp if team.full?
result = team.add_member(participant)
raise ActiveRecord::RecordInvalid, tp unless result[:success]
end

@join_team_request.update!(reply_status: ACCEPTED)
render json: { message: 'Join team request accepted successfully', ... }, status: :ok
end
</syntaxhighlight>

== MentoredTeam ==
MentoredTeam mentor identification and assignment are based on participant duty:

* A mentor duty is represented by a <code>Duty</code> record with name <code>'Mentor'</code>.
* The mentor is the participant on the team whose <code>duty_id</code> equals that duty.

<syntaxhighlight lang="ruby">
# app/models/mentored_team.rb
def assign_mentor(user)
mentor_duty = Duty.find_by(name: 'Mentor')
return false unless mentor_duty

participant = AssignmentParticipant.find_by(user_id: user.id, parent_id: parent_id)
return false unless participant

participant.update(duty_id: mentor_duty.id)
end
</syntaxhighlight>

<syntaxhighlight lang="ruby">
# app/models/mentored_team.rb (mentor lookup)
AssignmentParticipant
.joins('INNER JOIN teams_participants ON teams_participants.participant_id = participants.id')
.where('teams_participants.team_id = ? AND participants.duty_id = ?', id, mentor_duty.id)
.first&.user
</syntaxhighlight>

== RSpec Test Coverage (Actual Specs in This Project) ==

=== Model Specs ===
{| class="wikitable" style="width:100%;"
|-
! Area !! Spec File(s) !! What is validated
|-
| Team validations + membership rules || <code>spec/models/team_spec.rb</code> || Presence/type validation, <code>full?</code>, <code>add_member</code>, eligibility rules
|-
| Capacity behavior || <code>spec/models/team_capacity_spec.rb</code> || Assignment capacity behavior; course teams expected to be uncapped by default
|-
| Association integrity || <code>spec/models/team_association_spec.rb</code> || Team-parent linkage and membership scoping
|-
| Conversion behavior || <code>spec/models/team_conversion_spec.rb</code> || CourseTeam ⇄ AssignmentTeam conversions and member copying
|-
| MentoredTeam duty behavior || <code>spec/models/mentored_team_spec.rb</code> || Mentor duty assignment/removal, mentor lookup by duty, capacity inheritance from AssignmentTeam
|-
| Join model constraints || <code>spec/models/teams_participant_spec.rb</code> || Uniqueness/presence validations; enrollment rules via <code>Team#add_member</code>
|}

=== Request Specs (API/Controllers) ===
{| class="wikitable" style="width:100%;"
|-
! Endpoint Area !! Spec File(s) !! What is validated
|-
| Teams API || <code>spec/requests/api/v1/teams_controller_spec.rb</code> || Index/show/members/add/remove behavior (HTTP codes + JSON shape)
|-
| JoinTeamRequests API || <code>spec/requests/api/v1/join_team_requests_controller_spec.rb</code> || Authorization rules, creating requests, accepting/declining, “team full” responses
|-
| TeamsParticipants API || <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code> || Update duty authorization, list/add/delete participant endpoints
|}

== Summary ==
This project strengthens the teams hierarchy by enforcing enrollment-based membership, preventing duplicate participation across teams, enforcing assignment team capacity with a join-model backstop, and implementing/testing MentoredTeam mentor behavior using participant duty rather than user role. Comprehensive RSpec coverage spans models, conversions, and API request behaviors.

== References ==
* Expertiza project specification — Teams hierarchy testing
* Rails Guides — Active Record Associations
* RSpec Documentation

CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing

2026-03-30T00:23:14Z

Awainga: /* Notes / Known Gaps */

CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing

2026-03-30T00:22:30Z

Awainga: /* MentoredTeam (Duty-Based Mentor) */

== About This Project ==

{| class="wikitable" style="float:right; margin-left:20px; width:320px;"
|-
! colspan="2" style="background:#cee0f2; text-align:center;" | Project Info
|-
| '''Course''' || CSC/ECE 517 Spring 2026
|-
| '''Project''' || E2610 — Teams Hierarchy Testing
|-
| '''Instructor''' || Ed Gehringer
|-
| '''Mentor''' || Vihar Manojkumar Shah
|-
| '''Collaborators''' || Atharva Waingankar, Krisha Darji, Saladin Al-Bataineh
|-
| '''Platform''' || Expertiza (Ruby on Rails)
|-
| '''Test Framework''' || RSpec
|-
| '''Root Class''' || <code>Team</code> (STI superclass)
|-
| '''Subclasses''' || <code>CourseTeam</code>, <code>AssignmentTeam</code>, <code>MentoredTeam</code>
|-
| '''Membership Join Model''' || <code>TeamsParticipant</code>

|}

The Expertiza platform organises student collaboration through a structured class hierarchy dedicated to managing teams. Teams are the unit used to reserve topics, collaborate on coursework, and submit work. This project focuses on validating the correctness of the Team hierarchy and providing thorough RSpec test coverage for team membership rules, conversions between team types, capacity enforcement, and MentoredTeam mentor logic (duty-based rather than role-based).

== Background ==

=== The Team Hierarchy ===
The hierarchy consists of exactly four classes: <code>Team</code> (superclass), <code>CourseTeam</code>, <code>AssignmentTeam</code>, and <code>MentoredTeam</code>. Teams are stored using Rails STI (single table inheritance) via the <code>type</code> column.

Two broad kinds of teams exist:

* '''Course teams''' (<code>CourseTeam</code>) — persist for the duration of an entire course and can be reused across multiple assignments.
* '''Assignment teams''' (<code>AssignmentTeam</code>) — formed for a single assignment. When mentor assignment is enabled, teams are instantiated as <code>MentoredTeam</code>, a subclass of <code>AssignmentTeam</code>.

=== Class Hierarchy Diagram ===
<pre>
┌─────────────────┐
│ Team │
│ (STI parent) │
└────────┬────────┘
│
┌─────────────────┴──────────────────┐
│ │
┌────────┴────────┐ ┌──────────┴──────────┐
│ CourseTeam │ │ AssignmentTeam │
│ (course-scoped) │ │ (assignment-scoped) │
└─────────────────┘ └──────────┬──────────┘
│
┌──────────┴──────────┐
│ MentoredTeam │
│ (mentor via duty) │
└─────────────────────┘
</pre>

=== Subclass Responsibilities ===
{| class="wikitable" style="width:100%;"
|-
! Class !! Scope !! Key Constraint !! Notes
|-
| <code>Team</code> || — || STI superclass, shared associations/logic || Holds membership helpers and core add/remove methods
|-
| <code>CourseTeam</code> || Course || Members must be course participants || Supports conversion to/from assignment teams
|-
| <code>AssignmentTeam</code> || Assignment || Members must be assignment participants || Capacity comes from <code>Assignment#max_team_size</code>
|-
| <code>MentoredTeam</code> || Assignment || Mentor identified by participant duty || Uses <code>Duty</code> + participant <code>duty_id</code>
|}

== Duty vs. Role Distinction ==
A critical design point is the separation between a user's '''role''' and their '''duty''' within a team.

{| class="wikitable" style="width:100%;"
|-
! Concept !! Definition !! Examples
|-
| '''Role''' || System-level permission level for a user account || <code>Instructor</code>, <code>Teaching Assistant</code>, <code>Student</code>
|-
| '''Duty''' || Team-level function of a participant on a specific team || <code>Submitter</code>, <code>Reviewer</code>, <code>Mentor</code>
|}

In Expertiza, mentors are not special system accounts. A mentor is a normal user whose '''participant record''' has been assigned the '''Mentor duty''' for a particular team. This project enforces and tests mentor identification by duty (not user role).

== Project Goals Implemented ==

=== Membership grounded in valid participation ===
Membership is mediated through <code>Participant</code> records:
* CourseTeam: must be a <code>CourseParticipant</code> for the same course (<code>parent_id</code>).
* AssignmentTeam / MentoredTeam: must be an <code>AssignmentParticipant</code> for the same assignment (<code>parent_id</code>).

This is enforced in <code>Team#add_member</code> by resolving the correct participant type based on the team’s subclass and the team’s <code>parent_id</code>.

<syntaxhighlight lang="ruby">
# app/models/team.rb
def add_member(participant_or_user)
participant =
if participant_or_user.is_a?(AssignmentParticipant) || participant_or_user.is_a?(CourseParticipant)
participant_or_user
elsif participant_or_user.is_a?(User)
participant_type = is_a?(AssignmentTeam) ? AssignmentParticipant : CourseParticipant
participant_type.find_by(user_id: participant_or_user.id, parent_id: parent_id)
else
nil
end

return { success: false, error: "#{participant_or_user.name} is not a participant in this #{is_a?(AssignmentTeam) ? 'assignment' : 'course'}" } if participant.nil?
return { success: false, error: "Participant already on the team" } if participants.exists?(id: participant.id)
return { success: false, error: "Unable to add participant: team is at full capacity." } if full?

team_participant = TeamsParticipant.create(
participant_id: participant.id,
team_id: id,
user_id: participant.user_id
)

team_participant.persisted? ? { success: true } : { success: false, error: team_participant.errors.full_messages.join(', ') }
end
</syntaxhighlight>

=== No user should appear on multiple teams in the same scope ===
The membership join model includes a uniqueness rule that prevents the same participant from being on multiple teams.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validates :participant_id, uniqueness: true
</syntaxhighlight>

A corresponding database migration adds a unique index on <code>participant_id</code> to make this constraint durable at the DB level.

=== Team size limits respected (capacity enforcement) ===
Capacity is enforced in two layers:

1) '''Domain-level check''': <code>Team#add_member</code> rejects when <code>full?</code> is true (returns <code>{success:false, error: ...}</code>).

2) '''Join-model backstop''': direct creation of <code>TeamsParticipant</code> is prevented if the team is already full.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validate :team_not_full, on: :create

def team_not_full
return unless team

max = team.max_size
return if max.blank?

if team.participants.count >= max
errors.add(:base, "Team is at full capacity (max #{max}).")
end
end
</syntaxhighlight>

This prevents bypassing capacity by calling <code>TeamsParticipant.create!</code> directly.

=== Join request acceptance is race-safe ===
The join request acceptance flow is guarded using a transaction and a lock, so that capacity is checked at the time of insertion.

<syntaxhighlight lang="ruby">
# app/controllers/join_team_requests_controller.rb
ActiveRecord::Base.transaction do
team.with_lock do
raise ActiveRecord::RecordInvalid, tp if team.full?
result = team.add_member(participant)
raise ActiveRecord::RecordInvalid, tp unless result[:success]
end

@join_team_request.update!(reply_status: ACCEPTED)
render json: { message: 'Join team request accepted successfully', ... }, status: :ok
end
</syntaxhighlight>

== MentoredTeam ==
MentoredTeam mentor identification and assignment are based on participant duty:

* A mentor duty is represented by a <code>Duty</code> record with name <code>'Mentor'</code>.
* The mentor is the participant on the team whose <code>duty_id</code> equals that duty.

<syntaxhighlight lang="ruby">
# app/models/mentored_team.rb
def assign_mentor(user)
mentor_duty = Duty.find_by(name: 'Mentor')
return false unless mentor_duty

participant = AssignmentParticipant.find_by(user_id: user.id, parent_id: parent_id)
return false unless participant

participant.update(duty_id: mentor_duty.id)
end
</syntaxhighlight>

<syntaxhighlight lang="ruby">
# app/models/mentored_team.rb (mentor lookup)
AssignmentParticipant
.joins('INNER JOIN teams_participants ON teams_participants.participant_id = participants.id')
.where('teams_participants.team_id = ? AND participants.duty_id = ?', id, mentor_duty.id)
.first&.user
</syntaxhighlight>

== RSpec Test Coverage (Actual Specs in This Project) ==

=== Model Specs ===
{| class="wikitable" style="width:100%;"
|-
! Area !! Spec File(s) !! What is validated
|-
| Team validations + membership rules || <code>spec/models/team_spec.rb</code> || Presence/type validation, <code>full?</code>, <code>add_member</code>, eligibility rules
|-
| Capacity behavior || <code>spec/models/team_capacity_spec.rb</code> || Assignment capacity behavior; course teams expected to be uncapped by default
|-
| Association integrity || <code>spec/models/team_association_spec.rb</code> || Team-parent linkage and membership scoping
|-
| Conversion behavior || <code>spec/models/team_conversion_spec.rb</code> || CourseTeam ⇄ AssignmentTeam conversions and member copying
|-
| MentoredTeam duty behavior || <code>spec/models/mentored_team_spec.rb</code> || Mentor duty assignment/removal, mentor lookup by duty, capacity inheritance from AssignmentTeam
|-
| Join model constraints || <code>spec/models/teams_participant_spec.rb</code> || Uniqueness/presence validations; enrollment rules via <code>Team#add_member</code>
|}

=== Request Specs (API/Controllers) ===
{| class="wikitable" style="width:100%;"
|-
! Endpoint Area !! Spec File(s) !! What is validated
|-
| Teams API || <code>spec/requests/api/v1/teams_controller_spec.rb</code> || Index/show/members/add/remove behavior (HTTP codes + JSON shape)
|-
| JoinTeamRequests API || <code>spec/requests/api/v1/join_team_requests_controller_spec.rb</code> || Authorization rules, creating requests, accepting/declining, “team full” responses
|-
| TeamsParticipants API || <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code> || Update duty authorization, list/add/delete participant endpoints
|}

== Notes / Known Gaps ==
* CourseTeam capacity is not configured in the current schema (courses do not have <code>max_team_size</code>), so capacity enforcement is defined for assignment-based teams via <code>Assignment#max_team_size</code>.
* TeamsController role-based restrictions require an explicit policy in <code>TeamsController#action_allowed?</code> to satisfy “student blocked / instructor unrestricted” criteria; the Authorization concern enforces <code>403</code> only when controllers define action rules.

== Summary ==
This project strengthens the teams hierarchy by enforcing enrollment-based membership, preventing duplicate participation across teams, enforcing assignment team capacity with a join-model backstop, and implementing/testing MentoredTeam mentor behavior using participant duty rather than user role. Comprehensive RSpec coverage spans models, conversions, and API request behaviors.

== References ==
* Expertiza project specification — Teams hierarchy testing
* Rails Guides — Active Record Associations
* RSpec Documentation

CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing

2026-03-30T00:21:33Z

Awainga: /* Duty vs. Role Distinction (Key Fix) */

== About This Project ==

{| class="wikitable" style="float:right; margin-left:20px; width:320px;"
|-
! colspan="2" style="background:#cee0f2; text-align:center;" | Project Info
|-
| '''Course''' || CSC/ECE 517 Spring 2026
|-
| '''Project''' || E2610 — Teams Hierarchy Testing
|-
| '''Instructor''' || Ed Gehringer
|-
| '''Mentor''' || Vihar Manojkumar Shah
|-
| '''Collaborators''' || Atharva Waingankar, Krisha Darji, Saladin Al-Bataineh
|-
| '''Platform''' || Expertiza (Ruby on Rails)
|-
| '''Test Framework''' || RSpec
|-
| '''Root Class''' || <code>Team</code> (STI superclass)
|-
| '''Subclasses''' || <code>CourseTeam</code>, <code>AssignmentTeam</code>, <code>MentoredTeam</code>
|-
| '''Membership Join Model''' || <code>TeamsParticipant</code>

|}

The Expertiza platform organises student collaboration through a structured class hierarchy dedicated to managing teams. Teams are the unit used to reserve topics, collaborate on coursework, and submit work. This project focuses on validating the correctness of the Team hierarchy and providing thorough RSpec test coverage for team membership rules, conversions between team types, capacity enforcement, and MentoredTeam mentor logic (duty-based rather than role-based).

== Background ==

=== The Team Hierarchy ===
The hierarchy consists of exactly four classes: <code>Team</code> (superclass), <code>CourseTeam</code>, <code>AssignmentTeam</code>, and <code>MentoredTeam</code>. Teams are stored using Rails STI (single table inheritance) via the <code>type</code> column.

Two broad kinds of teams exist:

* '''Course teams''' (<code>CourseTeam</code>) — persist for the duration of an entire course and can be reused across multiple assignments.
* '''Assignment teams''' (<code>AssignmentTeam</code>) — formed for a single assignment. When mentor assignment is enabled, teams are instantiated as <code>MentoredTeam</code>, a subclass of <code>AssignmentTeam</code>.

=== Class Hierarchy Diagram ===
<pre>
┌─────────────────┐
│ Team │
│ (STI parent) │
└────────┬────────┘
│
┌─────────────────┴──────────────────┐
│ │
┌────────┴────────┐ ┌──────────┴──────────┐
│ CourseTeam │ │ AssignmentTeam │
│ (course-scoped) │ │ (assignment-scoped) │
└─────────────────┘ └──────────┬──────────┘
│
┌──────────┴──────────┐
│ MentoredTeam │
│ (mentor via duty) │
└─────────────────────┘
</pre>

=== Subclass Responsibilities ===
{| class="wikitable" style="width:100%;"
|-
! Class !! Scope !! Key Constraint !! Notes
|-
| <code>Team</code> || — || STI superclass, shared associations/logic || Holds membership helpers and core add/remove methods
|-
| <code>CourseTeam</code> || Course || Members must be course participants || Supports conversion to/from assignment teams
|-
| <code>AssignmentTeam</code> || Assignment || Members must be assignment participants || Capacity comes from <code>Assignment#max_team_size</code>
|-
| <code>MentoredTeam</code> || Assignment || Mentor identified by participant duty || Uses <code>Duty</code> + participant <code>duty_id</code>
|}

== Duty vs. Role Distinction ==
A critical design point is the separation between a user's '''role''' and their '''duty''' within a team.

{| class="wikitable" style="width:100%;"
|-
! Concept !! Definition !! Examples
|-
| '''Role''' || System-level permission level for a user account || <code>Instructor</code>, <code>Teaching Assistant</code>, <code>Student</code>
|-
| '''Duty''' || Team-level function of a participant on a specific team || <code>Submitter</code>, <code>Reviewer</code>, <code>Mentor</code>
|}

In Expertiza, mentors are not special system accounts. A mentor is a normal user whose '''participant record''' has been assigned the '''Mentor duty''' for a particular team. This project enforces and tests mentor identification by duty (not user role).

== Project Goals Implemented ==

=== Membership grounded in valid participation ===
Membership is mediated through <code>Participant</code> records:
* CourseTeam: must be a <code>CourseParticipant</code> for the same course (<code>parent_id</code>).
* AssignmentTeam / MentoredTeam: must be an <code>AssignmentParticipant</code> for the same assignment (<code>parent_id</code>).

This is enforced in <code>Team#add_member</code> by resolving the correct participant type based on the team’s subclass and the team’s <code>parent_id</code>.

<syntaxhighlight lang="ruby">
# app/models/team.rb
def add_member(participant_or_user)
participant =
if participant_or_user.is_a?(AssignmentParticipant) || participant_or_user.is_a?(CourseParticipant)
participant_or_user
elsif participant_or_user.is_a?(User)
participant_type = is_a?(AssignmentTeam) ? AssignmentParticipant : CourseParticipant
participant_type.find_by(user_id: participant_or_user.id, parent_id: parent_id)
else
nil
end

return { success: false, error: "#{participant_or_user.name} is not a participant in this #{is_a?(AssignmentTeam) ? 'assignment' : 'course'}" } if participant.nil?
return { success: false, error: "Participant already on the team" } if participants.exists?(id: participant.id)
return { success: false, error: "Unable to add participant: team is at full capacity." } if full?

team_participant = TeamsParticipant.create(
participant_id: participant.id,
team_id: id,
user_id: participant.user_id
)

team_participant.persisted? ? { success: true } : { success: false, error: team_participant.errors.full_messages.join(', ') }
end
</syntaxhighlight>

=== No user should appear on multiple teams in the same scope ===
The membership join model includes a uniqueness rule that prevents the same participant from being on multiple teams.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validates :participant_id, uniqueness: true
</syntaxhighlight>

A corresponding database migration adds a unique index on <code>participant_id</code> to make this constraint durable at the DB level.

=== Team size limits respected (capacity enforcement) ===
Capacity is enforced in two layers:

1) '''Domain-level check''': <code>Team#add_member</code> rejects when <code>full?</code> is true (returns <code>{success:false, error: ...}</code>).

2) '''Join-model backstop''': direct creation of <code>TeamsParticipant</code> is prevented if the team is already full.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validate :team_not_full, on: :create

def team_not_full
return unless team

max = team.max_size
return if max.blank?

if team.participants.count >= max
errors.add(:base, "Team is at full capacity (max #{max}).")
end
end
</syntaxhighlight>

This prevents bypassing capacity by calling <code>TeamsParticipant.create!</code> directly.

=== Join request acceptance is race-safe ===
The join request acceptance flow is guarded using a transaction and a lock, so that capacity is checked at the time of insertion.

<syntaxhighlight lang="ruby">
# app/controllers/join_team_requests_controller.rb
ActiveRecord::Base.transaction do
team.with_lock do
raise ActiveRecord::RecordInvalid, tp if team.full?
result = team.add_member(participant)
raise ActiveRecord::RecordInvalid, tp unless result[:success]
end

@join_team_request.update!(reply_status: ACCEPTED)
render json: { message: 'Join team request accepted successfully', ... }, status: :ok
end
</syntaxhighlight>

== MentoredTeam (Duty-Based Mentor) ==
MentoredTeam mentor identification and assignment are based on participant duty:

* A mentor duty is represented by a <code>Duty</code> record with name <code>'Mentor'</code>.
* The mentor is the participant on the team whose <code>duty_id</code> equals that duty.

<syntaxhighlight lang="ruby">
# app/models/mentored_team.rb
def assign_mentor(user)
mentor_duty = Duty.find_by(name: 'Mentor')
return false unless mentor_duty

participant = AssignmentParticipant.find_by(user_id: user.id, parent_id: parent_id)
return false unless participant

participant.update(duty_id: mentor_duty.id)
end
</syntaxhighlight>

<syntaxhighlight lang="ruby">
# app/models/mentored_team.rb (mentor lookup)
AssignmentParticipant
.joins('INNER JOIN teams_participants ON teams_participants.participant_id = participants.id')
.where('teams_participants.team_id = ? AND participants.duty_id = ?', id, mentor_duty.id)
.first&.user
</syntaxhighlight>

== RSpec Test Coverage (Actual Specs in This Project) ==

=== Model Specs ===
{| class="wikitable" style="width:100%;"
|-
! Area !! Spec File(s) !! What is validated
|-
| Team validations + membership rules || <code>spec/models/team_spec.rb</code> || Presence/type validation, <code>full?</code>, <code>add_member</code>, eligibility rules
|-
| Capacity behavior || <code>spec/models/team_capacity_spec.rb</code> || Assignment capacity behavior; course teams expected to be uncapped by default
|-
| Association integrity || <code>spec/models/team_association_spec.rb</code> || Team-parent linkage and membership scoping
|-
| Conversion behavior || <code>spec/models/team_conversion_spec.rb</code> || CourseTeam ⇄ AssignmentTeam conversions and member copying
|-
| MentoredTeam duty behavior || <code>spec/models/mentored_team_spec.rb</code> || Mentor duty assignment/removal, mentor lookup by duty, capacity inheritance from AssignmentTeam
|-
| Join model constraints || <code>spec/models/teams_participant_spec.rb</code> || Uniqueness/presence validations; enrollment rules via <code>Team#add_member</code>
|}

=== Request Specs (API/Controllers) ===
{| class="wikitable" style="width:100%;"
|-
! Endpoint Area !! Spec File(s) !! What is validated
|-
| Teams API || <code>spec/requests/api/v1/teams_controller_spec.rb</code> || Index/show/members/add/remove behavior (HTTP codes + JSON shape)
|-
| JoinTeamRequests API || <code>spec/requests/api/v1/join_team_requests_controller_spec.rb</code> || Authorization rules, creating requests, accepting/declining, “team full” responses
|-
| TeamsParticipants API || <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code> || Update duty authorization, list/add/delete participant endpoints
|}

== Notes / Known Gaps ==
* CourseTeam capacity is not configured in the current schema (courses do not have <code>max_team_size</code>), so capacity enforcement is defined for assignment-based teams via <code>Assignment#max_team_size</code>.
* TeamsController role-based restrictions require an explicit policy in <code>TeamsController#action_allowed?</code> to satisfy “student blocked / instructor unrestricted” criteria; the Authorization concern enforces <code>403</code> only when controllers define action rules.

== Summary ==
This project strengthens the teams hierarchy by enforcing enrollment-based membership, preventing duplicate participation across teams, enforcing assignment team capacity with a join-model backstop, and implementing/testing MentoredTeam mentor behavior using participant duty rather than user role. Comprehensive RSpec coverage spans models, conversions, and API request behaviors.

== References ==
* Expertiza project specification — Teams hierarchy testing
* Rails Guides — Active Record Associations
* RSpec Documentation

CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing

2026-03-30T00:19:55Z

Awainga:

== About This Project ==

{| class="wikitable" style="float:right; margin-left:20px; width:320px;"
|-
! colspan="2" style="background:#cee0f2; text-align:center;" | Project Info
|-
| '''Course''' || CSC/ECE 517 Spring 2026
|-
| '''Project''' || E2610 — Teams Hierarchy Testing
|-
| '''Instructor''' || Ed Gehringer
|-
| '''Mentor''' || Vihar Manojkumar Shah
|-
| '''Collaborators''' || Atharva Waingankar, Krisha Darji, Saladin Al-Bataineh
|-
| '''Platform''' || Expertiza (Ruby on Rails)
|-
| '''Test Framework''' || RSpec
|-
| '''Root Class''' || <code>Team</code> (STI superclass)
|-
| '''Subclasses''' || <code>CourseTeam</code>, <code>AssignmentTeam</code>, <code>MentoredTeam</code>
|-
| '''Membership Join Model''' || <code>TeamsParticipant</code>

|}

The Expertiza platform organises student collaboration through a structured class hierarchy dedicated to managing teams. Teams are the unit used to reserve topics, collaborate on coursework, and submit work. This project focuses on validating the correctness of the Team hierarchy and providing thorough RSpec test coverage for team membership rules, conversions between team types, capacity enforcement, and MentoredTeam mentor logic (duty-based rather than role-based).

== Background ==

=== The Team Hierarchy ===
The hierarchy consists of exactly four classes: <code>Team</code> (superclass), <code>CourseTeam</code>, <code>AssignmentTeam</code>, and <code>MentoredTeam</code>. Teams are stored using Rails STI (single table inheritance) via the <code>type</code> column.

Two broad kinds of teams exist:

* '''Course teams''' (<code>CourseTeam</code>) — persist for the duration of an entire course and can be reused across multiple assignments.
* '''Assignment teams''' (<code>AssignmentTeam</code>) — formed for a single assignment. When mentor assignment is enabled, teams are instantiated as <code>MentoredTeam</code>, a subclass of <code>AssignmentTeam</code>.

=== Class Hierarchy Diagram ===
<pre>
┌─────────────────┐
│ Team │
│ (STI parent) │
└────────┬────────┘
│
┌─────────────────┴──────────────────┐
│ │
┌────────┴────────┐ ┌──────────┴──────────┐
│ CourseTeam │ │ AssignmentTeam │
│ (course-scoped) │ │ (assignment-scoped) │
└─────────────────┘ └──────────┬──────────┘
│
┌──────────┴──────────┐
│ MentoredTeam │
│ (mentor via duty) │
└─────────────────────┘
</pre>

=== Subclass Responsibilities ===
{| class="wikitable" style="width:100%;"
|-
! Class !! Scope !! Key Constraint !! Notes
|-
| <code>Team</code> || — || STI superclass, shared associations/logic || Holds membership helpers and core add/remove methods
|-
| <code>CourseTeam</code> || Course || Members must be course participants || Supports conversion to/from assignment teams
|-
| <code>AssignmentTeam</code> || Assignment || Members must be assignment participants || Capacity comes from <code>Assignment#max_team_size</code>
|-
| <code>MentoredTeam</code> || Assignment || Mentor identified by participant duty || Uses <code>Duty</code> + participant <code>duty_id</code>
|}

== Duty vs. Role Distinction (Key Fix) ==
A critical design point is the separation between a user's '''role''' and their '''duty''' within a team.

{| class="wikitable" style="width:100%;"
|-
! Concept !! Definition !! Examples
|-
| '''Role''' || System-level permission level for a user account || <code>Instructor</code>, <code>Teaching Assistant</code>, <code>Student</code>
|-
| '''Duty''' || Team-level function of a participant on a specific team || <code>Submitter</code>, <code>Reviewer</code>, <code>Mentor</code>
|}

In Expertiza, mentors are not special system accounts. A mentor is a normal user whose '''participant record''' has been assigned the '''Mentor duty''' for a particular team. This project enforces and tests mentor identification by duty (not user role).

== Project Goals Implemented ==

=== Membership grounded in valid participation ===
Membership is mediated through <code>Participant</code> records:
* CourseTeam: must be a <code>CourseParticipant</code> for the same course (<code>parent_id</code>).
* AssignmentTeam / MentoredTeam: must be an <code>AssignmentParticipant</code> for the same assignment (<code>parent_id</code>).

This is enforced in <code>Team#add_member</code> by resolving the correct participant type based on the team’s subclass and the team’s <code>parent_id</code>.

<syntaxhighlight lang="ruby">
# app/models/team.rb
def add_member(participant_or_user)
participant =
if participant_or_user.is_a?(AssignmentParticipant) || participant_or_user.is_a?(CourseParticipant)
participant_or_user
elsif participant_or_user.is_a?(User)
participant_type = is_a?(AssignmentTeam) ? AssignmentParticipant : CourseParticipant
participant_type.find_by(user_id: participant_or_user.id, parent_id: parent_id)
else
nil
end

return { success: false, error: "#{participant_or_user.name} is not a participant in this #{is_a?(AssignmentTeam) ? 'assignment' : 'course'}" } if participant.nil?
return { success: false, error: "Participant already on the team" } if participants.exists?(id: participant.id)
return { success: false, error: "Unable to add participant: team is at full capacity." } if full?

team_participant = TeamsParticipant.create(
participant_id: participant.id,
team_id: id,
user_id: participant.user_id
)

team_participant.persisted? ? { success: true } : { success: false, error: team_participant.errors.full_messages.join(', ') }
end
</syntaxhighlight>

=== No user should appear on multiple teams in the same scope ===
The membership join model includes a uniqueness rule that prevents the same participant from being on multiple teams.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validates :participant_id, uniqueness: true
</syntaxhighlight>

A corresponding database migration adds a unique index on <code>participant_id</code> to make this constraint durable at the DB level.

=== Team size limits respected (capacity enforcement) ===
Capacity is enforced in two layers:

1) '''Domain-level check''': <code>Team#add_member</code> rejects when <code>full?</code> is true (returns <code>{success:false, error: ...}</code>).

2) '''Join-model backstop''': direct creation of <code>TeamsParticipant</code> is prevented if the team is already full.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validate :team_not_full, on: :create

def team_not_full
return unless team

max = team.max_size
return if max.blank?

if team.participants.count >= max
errors.add(:base, "Team is at full capacity (max #{max}).")
end
end
</syntaxhighlight>

This prevents bypassing capacity by calling <code>TeamsParticipant.create!</code> directly.

=== Join request acceptance is race-safe ===
The join request acceptance flow is guarded using a transaction and a lock, so that capacity is checked at the time of insertion.

<syntaxhighlight lang="ruby">
# app/controllers/join_team_requests_controller.rb
ActiveRecord::Base.transaction do
team.with_lock do
raise ActiveRecord::RecordInvalid, tp if team.full?
result = team.add_member(participant)
raise ActiveRecord::RecordInvalid, tp unless result[:success]
end

@join_team_request.update!(reply_status: ACCEPTED)
render json: { message: 'Join team request accepted successfully', ... }, status: :ok
end
</syntaxhighlight>

== MentoredTeam (Duty-Based Mentor) ==
MentoredTeam mentor identification and assignment are based on participant duty:

* A mentor duty is represented by a <code>Duty</code> record with name <code>'Mentor'</code>.
* The mentor is the participant on the team whose <code>duty_id</code> equals that duty.

<syntaxhighlight lang="ruby">
# app/models/mentored_team.rb
def assign_mentor(user)
mentor_duty = Duty.find_by(name: 'Mentor')
return false unless mentor_duty

participant = AssignmentParticipant.find_by(user_id: user.id, parent_id: parent_id)
return false unless participant

participant.update(duty_id: mentor_duty.id)
end
</syntaxhighlight>

<syntaxhighlight lang="ruby">
# app/models/mentored_team.rb (mentor lookup)
AssignmentParticipant
.joins('INNER JOIN teams_participants ON teams_participants.participant_id = participants.id')
.where('teams_participants.team_id = ? AND participants.duty_id = ?', id, mentor_duty.id)
.first&.user
</syntaxhighlight>

== RSpec Test Coverage (Actual Specs in This Project) ==

=== Model Specs ===
{| class="wikitable" style="width:100%;"
|-
! Area !! Spec File(s) !! What is validated
|-
| Team validations + membership rules || <code>spec/models/team_spec.rb</code> || Presence/type validation, <code>full?</code>, <code>add_member</code>, eligibility rules
|-
| Capacity behavior || <code>spec/models/team_capacity_spec.rb</code> || Assignment capacity behavior; course teams expected to be uncapped by default
|-
| Association integrity || <code>spec/models/team_association_spec.rb</code> || Team-parent linkage and membership scoping
|-
| Conversion behavior || <code>spec/models/team_conversion_spec.rb</code> || CourseTeam ⇄ AssignmentTeam conversions and member copying
|-
| MentoredTeam duty behavior || <code>spec/models/mentored_team_spec.rb</code> || Mentor duty assignment/removal, mentor lookup by duty, capacity inheritance from AssignmentTeam
|-
| Join model constraints || <code>spec/models/teams_participant_spec.rb</code> || Uniqueness/presence validations; enrollment rules via <code>Team#add_member</code>
|}

=== Request Specs (API/Controllers) ===
{| class="wikitable" style="width:100%;"
|-
! Endpoint Area !! Spec File(s) !! What is validated
|-
| Teams API || <code>spec/requests/api/v1/teams_controller_spec.rb</code> || Index/show/members/add/remove behavior (HTTP codes + JSON shape)
|-
| JoinTeamRequests API || <code>spec/requests/api/v1/join_team_requests_controller_spec.rb</code> || Authorization rules, creating requests, accepting/declining, “team full” responses
|-
| TeamsParticipants API || <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code> || Update duty authorization, list/add/delete participant endpoints
|}

== Notes / Known Gaps ==
* CourseTeam capacity is not configured in the current schema (courses do not have <code>max_team_size</code>), so capacity enforcement is defined for assignment-based teams via <code>Assignment#max_team_size</code>.
* TeamsController role-based restrictions require an explicit policy in <code>TeamsController#action_allowed?</code> to satisfy “student blocked / instructor unrestricted” criteria; the Authorization concern enforces <code>403</code> only when controllers define action rules.

== Summary ==
This project strengthens the teams hierarchy by enforcing enrollment-based membership, preventing duplicate participation across teams, enforcing assignment team capacity with a join-model backstop, and implementing/testing MentoredTeam mentor behavior using participant duty rather than user role. Comprehensive RSpec coverage spans models, conversions, and API request behaviors.

== References ==
* Expertiza project specification — Teams hierarchy testing
* Rails Guides — Active Record Associations
* RSpec Documentation

CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing

2026-03-30T00:18:57Z

Awainga:

== About This Project ==

{| class="wikitable" style="float:right; margin-left:20px; width:320px;"
|-
! colspan="2" style="background:#cee0f2; text-align:center;" | Project Info
|-
| '''Course''' || CSC/ECE 517 Spring 2026
|-
| '''Project''' || E2610 — Teams Hierarchy Testing
|-
| '''Instructor''' || Ed Gehringer
|-
| '''Mentor''' || Vihar Manojkumar Shah
|-
| '''Collaborators''' || Atharva Waingankar,
Krisha Darji,
Saladin Al-Bataineh
|-
| '''Platform''' || Expertiza (Ruby on Rails)
|-
| '''Test Framework''' || RSpec
|-
| '''Root Class''' || <code>Team</code> (STI superclass)
|-
| '''Subclasses''' || <code>CourseTeam</code>, <code>AssignmentTeam</code>, <code>MentoredTeam</code>
|-
| '''Membership Join Model''' || <code>TeamsParticipant</code>

|}

The Expertiza platform organises student collaboration through a structured class hierarchy dedicated to managing teams. Teams are the unit used to reserve topics, collaborate on coursework, and submit work. This project focuses on validating the correctness of the Team hierarchy and providing thorough RSpec test coverage for team membership rules, conversions between team types, capacity enforcement, and MentoredTeam mentor logic (duty-based rather than role-based).

== Background ==

=== The Team Hierarchy ===
The hierarchy consists of exactly four classes: <code>Team</code> (superclass), <code>CourseTeam</code>, <code>AssignmentTeam</code>, and <code>MentoredTeam</code>. Teams are stored using Rails STI (single table inheritance) via the <code>type</code> column.

Two broad kinds of teams exist:

* '''Course teams''' (<code>CourseTeam</code>) — persist for the duration of an entire course and can be reused across multiple assignments.
* '''Assignment teams''' (<code>AssignmentTeam</code>) — formed for a single assignment. When mentor assignment is enabled, teams are instantiated as <code>MentoredTeam</code>, a subclass of <code>AssignmentTeam</code>.

=== Class Hierarchy Diagram ===
<pre>
┌─────────────────┐
│ Team │
│ (STI parent) │
└────────┬────────┘
│
┌─────────────────┴──────────────────┐
│ │
┌────────┴────────┐ ┌──────────┴──────────┐
│ CourseTeam │ │ AssignmentTeam │
│ (course-scoped) │ │ (assignment-scoped) │
└─────────────────┘ └──────────┬──────────┘
│
┌──────────┴──────────┐
│ MentoredTeam │
│ (mentor via duty) │
└─────────────────────┘
</pre>

=== Subclass Responsibilities ===
{| class="wikitable" style="width:100%;"
|-
! Class !! Scope !! Key Constraint !! Notes
|-
| <code>Team</code> || — || STI superclass, shared associations/logic || Holds membership helpers and core add/remove methods
|-
| <code>CourseTeam</code> || Course || Members must be course participants || Supports conversion to/from assignment teams
|-
| <code>AssignmentTeam</code> || Assignment || Members must be assignment participants || Capacity comes from <code>Assignment#max_team_size</code>
|-
| <code>MentoredTeam</code> || Assignment || Mentor identified by participant duty || Uses <code>Duty</code> + participant <code>duty_id</code>
|}

== Duty vs. Role Distinction (Key Fix) ==
A critical design point is the separation between a user's '''role''' and their '''duty''' within a team.

{| class="wikitable" style="width:100%;"
|-
! Concept !! Definition !! Examples
|-
| '''Role''' || System-level permission level for a user account || <code>Instructor</code>, <code>Teaching Assistant</code>, <code>Student</code>
|-
| '''Duty''' || Team-level function of a participant on a specific team || <code>Submitter</code>, <code>Reviewer</code>, <code>Mentor</code>
|}

In Expertiza, mentors are not special system accounts. A mentor is a normal user whose '''participant record''' has been assigned the '''Mentor duty''' for a particular team. This project enforces and tests mentor identification by duty (not user role).

== Project Goals Implemented ==

=== Membership grounded in valid participation ===
Membership is mediated through <code>Participant</code> records:
* CourseTeam: must be a <code>CourseParticipant</code> for the same course (<code>parent_id</code>).
* AssignmentTeam / MentoredTeam: must be an <code>AssignmentParticipant</code> for the same assignment (<code>parent_id</code>).

This is enforced in <code>Team#add_member</code> by resolving the correct participant type based on the team’s subclass and the team’s <code>parent_id</code>.

<syntaxhighlight lang="ruby">
# app/models/team.rb
def add_member(participant_or_user)
participant =
if participant_or_user.is_a?(AssignmentParticipant) || participant_or_user.is_a?(CourseParticipant)
participant_or_user
elsif participant_or_user.is_a?(User)
participant_type = is_a?(AssignmentTeam) ? AssignmentParticipant : CourseParticipant
participant_type.find_by(user_id: participant_or_user.id, parent_id: parent_id)
else
nil
end

return { success: false, error: "#{participant_or_user.name} is not a participant in this #{is_a?(AssignmentTeam) ? 'assignment' : 'course'}" } if participant.nil?
return { success: false, error: "Participant already on the team" } if participants.exists?(id: participant.id)
return { success: false, error: "Unable to add participant: team is at full capacity." } if full?

team_participant = TeamsParticipant.create(
participant_id: participant.id,
team_id: id,
user_id: participant.user_id
)

team_participant.persisted? ? { success: true } : { success: false, error: team_participant.errors.full_messages.join(', ') }
end
</syntaxhighlight>

=== No user should appear on multiple teams in the same scope ===
The membership join model includes a uniqueness rule that prevents the same participant from being on multiple teams.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validates :participant_id, uniqueness: true
</syntaxhighlight>

A corresponding database migration adds a unique index on <code>participant_id</code> to make this constraint durable at the DB level.

=== Team size limits respected (capacity enforcement) ===
Capacity is enforced in two layers:

1) '''Domain-level check''': <code>Team#add_member</code> rejects when <code>full?</code> is true (returns <code>{success:false, error: ...}</code>).

2) '''Join-model backstop''': direct creation of <code>TeamsParticipant</code> is prevented if the team is already full.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validate :team_not_full, on: :create

def team_not_full
return unless team

max = team.max_size
return if max.blank?

if team.participants.count >= max
errors.add(:base, "Team is at full capacity (max #{max}).")
end
end
</syntaxhighlight>

This prevents bypassing capacity by calling <code>TeamsParticipant.create!</code> directly.

=== Join request acceptance is race-safe ===
The join request acceptance flow is guarded using a transaction and a lock, so that capacity is checked at the time of insertion.

<syntaxhighlight lang="ruby">
# app/controllers/join_team_requests_controller.rb
ActiveRecord::Base.transaction do
team.with_lock do
raise ActiveRecord::RecordInvalid, tp if team.full?
result = team.add_member(participant)
raise ActiveRecord::RecordInvalid, tp unless result[:success]
end

@join_team_request.update!(reply_status: ACCEPTED)
render json: { message: 'Join team request accepted successfully', ... }, status: :ok
end
</syntaxhighlight>

== MentoredTeam (Duty-Based Mentor) ==
MentoredTeam mentor identification and assignment are based on participant duty:

* A mentor duty is represented by a <code>Duty</code> record with name <code>'Mentor'</code>.
* The mentor is the participant on the team whose <code>duty_id</code> equals that duty.

<syntaxhighlight lang="ruby">
# app/models/mentored_team.rb
def assign_mentor(user)
mentor_duty = Duty.find_by(name: 'Mentor')
return false unless mentor_duty

participant = AssignmentParticipant.find_by(user_id: user.id, parent_id: parent_id)
return false unless participant

participant.update(duty_id: mentor_duty.id)
end
</syntaxhighlight>

<syntaxhighlight lang="ruby">
# app/models/mentored_team.rb (mentor lookup)
AssignmentParticipant
.joins('INNER JOIN teams_participants ON teams_participants.participant_id = participants.id')
.where('teams_participants.team_id = ? AND participants.duty_id = ?', id, mentor_duty.id)
.first&.user
</syntaxhighlight>

== RSpec Test Coverage (Actual Specs in This Project) ==

=== Model Specs ===
{| class="wikitable" style="width:100%;"
|-
! Area !! Spec File(s) !! What is validated
|-
| Team validations + membership rules || <code>spec/models/team_spec.rb</code> || Presence/type validation, <code>full?</code>, <code>add_member</code>, eligibility rules
|-
| Capacity behavior || <code>spec/models/team_capacity_spec.rb</code> || Assignment capacity behavior; course teams expected to be uncapped by default
|-
| Association integrity || <code>spec/models/team_association_spec.rb</code> || Team-parent linkage and membership scoping
|-
| Conversion behavior || <code>spec/models/team_conversion_spec.rb</code> || CourseTeam ⇄ AssignmentTeam conversions and member copying
|-
| MentoredTeam duty behavior || <code>spec/models/mentored_team_spec.rb</code> || Mentor duty assignment/removal, mentor lookup by duty, capacity inheritance from AssignmentTeam
|-
| Join model constraints || <code>spec/models/teams_participant_spec.rb</code> || Uniqueness/presence validations; enrollment rules via <code>Team#add_member</code>
|}

=== Request Specs (API/Controllers) ===
{| class="wikitable" style="width:100%;"
|-
! Endpoint Area !! Spec File(s) !! What is validated
|-
| Teams API || <code>spec/requests/api/v1/teams_controller_spec.rb</code> || Index/show/members/add/remove behavior (HTTP codes + JSON shape)
|-
| JoinTeamRequests API || <code>spec/requests/api/v1/join_team_requests_controller_spec.rb</code> || Authorization rules, creating requests, accepting/declining, “team full” responses
|-
| TeamsParticipants API || <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code> || Update duty authorization, list/add/delete participant endpoints
|}

== Notes / Known Gaps ==
* CourseTeam capacity is not configured in the current schema (courses do not have <code>max_team_size</code>), so capacity enforcement is defined for assignment-based teams via <code>Assignment#max_team_size</code>.
* TeamsController role-based restrictions require an explicit policy in <code>TeamsController#action_allowed?</code> to satisfy “student blocked / instructor unrestricted” criteria; the Authorization concern enforces <code>403</code> only when controllers define action rules.

== Summary ==
This project strengthens the teams hierarchy by enforcing enrollment-based membership, preventing duplicate participation across teams, enforcing assignment team capacity with a join-model backstop, and implementing/testing MentoredTeam mentor behavior using participant duty rather than user role. Comprehensive RSpec coverage spans models, conversions, and API request behaviors.

== References ==
* Expertiza project specification — Teams hierarchy testing
* Rails Guides — Active Record Associations
* RSpec Documentation

CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing

2026-03-30T00:16:04Z

Awainga:

== About This Project ==

{| class="wikitable" style="float:right; margin-left:20px; width:320px;"
|-
! colspan="2" style="background:#cee0f2; text-align:center;" | Project Info
|-
| '''Course''' || CSC/ECE 517 Spring 2026
|-
| '''Project''' || E2610 — Teams Hierarchy Testing
|-
| '''Mentor''' || Vihar Manojkumar Shah
|-
| '''Platform''' || Expertiza (Ruby on Rails)
|-
| '''Test Framework''' || RSpec
|-
| '''Root Class''' || <code>Team</code> (STI superclass)
|-
| '''Subclasses''' || <code>CourseTeam</code>, <code>AssignmentTeam</code>, <code>MentoredTeam</code>
|-
| '''Membership Join Model''' || <code>TeamsParticipant</code>
|-
| '''Collaborators''' || <code>Atharva, Krisha, Saladin</code>

|}

The Expertiza platform organises student collaboration through a structured class hierarchy dedicated to managing teams. Teams are the unit used to reserve topics, collaborate on coursework, and submit work. This project focuses on validating the correctness of the Team hierarchy and providing thorough RSpec test coverage for team membership rules, conversions between team types, capacity enforcement, and MentoredTeam mentor logic (duty-based rather than role-based).

== Background ==

=== The Team Hierarchy ===
The hierarchy consists of exactly four classes: <code>Team</code> (superclass), <code>CourseTeam</code>, <code>AssignmentTeam</code>, and <code>MentoredTeam</code>. Teams are stored using Rails STI (single table inheritance) via the <code>type</code> column.

Two broad kinds of teams exist:

* '''Course teams''' (<code>CourseTeam</code>) — persist for the duration of an entire course and can be reused across multiple assignments.
* '''Assignment teams''' (<code>AssignmentTeam</code>) — formed for a single assignment. When mentor assignment is enabled, teams are instantiated as <code>MentoredTeam</code>, a subclass of <code>AssignmentTeam</code>.

=== Class Hierarchy Diagram ===
<pre>
┌─────────────────┐
│ Team │
│ (STI parent) │
└────────┬────────┘
│
┌─────────────────┴──────────────────┐
│ │
┌────────┴────────┐ ┌──────────┴──────────┐
│ CourseTeam │ │ AssignmentTeam │
│ (course-scoped) │ │ (assignment-scoped) │
└─────────────────┘ └──────────┬──────────┘
│
┌──────────┴──────────┐
│ MentoredTeam │
│ (mentor via duty) │
└─────────────────────┘
</pre>

=== Subclass Responsibilities ===
{| class="wikitable" style="width:100%;"
|-
! Class !! Scope !! Key Constraint !! Notes
|-
| <code>Team</code> || — || STI superclass, shared associations/logic || Holds membership helpers and core add/remove methods
|-
| <code>CourseTeam</code> || Course || Members must be course participants || Supports conversion to/from assignment teams
|-
| <code>AssignmentTeam</code> || Assignment || Members must be assignment participants || Capacity comes from <code>Assignment#max_team_size</code>
|-
| <code>MentoredTeam</code> || Assignment || Mentor identified by participant duty || Uses <code>Duty</code> + participant <code>duty_id</code>
|}

== Duty vs. Role Distinction (Key Fix) ==
A critical design point is the separation between a user's '''role''' and their '''duty''' within a team.

{| class="wikitable" style="width:100%;"
|-
! Concept !! Definition !! Examples
|-
| '''Role''' || System-level permission level for a user account || <code>Instructor</code>, <code>Teaching Assistant</code>, <code>Student</code>
|-
| '''Duty''' || Team-level function of a participant on a specific team || <code>Submitter</code>, <code>Reviewer</code>, <code>Mentor</code>
|}

In Expertiza, mentors are not special system accounts. A mentor is a normal user whose '''participant record''' has been assigned the '''Mentor duty''' for a particular team. This project enforces and tests mentor identification by duty (not user role).

== Project Goals Implemented ==

=== Membership grounded in valid participation ===
Membership is mediated through <code>Participant</code> records:
* CourseTeam: must be a <code>CourseParticipant</code> for the same course (<code>parent_id</code>).
* AssignmentTeam / MentoredTeam: must be an <code>AssignmentParticipant</code> for the same assignment (<code>parent_id</code>).

This is enforced in <code>Team#add_member</code> by resolving the correct participant type based on the team’s subclass and the team’s <code>parent_id</code>.

<syntaxhighlight lang="ruby">
# app/models/team.rb
def add_member(participant_or_user)
participant =
if participant_or_user.is_a?(AssignmentParticipant) || participant_or_user.is_a?(CourseParticipant)
participant_or_user
elsif participant_or_user.is_a?(User)
participant_type = is_a?(AssignmentTeam) ? AssignmentParticipant : CourseParticipant
participant_type.find_by(user_id: participant_or_user.id, parent_id: parent_id)
else
nil
end

return { success: false, error: "#{participant_or_user.name} is not a participant in this #{is_a?(AssignmentTeam) ? 'assignment' : 'course'}" } if participant.nil?
return { success: false, error: "Participant already on the team" } if participants.exists?(id: participant.id)
return { success: false, error: "Unable to add participant: team is at full capacity." } if full?

team_participant = TeamsParticipant.create(
participant_id: participant.id,
team_id: id,
user_id: participant.user_id
)

team_participant.persisted? ? { success: true } : { success: false, error: team_participant.errors.full_messages.join(', ') }
end
</syntaxhighlight>

=== No user should appear on multiple teams in the same scope ===
The membership join model includes a uniqueness rule that prevents the same participant from being on multiple teams.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validates :participant_id, uniqueness: true
</syntaxhighlight>

A corresponding database migration adds a unique index on <code>participant_id</code> to make this constraint durable at the DB level.

=== Team size limits respected (capacity enforcement) ===
Capacity is enforced in two layers:

1) '''Domain-level check''': <code>Team#add_member</code> rejects when <code>full?</code> is true (returns <code>{success:false, error: ...}</code>).

2) '''Join-model backstop''': direct creation of <code>TeamsParticipant</code> is prevented if the team is already full.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validate :team_not_full, on: :create

def team_not_full
return unless team

max = team.max_size
return if max.blank?

if team.participants.count >= max
errors.add(:base, "Team is at full capacity (max #{max}).")
end
end
</syntaxhighlight>

This prevents bypassing capacity by calling <code>TeamsParticipant.create!</code> directly.

=== Join request acceptance is race-safe ===
The join request acceptance flow is guarded using a transaction and a lock, so that capacity is checked at the time of insertion.

<syntaxhighlight lang="ruby">
# app/controllers/join_team_requests_controller.rb
ActiveRecord::Base.transaction do
team.with_lock do
raise ActiveRecord::RecordInvalid, tp if team.full?
result = team.add_member(participant)
raise ActiveRecord::RecordInvalid, tp unless result[:success]
end

@join_team_request.update!(reply_status: ACCEPTED)
render json: { message: 'Join team request accepted successfully', ... }, status: :ok
end
</syntaxhighlight>

== MentoredTeam (Duty-Based Mentor) ==
MentoredTeam mentor identification and assignment are based on participant duty:

* A mentor duty is represented by a <code>Duty</code> record with name <code>'Mentor'</code>.
* The mentor is the participant on the team whose <code>duty_id</code> equals that duty.

<syntaxhighlight lang="ruby">
# app/models/mentored_team.rb
def assign_mentor(user)
mentor_duty = Duty.find_by(name: 'Mentor')
return false unless mentor_duty

participant = AssignmentParticipant.find_by(user_id: user.id, parent_id: parent_id)
return false unless participant

participant.update(duty_id: mentor_duty.id)
end
</syntaxhighlight>

<syntaxhighlight lang="ruby">
# app/models/mentored_team.rb (mentor lookup)
AssignmentParticipant
.joins('INNER JOIN teams_participants ON teams_participants.participant_id = participants.id')
.where('teams_participants.team_id = ? AND participants.duty_id = ?', id, mentor_duty.id)
.first&.user
</syntaxhighlight>

== RSpec Test Coverage (Actual Specs in This Project) ==

=== Model Specs ===
{| class="wikitable" style="width:100%;"
|-
! Area !! Spec File(s) !! What is validated
|-
| Team validations + membership rules || <code>spec/models/team_spec.rb</code> || Presence/type validation, <code>full?</code>, <code>add_member</code>, eligibility rules
|-
| Capacity behavior || <code>spec/models/team_capacity_spec.rb</code> || Assignment capacity behavior; course teams expected to be uncapped by default
|-
| Association integrity || <code>spec/models/team_association_spec.rb</code> || Team-parent linkage and membership scoping
|-
| Conversion behavior || <code>spec/models/team_conversion_spec.rb</code> || CourseTeam ⇄ AssignmentTeam conversions and member copying
|-
| MentoredTeam duty behavior || <code>spec/models/mentored_team_spec.rb</code> || Mentor duty assignment/removal, mentor lookup by duty, capacity inheritance from AssignmentTeam
|-
| Join model constraints || <code>spec/models/teams_participant_spec.rb</code> || Uniqueness/presence validations; enrollment rules via <code>Team#add_member</code>
|}

=== Request Specs (API/Controllers) ===
{| class="wikitable" style="width:100%;"
|-
! Endpoint Area !! Spec File(s) !! What is validated
|-
| Teams API || <code>spec/requests/api/v1/teams_controller_spec.rb</code> || Index/show/members/add/remove behavior (HTTP codes + JSON shape)
|-
| JoinTeamRequests API || <code>spec/requests/api/v1/join_team_requests_controller_spec.rb</code> || Authorization rules, creating requests, accepting/declining, “team full” responses
|-
| TeamsParticipants API || <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code> || Update duty authorization, list/add/delete participant endpoints
|}

== Notes / Known Gaps ==
* CourseTeam capacity is not configured in the current schema (courses do not have <code>max_team_size</code>), so capacity enforcement is defined for assignment-based teams via <code>Assignment#max_team_size</code>.
* TeamsController role-based restrictions require an explicit policy in <code>TeamsController#action_allowed?</code> to satisfy “student blocked / instructor unrestricted” criteria; the Authorization concern enforces <code>403</code> only when controllers define action rules.

== Summary ==
This project strengthens the teams hierarchy by enforcing enrollment-based membership, preventing duplicate participation across teams, enforcing assignment team capacity with a join-model backstop, and implementing/testing MentoredTeam mentor behavior using participant duty rather than user role. Comprehensive RSpec coverage spans models, conversions, and API request behaviors.

== References ==
* Expertiza project specification — Teams hierarchy testing
* Rails Guides — Active Record Associations
* RSpec Documentation

CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing

2026-03-30T00:15:29Z

Awainga:

== About This Project ==

{| class="wikitable" style="float:right; margin-left:20px; width:320px;"
|-
! colspan="2" style="background:#cee0f2; text-align:center;" | Project Info
|-
| '''Course''' || CSC/ECE 517 Spring 2026
|-
| '''Project''' || E2610 — Teams Hierarchy Testing
|-
| '''Mentor''' || Vihar Manojkumar Shah
|-
| '''Platform''' || Expertiza (Ruby on Rails)
|-
| '''Test Framework''' || RSpec
|-
| '''Root Class''' || <code>Team</code> (STI superclass)
|-
| '''Subclasses''' || <code>CourseTeam</code>, <code>AssignmentTeam</code>, <code>MentoredTeam</code>
|-
| '''Membership Join Model''' || <code>TeamsParticipant</code>
| '''Collaborators''' || <code>Atharva, Krisha, Saladin</code>

|}

The Expertiza platform organises student collaboration through a structured class hierarchy dedicated to managing teams. Teams are the unit used to reserve topics, collaborate on coursework, and submit work. This project focuses on validating the correctness of the Team hierarchy and providing thorough RSpec test coverage for team membership rules, conversions between team types, capacity enforcement, and MentoredTeam mentor logic (duty-based rather than role-based).

== Background ==

=== The Team Hierarchy ===
The hierarchy consists of exactly four classes: <code>Team</code> (superclass), <code>CourseTeam</code>, <code>AssignmentTeam</code>, and <code>MentoredTeam</code>. Teams are stored using Rails STI (single table inheritance) via the <code>type</code> column.

Two broad kinds of teams exist:

* '''Course teams''' (<code>CourseTeam</code>) — persist for the duration of an entire course and can be reused across multiple assignments.
* '''Assignment teams''' (<code>AssignmentTeam</code>) — formed for a single assignment. When mentor assignment is enabled, teams are instantiated as <code>MentoredTeam</code>, a subclass of <code>AssignmentTeam</code>.

=== Class Hierarchy Diagram ===
<pre>
┌─────────────────┐
│ Team │
│ (STI parent) │
└────────┬────────┘
│
┌─────────────────┴──────────────────┐
│ │
┌────────┴────────┐ ┌──────────┴──────────┐
│ CourseTeam │ │ AssignmentTeam │
│ (course-scoped) │ │ (assignment-scoped) │
└─────────────────┘ └──────────┬──────────┘
│
┌──────────┴──────────┐
│ MentoredTeam │
│ (mentor via duty) │
└─────────────────────┘
</pre>

=== Subclass Responsibilities ===
{| class="wikitable" style="width:100%;"
|-
! Class !! Scope !! Key Constraint !! Notes
|-
| <code>Team</code> || — || STI superclass, shared associations/logic || Holds membership helpers and core add/remove methods
|-
| <code>CourseTeam</code> || Course || Members must be course participants || Supports conversion to/from assignment teams
|-
| <code>AssignmentTeam</code> || Assignment || Members must be assignment participants || Capacity comes from <code>Assignment#max_team_size</code>
|-
| <code>MentoredTeam</code> || Assignment || Mentor identified by participant duty || Uses <code>Duty</code> + participant <code>duty_id</code>
|}

== Duty vs. Role Distinction (Key Fix) ==
A critical design point is the separation between a user's '''role''' and their '''duty''' within a team.

{| class="wikitable" style="width:100%;"
|-
! Concept !! Definition !! Examples
|-
| '''Role''' || System-level permission level for a user account || <code>Instructor</code>, <code>Teaching Assistant</code>, <code>Student</code>
|-
| '''Duty''' || Team-level function of a participant on a specific team || <code>Submitter</code>, <code>Reviewer</code>, <code>Mentor</code>
|}

In Expertiza, mentors are not special system accounts. A mentor is a normal user whose '''participant record''' has been assigned the '''Mentor duty''' for a particular team. This project enforces and tests mentor identification by duty (not user role).

== Project Goals Implemented ==

=== Membership grounded in valid participation ===
Membership is mediated through <code>Participant</code> records:
* CourseTeam: must be a <code>CourseParticipant</code> for the same course (<code>parent_id</code>).
* AssignmentTeam / MentoredTeam: must be an <code>AssignmentParticipant</code> for the same assignment (<code>parent_id</code>).

This is enforced in <code>Team#add_member</code> by resolving the correct participant type based on the team’s subclass and the team’s <code>parent_id</code>.

<syntaxhighlight lang="ruby">
# app/models/team.rb
def add_member(participant_or_user)
participant =
if participant_or_user.is_a?(AssignmentParticipant) || participant_or_user.is_a?(CourseParticipant)
participant_or_user
elsif participant_or_user.is_a?(User)
participant_type = is_a?(AssignmentTeam) ? AssignmentParticipant : CourseParticipant
participant_type.find_by(user_id: participant_or_user.id, parent_id: parent_id)
else
nil
end

return { success: false, error: "#{participant_or_user.name} is not a participant in this #{is_a?(AssignmentTeam) ? 'assignment' : 'course'}" } if participant.nil?
return { success: false, error: "Participant already on the team" } if participants.exists?(id: participant.id)
return { success: false, error: "Unable to add participant: team is at full capacity." } if full?

team_participant = TeamsParticipant.create(
participant_id: participant.id,
team_id: id,
user_id: participant.user_id
)

team_participant.persisted? ? { success: true } : { success: false, error: team_participant.errors.full_messages.join(', ') }
end
</syntaxhighlight>

=== No user should appear on multiple teams in the same scope ===
The membership join model includes a uniqueness rule that prevents the same participant from being on multiple teams.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validates :participant_id, uniqueness: true
</syntaxhighlight>

A corresponding database migration adds a unique index on <code>participant_id</code> to make this constraint durable at the DB level.

=== Team size limits respected (capacity enforcement) ===
Capacity is enforced in two layers:

1) '''Domain-level check''': <code>Team#add_member</code> rejects when <code>full?</code> is true (returns <code>{success:false, error: ...}</code>).

2) '''Join-model backstop''': direct creation of <code>TeamsParticipant</code> is prevented if the team is already full.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validate :team_not_full, on: :create

def team_not_full
return unless team

max = team.max_size
return if max.blank?

if team.participants.count >= max
errors.add(:base, "Team is at full capacity (max #{max}).")
end
end
</syntaxhighlight>

This prevents bypassing capacity by calling <code>TeamsParticipant.create!</code> directly.

=== Join request acceptance is race-safe ===
The join request acceptance flow is guarded using a transaction and a lock, so that capacity is checked at the time of insertion.

<syntaxhighlight lang="ruby">
# app/controllers/join_team_requests_controller.rb
ActiveRecord::Base.transaction do
team.with_lock do
raise ActiveRecord::RecordInvalid, tp if team.full?
result = team.add_member(participant)
raise ActiveRecord::RecordInvalid, tp unless result[:success]
end

@join_team_request.update!(reply_status: ACCEPTED)
render json: { message: 'Join team request accepted successfully', ... }, status: :ok
end
</syntaxhighlight>

== MentoredTeam (Duty-Based Mentor) ==
MentoredTeam mentor identification and assignment are based on participant duty:

* A mentor duty is represented by a <code>Duty</code> record with name <code>'Mentor'</code>.
* The mentor is the participant on the team whose <code>duty_id</code> equals that duty.

<syntaxhighlight lang="ruby">
# app/models/mentored_team.rb
def assign_mentor(user)
mentor_duty = Duty.find_by(name: 'Mentor')
return false unless mentor_duty

participant = AssignmentParticipant.find_by(user_id: user.id, parent_id: parent_id)
return false unless participant

participant.update(duty_id: mentor_duty.id)
end
</syntaxhighlight>

<syntaxhighlight lang="ruby">
# app/models/mentored_team.rb (mentor lookup)
AssignmentParticipant
.joins('INNER JOIN teams_participants ON teams_participants.participant_id = participants.id')
.where('teams_participants.team_id = ? AND participants.duty_id = ?', id, mentor_duty.id)
.first&.user
</syntaxhighlight>

== RSpec Test Coverage (Actual Specs in This Project) ==

=== Model Specs ===
{| class="wikitable" style="width:100%;"
|-
! Area !! Spec File(s) !! What is validated
|-
| Team validations + membership rules || <code>spec/models/team_spec.rb</code> || Presence/type validation, <code>full?</code>, <code>add_member</code>, eligibility rules
|-
| Capacity behavior || <code>spec/models/team_capacity_spec.rb</code> || Assignment capacity behavior; course teams expected to be uncapped by default
|-
| Association integrity || <code>spec/models/team_association_spec.rb</code> || Team-parent linkage and membership scoping
|-
| Conversion behavior || <code>spec/models/team_conversion_spec.rb</code> || CourseTeam ⇄ AssignmentTeam conversions and member copying
|-
| MentoredTeam duty behavior || <code>spec/models/mentored_team_spec.rb</code> || Mentor duty assignment/removal, mentor lookup by duty, capacity inheritance from AssignmentTeam
|-
| Join model constraints || <code>spec/models/teams_participant_spec.rb</code> || Uniqueness/presence validations; enrollment rules via <code>Team#add_member</code>
|}

=== Request Specs (API/Controllers) ===
{| class="wikitable" style="width:100%;"
|-
! Endpoint Area !! Spec File(s) !! What is validated
|-
| Teams API || <code>spec/requests/api/v1/teams_controller_spec.rb</code> || Index/show/members/add/remove behavior (HTTP codes + JSON shape)
|-
| JoinTeamRequests API || <code>spec/requests/api/v1/join_team_requests_controller_spec.rb</code> || Authorization rules, creating requests, accepting/declining, “team full” responses
|-
| TeamsParticipants API || <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code> || Update duty authorization, list/add/delete participant endpoints
|}

== Notes / Known Gaps ==
* CourseTeam capacity is not configured in the current schema (courses do not have <code>max_team_size</code>), so capacity enforcement is defined for assignment-based teams via <code>Assignment#max_team_size</code>.
* TeamsController role-based restrictions require an explicit policy in <code>TeamsController#action_allowed?</code> to satisfy “student blocked / instructor unrestricted” criteria; the Authorization concern enforces <code>403</code> only when controllers define action rules.

== Summary ==
This project strengthens the teams hierarchy by enforcing enrollment-based membership, preventing duplicate participation across teams, enforcing assignment team capacity with a join-model backstop, and implementing/testing MentoredTeam mentor behavior using participant duty rather than user role. Comprehensive RSpec coverage spans models, conversions, and API request behaviors.

== References ==
* Expertiza project specification — Teams hierarchy testing
* Rails Guides — Active Record Associations
* RSpec Documentation

CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing

2026-03-30T00:13:33Z

Awainga: /* References */

== About This Project ==

{| class="wikitable" style="float:right; margin-left:20px; width:320px;"
|-
! colspan="2" style="background:#cee0f2; text-align:center;" | Project Info
|-
| '''Course''' || CSC/ECE 517 Spring 2026
|-
| '''Project''' || E2610 — Teams Hierarchy Testing
|-
| '''Mentor''' || Vihar Manojkumar Shah
|-
| '''Platform''' || Expertiza (Ruby on Rails)
|-
| '''Test Framework''' || RSpec
|-
| '''Root Class''' || <code>Team</code> (STI superclass)
|-
| '''Subclasses''' || <code>CourseTeam</code>, <code>AssignmentTeam</code>, <code>MentoredTeam</code>
|-
| '''Membership Join Model''' || <code>TeamsParticipant</code>
|}

The Expertiza platform organises student collaboration through a structured class hierarchy dedicated to managing teams. Teams are the unit used to reserve topics, collaborate on coursework, and submit work. This project focuses on validating the correctness of the Team hierarchy and providing thorough RSpec test coverage for team membership rules, conversions between team types, capacity enforcement, and MentoredTeam mentor logic (duty-based rather than role-based).

== Background ==

=== The Team Hierarchy ===
The hierarchy consists of exactly four classes: <code>Team</code> (superclass), <code>CourseTeam</code>, <code>AssignmentTeam</code>, and <code>MentoredTeam</code>. Teams are stored using Rails STI (single table inheritance) via the <code>type</code> column.

Two broad kinds of teams exist:

* '''Course teams''' (<code>CourseTeam</code>) — persist for the duration of an entire course and can be reused across multiple assignments.
* '''Assignment teams''' (<code>AssignmentTeam</code>) — formed for a single assignment. When mentor assignment is enabled, teams are instantiated as <code>MentoredTeam</code>, a subclass of <code>AssignmentTeam</code>.

=== Class Hierarchy Diagram ===
<pre>
┌─────────────────┐
│ Team │
│ (STI parent) │
└────────┬────────┘
│
┌─────────────────┴──────────────────┐
│ │
┌────────┴────────┐ ┌──────────┴──────────┐
│ CourseTeam │ │ AssignmentTeam │
│ (course-scoped) │ │ (assignment-scoped) │
└─────────────────┘ └──────────┬──────────┘
│
┌──────────┴──────────┐
│ MentoredTeam │
│ (mentor via duty) │
└─────────────────────┘
</pre>

=== Subclass Responsibilities ===
{| class="wikitable" style="width:100%;"
|-
! Class !! Scope !! Key Constraint !! Notes
|-
| <code>Team</code> || — || STI superclass, shared associations/logic || Holds membership helpers and core add/remove methods
|-
| <code>CourseTeam</code> || Course || Members must be course participants || Supports conversion to/from assignment teams
|-
| <code>AssignmentTeam</code> || Assignment || Members must be assignment participants || Capacity comes from <code>Assignment#max_team_size</code>
|-
| <code>MentoredTeam</code> || Assignment || Mentor identified by participant duty || Uses <code>Duty</code> + participant <code>duty_id</code>
|}

== Duty vs. Role Distinction (Key Fix) ==
A critical design point is the separation between a user's '''role''' and their '''duty''' within a team.

{| class="wikitable" style="width:100%;"
|-
! Concept !! Definition !! Examples
|-
| '''Role''' || System-level permission level for a user account || <code>Instructor</code>, <code>Teaching Assistant</code>, <code>Student</code>
|-
| '''Duty''' || Team-level function of a participant on a specific team || <code>Submitter</code>, <code>Reviewer</code>, <code>Mentor</code>
|}

In Expertiza, mentors are not special system accounts. A mentor is a normal user whose '''participant record''' has been assigned the '''Mentor duty''' for a particular team. This project enforces and tests mentor identification by duty (not user role).

== Project Goals Implemented ==

=== Membership grounded in valid participation ===
Membership is mediated through <code>Participant</code> records:
* CourseTeam: must be a <code>CourseParticipant</code> for the same course (<code>parent_id</code>).
* AssignmentTeam / MentoredTeam: must be an <code>AssignmentParticipant</code> for the same assignment (<code>parent_id</code>).

This is enforced in <code>Team#add_member</code> by resolving the correct participant type based on the team’s subclass and the team’s <code>parent_id</code>.

<syntaxhighlight lang="ruby">
# app/models/team.rb
def add_member(participant_or_user)
participant =
if participant_or_user.is_a?(AssignmentParticipant) || participant_or_user.is_a?(CourseParticipant)
participant_or_user
elsif participant_or_user.is_a?(User)
participant_type = is_a?(AssignmentTeam) ? AssignmentParticipant : CourseParticipant
participant_type.find_by(user_id: participant_or_user.id, parent_id: parent_id)
else
nil
end

return { success: false, error: "#{participant_or_user.name} is not a participant in this #{is_a?(AssignmentTeam) ? 'assignment' : 'course'}" } if participant.nil?
return { success: false, error: "Participant already on the team" } if participants.exists?(id: participant.id)
return { success: false, error: "Unable to add participant: team is at full capacity." } if full?

team_participant = TeamsParticipant.create(
participant_id: participant.id,
team_id: id,
user_id: participant.user_id
)

team_participant.persisted? ? { success: true } : { success: false, error: team_participant.errors.full_messages.join(', ') }
end
</syntaxhighlight>

=== No user should appear on multiple teams in the same scope ===
The membership join model includes a uniqueness rule that prevents the same participant from being on multiple teams.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validates :participant_id, uniqueness: true
</syntaxhighlight>

A corresponding database migration adds a unique index on <code>participant_id</code> to make this constraint durable at the DB level.

=== Team size limits respected (capacity enforcement) ===
Capacity is enforced in two layers:

1) '''Domain-level check''': <code>Team#add_member</code> rejects when <code>full?</code> is true (returns <code>{success:false, error: ...}</code>).

2) '''Join-model backstop''': direct creation of <code>TeamsParticipant</code> is prevented if the team is already full.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validate :team_not_full, on: :create

def team_not_full
return unless team

max = team.max_size
return if max.blank?

if team.participants.count >= max
errors.add(:base, "Team is at full capacity (max #{max}).")
end
end
</syntaxhighlight>

This prevents bypassing capacity by calling <code>TeamsParticipant.create!</code> directly.

=== Join request acceptance is race-safe ===
The join request acceptance flow is guarded using a transaction and a lock, so that capacity is checked at the time of insertion.

<syntaxhighlight lang="ruby">
# app/controllers/join_team_requests_controller.rb
ActiveRecord::Base.transaction do
team.with_lock do
raise ActiveRecord::RecordInvalid, tp if team.full?
result = team.add_member(participant)
raise ActiveRecord::RecordInvalid, tp unless result[:success]
end

@join_team_request.update!(reply_status: ACCEPTED)
render json: { message: 'Join team request accepted successfully', ... }, status: :ok
end
</syntaxhighlight>

== MentoredTeam (Duty-Based Mentor) ==
MentoredTeam mentor identification and assignment are based on participant duty:

* A mentor duty is represented by a <code>Duty</code> record with name <code>'Mentor'</code>.
* The mentor is the participant on the team whose <code>duty_id</code> equals that duty.

<syntaxhighlight lang="ruby">
# app/models/mentored_team.rb
def assign_mentor(user)
mentor_duty = Duty.find_by(name: 'Mentor')
return false unless mentor_duty

participant = AssignmentParticipant.find_by(user_id: user.id, parent_id: parent_id)
return false unless participant

participant.update(duty_id: mentor_duty.id)
end
</syntaxhighlight>

<syntaxhighlight lang="ruby">
# app/models/mentored_team.rb (mentor lookup)
AssignmentParticipant
.joins('INNER JOIN teams_participants ON teams_participants.participant_id = participants.id')
.where('teams_participants.team_id = ? AND participants.duty_id = ?', id, mentor_duty.id)
.first&.user
</syntaxhighlight>

== RSpec Test Coverage (Actual Specs in This Project) ==

=== Model Specs ===
{| class="wikitable" style="width:100%;"
|-
! Area !! Spec File(s) !! What is validated
|-
| Team validations + membership rules || <code>spec/models/team_spec.rb</code> || Presence/type validation, <code>full?</code>, <code>add_member</code>, eligibility rules
|-
| Capacity behavior || <code>spec/models/team_capacity_spec.rb</code> || Assignment capacity behavior; course teams expected to be uncapped by default
|-
| Association integrity || <code>spec/models/team_association_spec.rb</code> || Team-parent linkage and membership scoping
|-
| Conversion behavior || <code>spec/models/team_conversion_spec.rb</code> || CourseTeam ⇄ AssignmentTeam conversions and member copying
|-
| MentoredTeam duty behavior || <code>spec/models/mentored_team_spec.rb</code> || Mentor duty assignment/removal, mentor lookup by duty, capacity inheritance from AssignmentTeam
|-
| Join model constraints || <code>spec/models/teams_participant_spec.rb</code> || Uniqueness/presence validations; enrollment rules via <code>Team#add_member</code>
|}

=== Request Specs (API/Controllers) ===
{| class="wikitable" style="width:100%;"
|-
! Endpoint Area !! Spec File(s) !! What is validated
|-
| Teams API || <code>spec/requests/api/v1/teams_controller_spec.rb</code> || Index/show/members/add/remove behavior (HTTP codes + JSON shape)
|-
| JoinTeamRequests API || <code>spec/requests/api/v1/join_team_requests_controller_spec.rb</code> || Authorization rules, creating requests, accepting/declining, “team full” responses
|-
| TeamsParticipants API || <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code> || Update duty authorization, list/add/delete participant endpoints
|}

== Notes / Known Gaps ==
* CourseTeam capacity is not configured in the current schema (courses do not have <code>max_team_size</code>), so capacity enforcement is defined for assignment-based teams via <code>Assignment#max_team_size</code>.
* TeamsController role-based restrictions require an explicit policy in <code>TeamsController#action_allowed?</code> to satisfy “student blocked / instructor unrestricted” criteria; the Authorization concern enforces <code>403</code> only when controllers define action rules.

== Summary ==
This project strengthens the teams hierarchy by enforcing enrollment-based membership, preventing duplicate participation across teams, enforcing assignment team capacity with a join-model backstop, and implementing/testing MentoredTeam mentor behavior using participant duty rather than user role. Comprehensive RSpec coverage spans models, conversions, and API request behaviors.

== References ==
* Expertiza project specification — Teams hierarchy testing
* Rails Guides — Active Record Associations
* RSpec Documentation

CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing

2026-03-30T00:12:44Z

Awainga: /* References */

== About This Project ==

{| class="wikitable" style="float:right; margin-left:20px; width:320px;"
|-
! colspan="2" style="background:#cee0f2; text-align:center;" | Project Info
|-
| '''Course''' || CSC/ECE 517 Spring 2026
|-
| '''Project''' || E2610 — Teams Hierarchy Testing
|-
| '''Mentor''' || Vihar Manojkumar Shah
|-
| '''Platform''' || Expertiza (Ruby on Rails)
|-
| '''Test Framework''' || RSpec
|-
| '''Root Class''' || <code>Team</code> (STI superclass)
|-
| '''Subclasses''' || <code>CourseTeam</code>, <code>AssignmentTeam</code>, <code>MentoredTeam</code>
|-
| '''Membership Join Model''' || <code>TeamsParticipant</code>
|}

The Expertiza platform organises student collaboration through a structured class hierarchy dedicated to managing teams. Teams are the unit used to reserve topics, collaborate on coursework, and submit work. This project focuses on validating the correctness of the Team hierarchy and providing thorough RSpec test coverage for team membership rules, conversions between team types, capacity enforcement, and MentoredTeam mentor logic (duty-based rather than role-based).

== Background ==

=== The Team Hierarchy ===
The hierarchy consists of exactly four classes: <code>Team</code> (superclass), <code>CourseTeam</code>, <code>AssignmentTeam</code>, and <code>MentoredTeam</code>. Teams are stored using Rails STI (single table inheritance) via the <code>type</code> column.

Two broad kinds of teams exist:

* '''Course teams''' (<code>CourseTeam</code>) — persist for the duration of an entire course and can be reused across multiple assignments.
* '''Assignment teams''' (<code>AssignmentTeam</code>) — formed for a single assignment. When mentor assignment is enabled, teams are instantiated as <code>MentoredTeam</code>, a subclass of <code>AssignmentTeam</code>.

=== Class Hierarchy Diagram ===
<pre>
┌─────────────────┐
│ Team │
│ (STI parent) │
└────────┬────────┘
│
┌─────────────────┴──────────────────┐
│ │
┌────────┴────────┐ ┌──────────┴──────────┐
│ CourseTeam │ │ AssignmentTeam │
│ (course-scoped) │ │ (assignment-scoped) │
└─────────────────┘ └──────────┬──────────┘
│
┌──────────┴──────────┐
│ MentoredTeam │
│ (mentor via duty) │
└─────────────────────┘
</pre>

=== Subclass Responsibilities ===
{| class="wikitable" style="width:100%;"
|-
! Class !! Scope !! Key Constraint !! Notes
|-
| <code>Team</code> || — || STI superclass, shared associations/logic || Holds membership helpers and core add/remove methods
|-
| <code>CourseTeam</code> || Course || Members must be course participants || Supports conversion to/from assignment teams
|-
| <code>AssignmentTeam</code> || Assignment || Members must be assignment participants || Capacity comes from <code>Assignment#max_team_size</code>
|-
| <code>MentoredTeam</code> || Assignment || Mentor identified by participant duty || Uses <code>Duty</code> + participant <code>duty_id</code>
|}

== Duty vs. Role Distinction (Key Fix) ==
A critical design point is the separation between a user's '''role''' and their '''duty''' within a team.

{| class="wikitable" style="width:100%;"
|-
! Concept !! Definition !! Examples
|-
| '''Role''' || System-level permission level for a user account || <code>Instructor</code>, <code>Teaching Assistant</code>, <code>Student</code>
|-
| '''Duty''' || Team-level function of a participant on a specific team || <code>Submitter</code>, <code>Reviewer</code>, <code>Mentor</code>
|}

In Expertiza, mentors are not special system accounts. A mentor is a normal user whose '''participant record''' has been assigned the '''Mentor duty''' for a particular team. This project enforces and tests mentor identification by duty (not user role).

== Project Goals Implemented ==

=== Membership grounded in valid participation ===
Membership is mediated through <code>Participant</code> records:
* CourseTeam: must be a <code>CourseParticipant</code> for the same course (<code>parent_id</code>).
* AssignmentTeam / MentoredTeam: must be an <code>AssignmentParticipant</code> for the same assignment (<code>parent_id</code>).

This is enforced in <code>Team#add_member</code> by resolving the correct participant type based on the team’s subclass and the team’s <code>parent_id</code>.

<syntaxhighlight lang="ruby">
# app/models/team.rb
def add_member(participant_or_user)
participant =
if participant_or_user.is_a?(AssignmentParticipant) || participant_or_user.is_a?(CourseParticipant)
participant_or_user
elsif participant_or_user.is_a?(User)
participant_type = is_a?(AssignmentTeam) ? AssignmentParticipant : CourseParticipant
participant_type.find_by(user_id: participant_or_user.id, parent_id: parent_id)
else
nil
end

return { success: false, error: "#{participant_or_user.name} is not a participant in this #{is_a?(AssignmentTeam) ? 'assignment' : 'course'}" } if participant.nil?
return { success: false, error: "Participant already on the team" } if participants.exists?(id: participant.id)
return { success: false, error: "Unable to add participant: team is at full capacity." } if full?

team_participant = TeamsParticipant.create(
participant_id: participant.id,
team_id: id,
user_id: participant.user_id
)

team_participant.persisted? ? { success: true } : { success: false, error: team_participant.errors.full_messages.join(', ') }
end
</syntaxhighlight>

=== No user should appear on multiple teams in the same scope ===
The membership join model includes a uniqueness rule that prevents the same participant from being on multiple teams.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validates :participant_id, uniqueness: true
</syntaxhighlight>

A corresponding database migration adds a unique index on <code>participant_id</code> to make this constraint durable at the DB level.

=== Team size limits respected (capacity enforcement) ===
Capacity is enforced in two layers:

1) '''Domain-level check''': <code>Team#add_member</code> rejects when <code>full?</code> is true (returns <code>{success:false, error: ...}</code>).

2) '''Join-model backstop''': direct creation of <code>TeamsParticipant</code> is prevented if the team is already full.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validate :team_not_full, on: :create

def team_not_full
return unless team

max = team.max_size
return if max.blank?

if team.participants.count >= max
errors.add(:base, "Team is at full capacity (max #{max}).")
end
end
</syntaxhighlight>

This prevents bypassing capacity by calling <code>TeamsParticipant.create!</code> directly.

=== Join request acceptance is race-safe ===
The join request acceptance flow is guarded using a transaction and a lock, so that capacity is checked at the time of insertion.

<syntaxhighlight lang="ruby">
# app/controllers/join_team_requests_controller.rb
ActiveRecord::Base.transaction do
team.with_lock do
raise ActiveRecord::RecordInvalid, tp if team.full?
result = team.add_member(participant)
raise ActiveRecord::RecordInvalid, tp unless result[:success]
end

@join_team_request.update!(reply_status: ACCEPTED)
render json: { message: 'Join team request accepted successfully', ... }, status: :ok
end
</syntaxhighlight>

== MentoredTeam (Duty-Based Mentor) ==
MentoredTeam mentor identification and assignment are based on participant duty:

* A mentor duty is represented by a <code>Duty</code> record with name <code>'Mentor'</code>.
* The mentor is the participant on the team whose <code>duty_id</code> equals that duty.

<syntaxhighlight lang="ruby">
# app/models/mentored_team.rb
def assign_mentor(user)
mentor_duty = Duty.find_by(name: 'Mentor')
return false unless mentor_duty

participant = AssignmentParticipant.find_by(user_id: user.id, parent_id: parent_id)
return false unless participant

participant.update(duty_id: mentor_duty.id)
end
</syntaxhighlight>

<syntaxhighlight lang="ruby">
# app/models/mentored_team.rb (mentor lookup)
AssignmentParticipant
.joins('INNER JOIN teams_participants ON teams_participants.participant_id = participants.id')
.where('teams_participants.team_id = ? AND participants.duty_id = ?', id, mentor_duty.id)
.first&.user
</syntaxhighlight>

== RSpec Test Coverage (Actual Specs in This Project) ==

=== Model Specs ===
{| class="wikitable" style="width:100%;"
|-
! Area !! Spec File(s) !! What is validated
|-
| Team validations + membership rules || <code>spec/models/team_spec.rb</code> || Presence/type validation, <code>full?</code>, <code>add_member</code>, eligibility rules
|-
| Capacity behavior || <code>spec/models/team_capacity_spec.rb</code> || Assignment capacity behavior; course teams expected to be uncapped by default
|-
| Association integrity || <code>spec/models/team_association_spec.rb</code> || Team-parent linkage and membership scoping
|-
| Conversion behavior || <code>spec/models/team_conversion_spec.rb</code> || CourseTeam ⇄ AssignmentTeam conversions and member copying
|-
| MentoredTeam duty behavior || <code>spec/models/mentored_team_spec.rb</code> || Mentor duty assignment/removal, mentor lookup by duty, capacity inheritance from AssignmentTeam
|-
| Join model constraints || <code>spec/models/teams_participant_spec.rb</code> || Uniqueness/presence validations; enrollment rules via <code>Team#add_member</code>
|}

=== Request Specs (API/Controllers) ===
{| class="wikitable" style="width:100%;"
|-
! Endpoint Area !! Spec File(s) !! What is validated
|-
| Teams API || <code>spec/requests/api/v1/teams_controller_spec.rb</code> || Index/show/members/add/remove behavior (HTTP codes + JSON shape)
|-
| JoinTeamRequests API || <code>spec/requests/api/v1/join_team_requests_controller_spec.rb</code> || Authorization rules, creating requests, accepting/declining, “team full” responses
|-
| TeamsParticipants API || <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code> || Update duty authorization, list/add/delete participant endpoints
|}

== Notes / Known Gaps ==
* CourseTeam capacity is not configured in the current schema (courses do not have <code>max_team_size</code>), so capacity enforcement is defined for assignment-based teams via <code>Assignment#max_team_size</code>.
* TeamsController role-based restrictions require an explicit policy in <code>TeamsController#action_allowed?</code> to satisfy “student blocked / instructor unrestricted” criteria; the Authorization concern enforces <code>403</code> only when controllers define action rules.

== Summary ==
This project strengthens the teams hierarchy by enforcing enrollment-based membership, preventing duplicate participation across teams, enforcing assignment team capacity with a join-model backstop, and implementing/testing MentoredTeam mentor behavior using participant duty rather than user role. Comprehensive RSpec coverage spans models, conversions, and API request behaviors.

== References ==
* Expertiza project specification — Teams hierarchy testing
* Rails Guides — Active Record Associations
* RSpec Documentation

[[Category:Spring 2026]]
[[Category:CSC517]]
[[Category:ECE517]]

CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing

2026-03-30T00:10:37Z

Awainga:

== About This Project ==

{| class="wikitable" style="float:right; margin-left:20px; width:320px;"
|-
! colspan="2" style="background:#cee0f2; text-align:center;" | Project Info
|-
| '''Course''' || CSC/ECE 517 Spring 2026
|-
| '''Project''' || E2610 — Teams Hierarchy Testing
|-
| '''Mentor''' || Vihar Manojkumar Shah
|-
| '''Platform''' || Expertiza (Ruby on Rails)
|-
| '''Test Framework''' || RSpec
|-
| '''Root Class''' || <code>Team</code> (STI superclass)
|-
| '''Subclasses''' || <code>CourseTeam</code>, <code>AssignmentTeam</code>, <code>MentoredTeam</code>
|-
| '''Membership Join Model''' || <code>TeamsParticipant</code>
|}

The Expertiza platform organises student collaboration through a structured class hierarchy dedicated to managing teams. Teams are the unit used to reserve topics, collaborate on coursework, and submit work. This project focuses on validating the correctness of the Team hierarchy and providing thorough RSpec test coverage for team membership rules, conversions between team types, capacity enforcement, and MentoredTeam mentor logic (duty-based rather than role-based).

== Background ==

=== The Team Hierarchy ===
The hierarchy consists of exactly four classes: <code>Team</code> (superclass), <code>CourseTeam</code>, <code>AssignmentTeam</code>, and <code>MentoredTeam</code>. Teams are stored using Rails STI (single table inheritance) via the <code>type</code> column.

Two broad kinds of teams exist:

* '''Course teams''' (<code>CourseTeam</code>) — persist for the duration of an entire course and can be reused across multiple assignments.
* '''Assignment teams''' (<code>AssignmentTeam</code>) — formed for a single assignment. When mentor assignment is enabled, teams are instantiated as <code>MentoredTeam</code>, a subclass of <code>AssignmentTeam</code>.

=== Class Hierarchy Diagram ===
<pre>
┌─────────────────┐
│ Team │
│ (STI parent) │
└────────┬────────┘
│
┌─────────────────┴──────────────────┐
│ │
┌────────┴────────┐ ┌──────────┴──────────┐
│ CourseTeam │ │ AssignmentTeam │
│ (course-scoped) │ │ (assignment-scoped) │
└─────────────────┘ └──────────┬──────────┘
│
┌──────────┴──────────┐
│ MentoredTeam │
│ (mentor via duty) │
└─────────────────────┘
</pre>

=== Subclass Responsibilities ===
{| class="wikitable" style="width:100%;"
|-
! Class !! Scope !! Key Constraint !! Notes
|-
| <code>Team</code> || — || STI superclass, shared associations/logic || Holds membership helpers and core add/remove methods
|-
| <code>CourseTeam</code> || Course || Members must be course participants || Supports conversion to/from assignment teams
|-
| <code>AssignmentTeam</code> || Assignment || Members must be assignment participants || Capacity comes from <code>Assignment#max_team_size</code>
|-
| <code>MentoredTeam</code> || Assignment || Mentor identified by participant duty || Uses <code>Duty</code> + participant <code>duty_id</code>
|}

== Duty vs. Role Distinction (Key Fix) ==
A critical design point is the separation between a user's '''role''' and their '''duty''' within a team.

{| class="wikitable" style="width:100%;"
|-
! Concept !! Definition !! Examples
|-
| '''Role''' || System-level permission level for a user account || <code>Instructor</code>, <code>Teaching Assistant</code>, <code>Student</code>
|-
| '''Duty''' || Team-level function of a participant on a specific team || <code>Submitter</code>, <code>Reviewer</code>, <code>Mentor</code>
|}

In Expertiza, mentors are not special system accounts. A mentor is a normal user whose '''participant record''' has been assigned the '''Mentor duty''' for a particular team. This project enforces and tests mentor identification by duty (not user role).

== Project Goals Implemented ==

=== Membership grounded in valid participation ===
Membership is mediated through <code>Participant</code> records:
* CourseTeam: must be a <code>CourseParticipant</code> for the same course (<code>parent_id</code>).
* AssignmentTeam / MentoredTeam: must be an <code>AssignmentParticipant</code> for the same assignment (<code>parent_id</code>).

This is enforced in <code>Team#add_member</code> by resolving the correct participant type based on the team’s subclass and the team’s <code>parent_id</code>.

<syntaxhighlight lang="ruby">
# app/models/team.rb
def add_member(participant_or_user)
participant =
if participant_or_user.is_a?(AssignmentParticipant) || participant_or_user.is_a?(CourseParticipant)
participant_or_user
elsif participant_or_user.is_a?(User)
participant_type = is_a?(AssignmentTeam) ? AssignmentParticipant : CourseParticipant
participant_type.find_by(user_id: participant_or_user.id, parent_id: parent_id)
else
nil
end

return { success: false, error: "#{participant_or_user.name} is not a participant in this #{is_a?(AssignmentTeam) ? 'assignment' : 'course'}" } if participant.nil?
return { success: false, error: "Participant already on the team" } if participants.exists?(id: participant.id)
return { success: false, error: "Unable to add participant: team is at full capacity." } if full?

team_participant = TeamsParticipant.create(
participant_id: participant.id,
team_id: id,
user_id: participant.user_id
)

team_participant.persisted? ? { success: true } : { success: false, error: team_participant.errors.full_messages.join(', ') }
end
</syntaxhighlight>

=== No user should appear on multiple teams in the same scope ===
The membership join model includes a uniqueness rule that prevents the same participant from being on multiple teams.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validates :participant_id, uniqueness: true
</syntaxhighlight>

A corresponding database migration adds a unique index on <code>participant_id</code> to make this constraint durable at the DB level.

=== Team size limits respected (capacity enforcement) ===
Capacity is enforced in two layers:

1) '''Domain-level check''': <code>Team#add_member</code> rejects when <code>full?</code> is true (returns <code>{success:false, error: ...}</code>).

2) '''Join-model backstop''': direct creation of <code>TeamsParticipant</code> is prevented if the team is already full.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validate :team_not_full, on: :create

def team_not_full
return unless team

max = team.max_size
return if max.blank?

if team.participants.count >= max
errors.add(:base, "Team is at full capacity (max #{max}).")
end
end
</syntaxhighlight>

This prevents bypassing capacity by calling <code>TeamsParticipant.create!</code> directly.

=== Join request acceptance is race-safe ===
The join request acceptance flow is guarded using a transaction and a lock, so that capacity is checked at the time of insertion.

<syntaxhighlight lang="ruby">
# app/controllers/join_team_requests_controller.rb
ActiveRecord::Base.transaction do
team.with_lock do
raise ActiveRecord::RecordInvalid, tp if team.full?
result = team.add_member(participant)
raise ActiveRecord::RecordInvalid, tp unless result[:success]
end

@join_team_request.update!(reply_status: ACCEPTED)
render json: { message: 'Join team request accepted successfully', ... }, status: :ok
end
</syntaxhighlight>

== MentoredTeam (Duty-Based Mentor) ==
MentoredTeam mentor identification and assignment are based on participant duty:

* A mentor duty is represented by a <code>Duty</code> record with name <code>'Mentor'</code>.
* The mentor is the participant on the team whose <code>duty_id</code> equals that duty.

<syntaxhighlight lang="ruby">
# app/models/mentored_team.rb
def assign_mentor(user)
mentor_duty = Duty.find_by(name: 'Mentor')
return false unless mentor_duty

participant = AssignmentParticipant.find_by(user_id: user.id, parent_id: parent_id)
return false unless participant

participant.update(duty_id: mentor_duty.id)
end
</syntaxhighlight>

<syntaxhighlight lang="ruby">
# app/models/mentored_team.rb (mentor lookup)
AssignmentParticipant
.joins('INNER JOIN teams_participants ON teams_participants.participant_id = participants.id')
.where('teams_participants.team_id = ? AND participants.duty_id = ?', id, mentor_duty.id)
.first&.user
</syntaxhighlight>

== RSpec Test Coverage (Actual Specs in This Project) ==

=== Model Specs ===
{| class="wikitable" style="width:100%;"
|-
! Area !! Spec File(s) !! What is validated
|-
| Team validations + membership rules || <code>spec/models/team_spec.rb</code> || Presence/type validation, <code>full?</code>, <code>add_member</code>, eligibility rules
|-
| Capacity behavior || <code>spec/models/team_capacity_spec.rb</code> || Assignment capacity behavior; course teams expected to be uncapped by default
|-
| Association integrity || <code>spec/models/team_association_spec.rb</code> || Team-parent linkage and membership scoping
|-
| Conversion behavior || <code>spec/models/team_conversion_spec.rb</code> || CourseTeam ⇄ AssignmentTeam conversions and member copying
|-
| MentoredTeam duty behavior || <code>spec/models/mentored_team_spec.rb</code> || Mentor duty assignment/removal, mentor lookup by duty, capacity inheritance from AssignmentTeam
|-
| Join model constraints || <code>spec/models/teams_participant_spec.rb</code> || Uniqueness/presence validations; enrollment rules via <code>Team#add_member</code>
|}

=== Request Specs (API/Controllers) ===
{| class="wikitable" style="width:100%;"
|-
! Endpoint Area !! Spec File(s) !! What is validated
|-
| Teams API || <code>spec/requests/api/v1/teams_controller_spec.rb</code> || Index/show/members/add/remove behavior (HTTP codes + JSON shape)
|-
| JoinTeamRequests API || <code>spec/requests/api/v1/join_team_requests_controller_spec.rb</code> || Authorization rules, creating requests, accepting/declining, “team full” responses
|-
| TeamsParticipants API || <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code> || Update duty authorization, list/add/delete participant endpoints
|}

== Notes / Known Gaps ==
* CourseTeam capacity is not configured in the current schema (courses do not have <code>max_team_size</code>), so capacity enforcement is defined for assignment-based teams via <code>Assignment#max_team_size</code>.
* TeamsController role-based restrictions require an explicit policy in <code>TeamsController#action_allowed?</code> to satisfy “student blocked / instructor unrestricted” criteria; the Authorization concern enforces <code>403</code> only when controllers define action rules.

== Summary ==
This project strengthens the teams hierarchy by enforcing enrollment-based membership, preventing duplicate participation across teams, enforcing assignment team capacity with a join-model backstop, and implementing/testing MentoredTeam mentor behavior using participant duty rather than user role. Comprehensive RSpec coverage spans models, conversions, and API request behaviors.

== References ==
* Expertiza project specification — Teams hierarchy testing (Mentor: Vihar Manojkumar Shah)
* Rails Guides — Active Record Associations
* RSpec Documentation

[[Category:Spring 2026]]
[[Category:CSC517]]
[[Category:ECE517]]

CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing

2026-03-29T23:58:51Z

Awainga: Blanked the page

CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing

2026-03-29T23:58:19Z

Awainga: Created page with "<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Expertiza Teams Hierarchy – Wikipedia-style Article</title> <style> @import url('https://fonts.googleapis.com/css2?family=Linux+Libertine+Display:ital,wght@0,400;0,600;1,400&family=Linux+Biolinum:wght@400;600&display=swap'); *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; } :root { --bg: #f8f9fa..."

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Expertiza Teams Hierarchy – Wikipedia-style Article</title>
<style>
@import url('https://fonts.googleapis.com/css2?family=Linux+Libertine+Display:ital,wght@0,400;0,600;1,400&family=Linux+Biolinum:wght@400;600&display=swap');

*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }

:root {
--bg: #f8f9fa;
--surface: #ffffff;
--border: #a2a9b1;
--border-light: #eaecf0;
--text: #202122;
--text-muted: #54595d;
--text-caption: #72777d;
--link: #3366cc;
--link-visited: #6b4ba1;
--toc-bg: #f8f9fa;
--toc-border: #a2a9b1;
--infobox-bg: #f8f9fa;
--infobox-header: #cee0f2;
--note-bg: #eaf3fb;
--note-border: #3683bb;
--warn-bg: #fef6e7;
--warn-border: #f28500;
--code-bg: #f6f6f6;
--title-border: #a2a9b1;
}

body {
font-family: 'Linux Libertine', 'Georgia', serif;
font-size: 14.4px;
line-height: 1.6;
color: var(--text);
background: var(--bg);
}

.page-wrap {
max-width: 960px;
margin: 0 auto;
background: var(--surface);
padding: 20px 24px 40px;
border-left: 1px solid var(--border-light);
border-right: 1px solid var(--border-light);
min-height: 100vh;
}

/* ── Header ── */
.page-header {
border-bottom: 1px solid var(--title-border);
margin-bottom: 16px;
padding-bottom: 4px;
}

h1.page-title {
font-family: 'Linux Libertine Display', 'Georgia', serif;
font-size: 2em;
font-weight: 400;
color: var(--text);
letter-spacing: -0.3px;
}

.hatnote {
font-style: italic;
color: var(--text-muted);
font-size: 0.9em;
margin-bottom: 12px;
padding-left: 1.6em;
border-left: 3px solid var(--border-light);
}

/* ── Sections ── */
h2 {
font-family: 'Linux Biolinum', 'Arial', sans-serif;
font-size: 1.4em;
font-weight: 600;
border-bottom: 1px solid var(--border-light);
margin: 28px 0 10px;
padding-bottom: 4px;
color: var(--text);
}

h3 {
font-family: 'Linux Biolinum', 'Arial', sans-serif;
font-size: 1.1em;
font-weight: 600;
margin: 18px 0 8px;
color: var(--text);
}

p { margin-bottom: 10px; }

a { color: var(--link); text-decoration: none; }
a:hover { text-decoration: underline; }
a:visited { color: var(--link-visited); }

/* ── Table of Contents ── */
.toc {
float: right;
clear: right;
margin: 0 0 20px 24px;
background: var(--toc-bg);
border: 1px solid var(--toc-border);
padding: 12px 16px;
font-size: 0.88em;
min-width: 220px;
max-width: 280px;
}

.toc-title {
font-weight: bold;
text-align: center;
margin-bottom: 8px;
font-size: 1em;
}

.toc ol {
margin: 0;
padding-left: 20px;
}

.toc li { margin: 3px 0; line-height: 1.4; }
.toc a { color: var(--text); }
.toc a:hover { text-decoration: underline; }

.toc ol ol { font-size: 0.95em; margin-top: 3px; }

/* ── Infobox ── */
.infobox {
float: right;
clear: right;
margin: 0 0 20px 24px;
border: 1px solid var(--border);
background: var(--infobox-bg);
font-size: 0.88em;
min-width: 260px;
max-width: 300px;
}

.infobox-title {
background: var(--infobox-header);
text-align: center;
padding: 8px 10px;
font-weight: bold;
font-family: 'Linux Biolinum', sans-serif;
font-size: 1.05em;
border-bottom: 1px solid var(--border);
}

.infobox table {
width: 100%;
border-collapse: collapse;
}

.infobox td {
padding: 4px 8px;
vertical-align: top;
border-bottom: 1px solid var(--border-light);
line-height: 1.4;
}

.infobox td:first-child {
font-weight: bold;
color: var(--text-muted);
white-space: nowrap;
width: 40%;
}

/* ── Notes / Warnings ── */
.note {
background: var(--note-bg);
border-left: 4px solid var(--note-border);
padding: 10px 14px;
margin: 14px 0;
font-size: 0.93em;
}

.warn {
background: var(--warn-bg);
border-left: 4px solid var(--warn-border);
padding: 10px 14px;
margin: 14px 0;
font-size: 0.93em;
}

/* ── Code ── */
code {
font-family: 'Courier New', monospace;
background: var(--code-bg);
border: 1px solid var(--border-light);
padding: 1px 4px;
font-size: 0.9em;
border-radius: 2px;
}

pre {
background: var(--code-bg);
border: 1px solid var(--border-light);
padding: 12px 14px;
overflow-x: auto;
font-size: 0.88em;
line-height: 1.5;
margin: 12px 0;
}

pre code { background: none; border: none; padding: 0; font-size: inherit; }

/* ── Tables ── */
.wiki-table {
border-collapse: collapse;
margin: 16px 0;
font-size: 0.9em;
width: 100%;
}

.wiki-table th {
background: #eaecf0;
border: 1px solid var(--border);
padding: 6px 10px;
text-align: left;
font-family: 'Linux Biolinum', sans-serif;
}

.wiki-table td {
border: 1px solid var(--border);
padding: 6px 10px;
vertical-align: top;
}

.wiki-table tr:nth-child(even) td { background: #f8f9fa; }

/* ── Hierarchy diagram ── */
.hierarchy-wrap {
margin: 18px 0;
overflow-x: auto;
}

/* ── Categories ── */
.categories {
border-top: 1px solid var(--border-light);
margin-top: 36px;
padding-top: 10px;
font-size: 0.88em;
color: var(--text-muted);
}

.categories strong { color: var(--text); }

/* ── References ── */
.references {
font-size: 0.88em;
color: var(--text-muted);
columns: 2;
column-gap: 24px;
}

.references ol { padding-left: 18px; }
.references li { margin-bottom: 4px; line-height: 1.4; }

.ref-sup {
font-size: 0.75em;
vertical-align: super;
color: var(--link);
cursor: pointer;
}

/* ── Clearfix ── */
.clearfix::after { content: ''; display: table; clear: both; }

/* ── Responsive ── */
@media (max-width: 640px) {
.infobox, .toc { float: none; max-width: 100%; margin: 0 0 16px; }
.references { columns: 1; }
}

/* ── Duty vs Role comparison box ── */
.compare-box {
display: grid;
grid-template-columns: 1fr 1fr;
gap: 0;
border: 1px solid var(--border);
margin: 16px 0;
font-size: 0.9em;
}

.compare-box .col-head {
background: #eaecf0;
font-weight: bold;
padding: 7px 12px;
border-bottom: 1px solid var(--border);
font-family: 'Linux Biolinum', sans-serif;
}

.compare-box .col-head:first-child { border-right: 1px solid var(--border); }

.compare-box .col-body {
padding: 8px 12px;
line-height: 1.5;
}

.compare-box .col-body:first-child { border-right: 1px solid var(--border); }

ul, ol { padding-left: 22px; margin-bottom: 10px; }
li { margin-bottom: 3px; }
</style>
</head>
<body>
<div class="page-wrap">


<div class="page-header">
<h1 class="page-title">Expertiza Teams Hierarchy</h1>
</div>
<p class="hatnote">This article covers the software design and implementation of team management in the Expertiza platform. For the broader Expertiza system, see <a href="#">Expertiza (software)</a>.</p>

<div class="clearfix">


<div class="infobox">
<div class="infobox-title">Expertiza Teams Hierarchy</div>
<table>
<tr><td>Platform</td><td>Expertiza (Ruby on Rails)</td></tr>
<tr><td>Root class</td><td><code>Team</code> (abstract)</td></tr>
<tr><td>Subclasses</td><td><code>CourseTeam</code>, <code>AssignmentTeam</code>, <code>MentoredTeam</code></td></tr>
<tr><td>Mentor</td><td>Vihar Manojkumar Shah</td></tr>
<tr><td>Test framework</td><td>RSpec</td></tr>
<tr><td>Membership model</td><td>Enrollment-based</td></tr>
<tr><td>Hierarchy depth</td><td>3 levels (Team → AssignmentTeam → MentoredTeam)</td></tr>
</table>
</div>


<div class="toc">
<div class="toc-title">Contents</div>
<ol>
<li><a href="#overview">Overview</a></li>
<li><a href="#hierarchy">Class hierarchy</a>
<ol>
<li><a href="#team">Team (abstract root)</a></li>
<li><a href="#courseteam">CourseTeam</a></li>
<li><a href="#assignmentteam">AssignmentTeam</a></li>
<li><a href="#mentoredteam">MentoredTeam</a></li>
</ol>
</li>
<li><a href="#duty-vs-role">Duty vs. role distinction</a></li>
<li><a href="#membership">Membership rules</a></li>
<li><a href="#mentored-impl">MentoredTeam implementation</a></li>
<li><a href="#testing">Test coverage (RSpec)</a>
<ol>
<li><a href="#test-model">Model validations</a></li>
<li><a href="#test-assoc">Association integrity</a></li>
<li><a href="#test-subclass">Subclass-specific behaviour</a></li>
<li><a href="#test-capacity">Capacity and size limits</a></li>
<li><a href="#test-edge">Edge cases</a></li>
<li><a href="#test-auth">Controller authorization</a></li>
<li><a href="#test-http">HTTP response codes</a></li>
</ol>
</li>
<li><a href="#references">References</a></li>
</ol>
</div>


<p>
The <b>Expertiza teams hierarchy</b> is a structured set of Ruby on Rails model classes that governs how student groups are formed, managed, and constrained within the <a href="#">Expertiza</a> peer-review platform. The hierarchy consists of exactly four classes — <code>Team</code>, <code>CourseTeam</code>, <code>AssignmentTeam</code>, and <code>MentoredTeam</code> — and underpins every form of collaborative participation in the system, from reserving discussion topics to submitting completed assignments.
</p>

<p>
The design follows a classical object-oriented inheritance pattern: an intentionally abstract superclass provides the shared data model and common behaviours, while concrete subclasses carry distinct responsibilities, lifecycle rules, and membership constraints. The hierarchy also plays a central role in the platform's role and duty model, most visibly in the <code>MentoredTeam</code> class, which designates a team participant as a mentor through a <em>duty</em> attribute rather than a system-level <em>role</em>.
</p>

</div>


<h2 id="overview">Overview</h2>

<p>
Expertiza organises student collaboration through a structured class hierarchy dedicated to managing teams. Teams serve as the fundamental unit of academic participation: they allow groups of students to collectively reserve discussion topics, collaborate on coursework, and submit completed assignments for evaluation.<span class="ref-sup">[1]</span>
</p>

<p>
Two broad kinds of team exist in the system. <em>Course teams</em> persist for the duration of an entire course and may be reused across multiple assignments, particularly in Team-Based Learning (TBL) environments. <em>Assignment teams</em> are formed specifically for a single assignment and dissolve once that assignment closes. When an assignment is configured to automatically assign mentors, the team is instantiated as a <code>MentoredTeam</code> — a specialised subclass of <code>AssignmentTeam</code> that records a designated mentor guiding the group.
</p>


<h2 id="hierarchy">Class hierarchy</h2>

<p>The four classes form a three-level inheritance tree:</p>

<div class="hierarchy-wrap">
<svg width="100%" viewBox="0 0 680 260" xmlns="http://www.w3.org/2000/svg" style="max-width:600px;display:block;margin:0 auto">
<defs>
<marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
<path d="M2 1L8 5L2 9" fill="none" stroke="#54595d" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
</marker>
</defs>

<rect x="230" y="18" width="220" height="52" rx="6" fill="#cee0f2" stroke="#a2a9b1" stroke-width="1"/>
<text x="340" y="40" text-anchor="middle" font-family="'Courier New',monospace" font-size="14" font-weight="600" fill="#202122">Team</text>
<text x="340" y="58" text-anchor="middle" font-family="Arial,sans-serif" font-size="11" fill="#54595d">(abstract superclass)</text>


<line x1="280" y1="70" x2="140" y2="130" stroke="#54595d" stroke-width="1" marker-end="url(#arrow)"/>

<line x1="400" y1="70" x2="500" y2="130" stroke="#54595d" stroke-width="1" marker-end="url(#arrow)"/>


<rect x="40" y="130" width="200" height="52" rx="6" fill="#eaf3fb" stroke="#a2a9b1" stroke-width="1"/>
<text x="140" y="152" text-anchor="middle" font-family="'Courier New',monospace" font-size="13" font-weight="600" fill="#202122">CourseTeam</text>
<text x="140" y="170" text-anchor="middle" font-family="Arial,sans-serif" font-size="11" fill="#54595d">Course-scoped teams</text>


<rect x="390" y="130" width="220" height="52" rx="6" fill="#eaf3fb" stroke="#a2a9b1" stroke-width="1"/>
<text x="500" y="152" text-anchor="middle" font-family="'Courier New',monospace" font-size="13" font-weight="600" fill="#202122">AssignmentTeam</text>
<text x="500" y="170" text-anchor="middle" font-family="Arial,sans-serif" font-size="11" fill="#54595d">Assignment-scoped teams</text>


<line x1="500" y1="182" x2="500" y2="208" stroke="#54595d" stroke-width="1" marker-end="url(#arrow)"/>


<rect x="380" y="208" width="240" height="42" rx="6" fill="#fef6e7" stroke="#f28500" stroke-width="1"/>
<text x="500" y="226" text-anchor="middle" font-family="'Courier New',monospace" font-size="13" font-weight="600" fill="#202122">MentoredTeam</text>
<text x="500" y="242" text-anchor="middle" font-family="Arial,sans-serif" font-size="11" fill="#54595d">Includes a duty=mentor participant</text>


<path d="M240 156 Q310 195 390 156" fill="none" stroke="#3366cc" stroke-width="1" stroke-dasharray="5,4"/>
<text x="315" y="205" text-anchor="middle" font-family="Arial,sans-serif" font-size="10" fill="#3366cc">convertible</text>
</svg>
</div>

<h3 id="team">Team (abstract root)</h3>
<p>
The <code>Team</code> class sits at the root of the hierarchy and provides the shared data model, associations, and common behaviours that all team types inherit. <code>Team</code> is intentionally abstract — it is never meant to be instantiated directly in production or test code. All functional teams that appear in the application must be concrete instances of one of the three subclasses. This design enforces a clean separation between shared infrastructure and specific business logic, and it means that any attempt to create a raw <code>Team</code> object should be treated as a programming error.<span class="ref-sup">[1]</span>
</p>

<div class="warn">
<strong>Constraint:</strong> Instantiating <code>Team</code> directly is a programming error. The test suite must explicitly verify that this constraint is honoured.
</div>

<h3 id="courseteam">CourseTeam</h3>
<p>
<code>CourseTeam</code> instances remain intact throughout a course, collaborating on all assignments within it. While some instructors opt not to use them, others find <code>CourseTeam</code>s beneficial, especially in Team-Based Learning environments. These teams can be converted into <code>AssignmentTeam</code>s, and vice versa, as instructional needs change.<span class="ref-sup">[1]</span>
</p>
<p>
A student may only be added to a <code>CourseTeam</code> if they are a participant in the associated course. No user should appear on more than one course team within the same course.
</p>

<h3 id="assignmentteam">AssignmentTeam</h3>
<p>
<code>AssignmentTeam</code> instances are formed specifically for individual assignments. Membership is restricted to users who are already participants in the associated assignment. The class is the direct superclass of <code>MentoredTeam</code> and participates in the bidirectional conversion relationship with <code>CourseTeam</code>.
</p>

<h3 id="mentoredteam">MentoredTeam</h3>
<p>
When an assignment is configured to automatically assign mentors, teams are instantiated as <code>MentoredTeam</code> — a subclass of <code>AssignmentTeam</code> with a designated mentor guiding the group. The mentor is identified not by a system role but by a <em>duty</em> attribute on the team membership record (see <a href="#duty-vs-role">§ Duty vs. role distinction</a>).
</p>


<h2 id="duty-vs-role">Duty vs. role distinction</h2>

<p>
A critical design point of the Expertiza platform is the separation between a user's <em>role</em> and their <em>duty</em> within a team. The current system's incorrect implementation of <code>MentoredTeam</code> conflates these two concepts; the corrected implementation must use <em>duty</em> exclusively when identifying the mentor participant.<span class="ref-sup">[1]</span>
</p>

<div class="compare-box">
<div class="col-head">Role</div>
<div class="col-head">Duty</div>
<div class="col-body">
A system-level permission level assigned to a user account.<br><br>
<strong>Examples:</strong> <code>Instructor</code>, <code>TeachingAssistant</code>, <code>Student</code>
</div>
<div class="col-body">
A function assigned to a user <em>within a specific team</em> for a specific assignment.<br><br>
<strong>Examples:</strong> <code>Submitter</code>, <code>Reader</code>, <code>Reviewer</code>, <code>Mentor</code>
</div>
</div>

<p>
The incorrect implementation checked whether a participant held the role of <code>Mentor</code> at the system level. This was incorrect because a mentor is not a privileged system account — they are an ordinary user who has been assigned the duty of <code>Mentor</code> on a particular <code>MentoredTeam</code>. The corrected implementation queries the <code>duty</code> attribute of the team participant record rather than the <code>role</code> attribute of the user.
</p>


<h2 id="membership">Membership rules</h2>

<p>A core correctness requirement of the entire hierarchy is that team membership must always be grounded in valid participation:<span class="ref-sup">[1]</span></p>

<table class="wiki-table">
<thead>
<tr>
<th>Rule</th>
<th>Applies to</th>
<th>Enforcement</th>
</tr>
</thead>
<tbody>
<tr>
<td>A student may only be added if they are a participant in the associated course.</td>
<td><code>CourseTeam</code></td>
<td>Model validation; raises error on violation</td>
</tr>
<tr>
<td>A student may only be added if they are a participant in the associated assignment.</td>
<td><code>AssignmentTeam</code>, <code>MentoredTeam</code></td>
<td>Model validation; raises error on violation</td>
</tr>
<tr>
<td>No user may appear on multiple course teams within the same course.</td>
<td><code>CourseTeam</code></td>
<td>Uniqueness constraint at model and DB level</td>
</tr>
<tr>
<td>No user may appear on multiple assignment teams within the same assignment.</td>
<td><code>AssignmentTeam</code>, <code>MentoredTeam</code></td>
<td>Uniqueness constraint at model and DB level</td>
</tr>
<tr>
<td>Team size must not exceed the configured maximum capacity.</td>
<td>All subclasses</td>
<td>Rejected with error before save</td>
</tr>
</tbody>
</table>


<h2 id="mentored-impl">MentoredTeam implementation</h2>

<p>
The corrected <code>MentoredTeam</code> implementation locates the mentor participant by querying the <code>duty</code> attribute of team member records, not the system-level <code>role</code> of the associated user. A representative model method looks as follows:
</p>

<pre><code># app/models/mentored_team.rb
class MentoredTeam < AssignmentTeam
# Returns the TeamMember record whose duty is 'Mentor'.
def mentor
team_members.find_by(duty: 'Mentor')
end

# Assigns a participant as the team mentor by setting their duty.
def assign_mentor!(user)
member = team_members.find_by(user: user)
raise ArgumentError, 'User is not a member of this team' unless member
member.update!(duty: 'Mentor')
end
end</code></pre>

<div class="note">
<strong>Note:</strong> Earlier versions of this class called <code>user.role == 'Mentor'</code>, which tested a system-level permission and incorrectly excluded ordinary students serving as mentors. The corrected query is <code>team_members.find_by(duty: 'Mentor')</code>.
</div>


<h2 id="testing">Test coverage (RSpec)</h2>

<p>
Comprehensive RSpec tests are required to validate the hierarchy. The test suite is organised into seven areas of concern.
</p>

<h3 id="test-model">Model validations</h3>
<p>
Tests confirm that required fields and uniqueness constraints are enforced. This includes verifying that a <code>Team</code> cannot be instantiated directly, that each subclass requires its parent association (course or assignment), and that enrollment-based membership rules reject non-participants.<span class="ref-sup">[1]</span>
</p>
<pre><code>RSpec.describe CourseTeam, type: :model do
it 'is invalid without an associated course' do
team = build(:course_team, course: nil)
expect(team).not_to be_valid
end

it 'rejects a member not enrolled in the course' do
team = create(:course_team)
student = create(:user) # no enrollment record
expect { team.add_member(student) }.to raise_error(ActiveRecord::RecordInvalid)
end
end</code></pre>

<h3 id="test-assoc">Association integrity</h3>
<p>
Tests verify that teams are correctly linked to their parent course or assignment and that membership records are properly scoped. For example, querying a team's members must not leak records belonging to teams in other courses or assignments.
</p>

<h3 id="test-subclass">Subclass-specific behaviour</h3>
<p>
This section covers two areas unique to the hierarchy design:
</p>
<ul>
<li><strong>Bidirectional conversion:</strong> A <code>CourseTeam</code> can be converted to an <code>AssignmentTeam</code> and vice versa, with member records preserved across the conversion.</li>
<li><strong>Mentor assignment in <code>MentoredTeam</code>:</strong> Tests confirm that <code>assign_mentor!</code> sets the correct <code>duty</code> value, that <code>mentor</code> returns the right participant, and that querying <code>duty</code> (not <code>role</code>) is the mechanism used.</li>
</ul>
<pre><code>RSpec.describe MentoredTeam, type: :model do
it 'identifies the mentor by duty, not by role' do
team = create(:mentored_team)
student = create(:user, role: 'Student') # system role is Student
create(:team_member, team: team, user: student, duty: 'Mentor')

expect(team.mentor.user).to eq student
end
end</code></pre>

<h3 id="test-capacity">Capacity and size limits</h3>
<p>
Tests ensure that teams cannot exceed their configured maximum member count, and that appropriate errors are returned when this limit is breached.
</p>
<pre><code>it 'rejects a member when the team is at maximum capacity' do
team = create(:assignment_team, max_members: 2)
create_list(:team_member, 2, team: team)
extra = create(:enrolled_user, assignment: team.assignment)
expect { team.add_member(extra) }.to raise_error(TeamFullError)
end</code></pre>

<h3 id="test-edge">Edge cases</h3>
<p>
Edge-case tests cover the following scenarios:
</p>
<ul>
<li>Performing operations on a team with zero members.</li>
<li>Attempting to add an already-enrolled member to the same team (duplicate membership).</li>
<li>Creating teams for assignments that have no participants yet.</li>
</ul>

<h3 id="test-auth">Controller authorization</h3>
<p>
Tests for <code>TeamsController</code> verify the correct role-based access policy:
</p>
<ul>
<li><strong>Students</strong> are blocked from viewing other teams.</li>
<li><strong>Mentors</strong> are restricted to their own mentored teams.</li>
<li><strong>Instructors</strong> have unrestricted access to all teams.</li>
</ul>
<pre><code>describe 'GET #index' do
context 'when the current user is a student' do
before { sign_in create(:student) }
it 'is forbidden from viewing other teams' do
get :index, params: { assignment_id: assignment.id }
expect(response).to have_http_status(:forbidden)
end
end
end</code></pre>

<h3 id="test-http">HTTP response codes</h3>
<p>
Tests confirm that unauthorized access attempts return appropriate HTTP status codes — specifically <code>403 Forbidden</code> — rather than silently succeeding or returning a <code>500 Internal Server Error</code>.<span class="ref-sup">[1]</span>
</p>

<table class="wiki-table">
<thead>
<tr>
<th>Actor</th>
<th>Action</th>
<th>Expected HTTP status</th>
</tr>
</thead>
<tbody>
<tr>
<td>Student (not on team)</td>
<td>View another team's details</td>
<td><code>403 Forbidden</code></td>
</tr>
<tr>
<td>Mentor (wrong team)</td>
<td>Access a MentoredTeam they do not mentor</td>
<td><code>403 Forbidden</code></td>
</tr>
<tr>
<td>Instructor</td>
<td>Any team action</td>
<td><code>200 OK</code></td>
</tr>
<tr>
<td>Unauthenticated user</td>
<td>Any team action</td>
<td><code>401 Unauthorized</code></td>
</tr>
</tbody>
</table>


<h2 id="references">References</h2>
<div class="references">
<ol>
<li>Expertiza project documentation — <em>Teams hierarchy testing</em>. Mentor: Vihar Manojkumar Shah. Internal specification document.</li>
<li>Fowler, M. (2002). <em>Patterns of Enterprise Application Architecture</em>. Addison-Wesley. (Single Table Inheritance pattern.)</li>
<li>Rails Guides — <em>Active Record Associations</em>. <a href="https://guides.rubyonrails.org/association_basics.html">guides.rubyonrails.org</a></li>
<li>RSpec Documentation — <em>RSpec Rails</em>. <a href="https://rspec.info/documentation/6.0/rspec-rails/">rspec.info</a></li>
</ol>
</div>


<div class="categories">
<strong>Categories:</strong>
<a href="#">Software design patterns</a> ·
<a href="#">Ruby on Rails</a> ·
<a href="#">Peer review systems</a> ·
<a href="#">Object-oriented programming</a> ·
<a href="#">Team-Based Learning</a> ·
<a href="#">RSpec</a>
</div>

</div>
</body>
</html>

CSC/ECE 517 Spring 2026

2026-03-29T23:48:23Z

Awainga:

* [[CSC/ECE 517 Spring 2026 - E2602. Reimplement student task view]]
* [[CSC/ECE 517 Spring 2026 - E2604. Finish Password Resets]]
* [[CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing]]