Testing
Testing Utilities
Import the test module, tenant context helper, and isolation assertion from @nestarc/tenancy/testing.
import { TestTenancyModule, withTenant, expectTenantIsolation } from '@nestarc/tenancy/testing';
// 1. Use TestTenancyModule in unit/integration tests (no middleware or guard)
const module = await Test.createTestingModule({
imports: [TestTenancyModule.register()],
providers: [MyService],
}).compile();
// 2. Run code in a tenant context
const result = await withTenant('tenant-1', () => service.findAll());
// 3. Use the tenancy-extended model delegate against seeded PostgreSQL fixtures.
await expectTenantIsolation(tenancyPrisma.user, tenantAId, tenantBId, {
tenantIdField: 'tenantId', // Prisma field name; the default is 'tenant_id'
});withTenant() establishes context only; it does not authenticate a caller, run middleware/guards, or install database policies. expectTenantIsolation() reads both tenant scopes concurrently and rejects rows whose tenant field differs from the queried tenant. It throws if both scopes return no rows; seed fixtures for both tenants and separately assert their expected records so an empty scope cannot hide a setup error. Use the non-owner, NOBYPASSRLS runtime role and a client configured with the tenancy extension.
Event System
Optional integration with @nestjs/event-emitter. Install the package and import EventEmitterModule:
import { EventEmitterModule } from '@nestjs/event-emitter';
import { TenancyEvents } from '@nestarc/tenancy';
@Module({
imports: [
EventEmitterModule.forRoot(),
TenancyModule.forRoot({ tenantExtractor: 'x-tenant-id' }),
],
})
export class AppModule {}
// Listen for events anywhere in your app
@Injectable()
class TenantLogger {
@OnEvent(TenancyEvents.RESOLVED)
handleResolved({ tenantId }: { tenantId: string }) {
console.log(`Tenant resolved: ${tenantId}`);
}
}Events: tenant.resolved, tenant.not_found, tenant.validation_failed, tenant.context_bypassed, tenant.cross_check_failed.
If @nestjs/event-emitter is not installed, events are silently skipped — no errors.
OpenTelemetry
Optional integration with @opentelemetry/api. Install the package to enable automatic tenant context in traces:
npm install @opentelemetry/apiTenancyModule.forRoot({
tenantExtractor: 'X-Tenant-Id',
telemetry: {
spanAttributeKey: 'tenant.id', // default
createSpans: true, // create custom spans for tenant lifecycle
},
})When enabled, tenant.id is automatically added as a span attribute to the active span on every request. If createSpans is true, a tenant.resolved span is also created.
If @opentelemetry/api is not installed, telemetry is silently skipped — no errors.