A junior nurse should not be able to access every patient record in the hospital. A contractor should not be able to read internal financial reports. An employee logged in from an unrecognized device at 2AM probably should not be editing production configuration files.

Simple role-based systems handle obvious cases well. But as applications grow and access rules become more nuanced, those systems start to crack. You end up creating more and more specific roles, like finance_viewer, finance_viewer_us_only, finance_viewer_us_only_readonly, until the roles themselves become unmanageable.

Attribute-Based Access Control (ABAC) was designed to solve exactly this problem. It shifts from "what role does this user have?" to "what do we know about this user, this resource, and this situation?" and makes access decisions based on all of those factors together.

In this guide, you'll learn how ABAC works, how it evolved from earlier access control models, how policies are structured, how to implement it in code, and when to use it.

Table of Contents

• Prerequisites

• How Access Control Has Evolved

• What is Attribute-Based Access Control?

• The Four Building Blocks of ABAC

• How an ABAC Decision is Made

• How to Write ABAC Policies

• How to Implement ABAC in Code

• ABAC vs RBAC: When to Use Which

• Real-World Use Cases

• Enterprise ABAC Considerations

• Limitations and Challenges

• Conclusion

• Glossary

Prerequisites

To get the most from this article, you should have:

• A basic understanding of web authentication (logins, sessions, tokens)

• Familiarity with how users and resources relate in applications

• Some experience reading JavaScript or pseudocode

No prior knowledge of access control theory is required.

How Access Control Has Evolved

To understand why ABAC exists, it helps to understand what came before it and why each generation fell short.

Discretionary and Mandatory Access Control

Early access control models emerged from Department of Defense applications in the 1960s and 1970s. According to NIST Special Publication 800-162, these were Discretionary Access Control (DAC) and Mandatory Access Control (MAC).

In DAC, the owner of a resource decides who can access it. Think of a file on your computer where you choose who can read or edit it. In MAC, access is governed by a central authority using labels like "Classified" or "Top Secret." The system enforces these labels, not individual owners.

Both worked for their original purposes but didn't scale well to the complexity of modern networked systems.

Identity-Based Access Control and Access Control Lists

As networks grew, identity-based access control (IBAC) became common. The most familiar implementation is the Access Control List (ACL), a list of users or groups attached to a resource, specifying what each can do.

ACLs are simple and transparent, but they create a management burden as systems grow. Every new user needs to be added to every relevant list. Every permission change means hunting through lists across multiple resources. And when someone leaves the organization, you need to find and remove them everywhere.

Failure to do this consistently leads to users accumulating privileges they should no longer have.

Role-Based Access Control

Role-Based Access Control (RBAC) was a major step forward. Instead of assigning permissions directly to users, RBAC assigns them to roles. Users are then assigned roles. A hospital might have roles like nurse, doctor, admin, and billing_staff, each with different permissions.

This made administration much more manageable. Adding a new employee means assigning them appropriate roles. Removing an employee means removing their roles. Changing what nurses can do means updating the nurse role once.

RBAC became widely adopted and is still the right choice for many applications. But it has a structural weakness: as permission requirements become more granular, you have to create more specific roles. A nurse who can only see patients on their floor, only during their shift, or only for certain record types, needs a very specific role, or a combination of roles that interacts in complicated ways.

This proliferation is called "role explosion." The roles multiply until they are as difficult to manage as the individual permissions RBAC was supposed to replace.

Attribute-Based Access Control

ABAC emerged as a response to role explosion. Instead of assigning roles that bundle fixed permissions, ABAC evaluates the actual characteristics of the user, the resource, and the context at the moment of every access request.

A nurse gets access to a patient record not because they have the nurse role, but because their job title is "Nurse Practitioner," the patient is on their assigned floor, it's currently their shift, and the record type is within their scope of care. Change any of those facts, and the access decision changes accordingly.

As NIST SP 800-162 defines it, ABAC is:

"an access control method where subject requests to perform operations on objects are granted or denied based on assigned attributes of the subject, assigned attributes of the object, environment conditions, and a set of policies that are specified in terms of those attributes and conditions."

What is Attribute-Based Access Control?

ABAC is a logical access control model where every access decision is made by evaluating a set of rules against the current values of attributes. Nothing is pre-computed or cached in role assignments. Every time a user tries to do something, the system asks: given what we know about this user, this resource, and this moment, should this be allowed?

This makes ABAC highly precise and highly dynamic. Permissions don't accumulate over time. They don't need manual cleanup when someone's role changes. The system simply evaluates the current state of attributes every time.

The model is formally described in NIST's guide to ABAC as being capable of enforcing both Discretionary Access Control and Mandatory Access Control concepts, making it more expressive than models that only support one or the other.

Companies like Axiomatics, major government agencies, and large enterprises managing cross-organizational data sharing all rely on ABAC for its ability to scale security policies across complex environments.

The Four Building Blocks of ABAC

Every ABAC system is built from four types of information. Understanding these clearly is the key to understanding how ABAC works.

1. Subject Attributes

The subject is whoever or whatever is requesting access. This is usually a user, but it can also be a service, an application, or an automated system, what NIST calls a Non-Person Entity (NPE).

Subject attributes describe who the subject is:

user.jobTitle         = "Nurse Practitioner"
user.department       = "Cardiology"
user.clearanceLevel   = "Confidential"
user.employmentStatus = "Active"
user.location         = "Floor 3"
user.shiftActive      = true

These attributes are typically sourced from an identity provider, HR system, or user directory. They're facts about the user that can be used in policies.

2. Object Attributes (Resource Attributes)

The object is whatever the subject is trying to access. This could be a file, a database record, an API endpoint, a service, or any other protected resource.

Object attributes describe what the resource is:

record.type           = "PatientMedical"
record.floor          = "Floor 3"
record.sensitivity    = "High"
record.owner          = "Dr. Williams"
record.department     = "Cardiology"

Object attributes are typically assigned when a resource is created and updated throughout its lifecycle. They're facts about the resource that determine who should be able to access it.

3. Action Attributes

The action is what the subject is trying to do to the object. Common actions include read, write, edit, delete, copy, execute, and share.

In many ABAC implementations, the action itself has attributes:

action.type           = "read"
action.bulk           = false

Policies can restrict which actions are allowed independently of the other attributes. A user might be able to read a document but not delete it, even if all their other attributes match.

4. Environment Conditions

Environment conditions are contextual factors that don't belong to either the subject or the object, but that should influence the access decision. NIST describes these as "dynamic factors, independent of subject and object, that may be used as attributes at decision time to influence an access decision."

Examples include:

environment.time           = "14:30"
environment.dayOfWeek      = "Wednesday"
environment.userLocation   = "Corporate Office"
environment.ipAddress      = "192.168.1.10"
environment.deviceStatus   = "compliant"
environment.threatLevel    = "low"

Environment conditions are what make ABAC truly dynamic. The same user, the same resource, and the same action might be allowed during business hours on a trusted device but denied at midnight from an unknown IP address.

How an ABAC Decision is Made

When a subject tries to perform an action on an object, the ABAC system runs through a specific process:

Step 1: Collect Attributes

The system gathers current attributes for the subject, object, action, and environment. This might involve querying a user directory, reading resource metadata, and checking current time and location.

Step 2: Find Applicable Policies

The system identifies which policies apply to this particular request. A request to read a patient record might have several policies that apply: one about clinical staff access, one about after-hours access, and one about record sensitivity levels.

Step 3: Evaluate Each Policy

Each applicable policy evaluates the collected attributes and returns permit or deny.

Step 4: Reconcile Conflicts

If multiple policies apply and they conflict, the system uses predefined combining rules. Common approaches are "deny overrides" (if any policy says deny, the request is denied) or "permit overrides" (if any policy says permit, the request is permitted).

Step 5: Enforce the Decision

The system grants or denies access based on the final decision.

This process happens every time an access request is made. There's no caching of role assignments or pre-computed permission tables. The decision reflects the current state of all attributes at the moment of the request.

How to Write ABAC Policies

Policies are the logic at the heart of ABAC. They're written as conditional rules that reference attributes. A well-written policy reads like a business rule, because that's exactly what it is.

Simple Boolean Policy

The most basic form evaluates whether certain attributes match:

// Policy: Only active employees can access internal resources
function canAccessInternalResource(user) {
  return user.employmentStatus === "Active";
}

What this does: Checks a single attribute, employment status, before allowing access. Any inactive, suspended, or terminated user is denied, regardless of their roles or past access history.

Multi-Attribute Policy

Real policies typically combine multiple attributes:

// Policy: A nurse can read a patient record
// if the patient is on their assigned floor
// and during their active shift

function canReadPatientRecord(user, record, environment) {
  const isNurse = user.jobTitle === "Nurse Practitioner";
  const isAssignedFloor = user.assignedFloor === record.floor;
  const isActiveDuty = user.shiftActive === true;

  return isNurse && isAssignedFloor && isActiveDuty;
}

What this does: Combines three conditions using AND logic. All three must be true for access to be granted. Change the nurse's floor assignment, and they immediately lose access to records on the previous floor, without any manual intervention.

Environment-Aware Policy

Adding environment conditions makes policies context-sensitive:

// Policy: Users can only access sensitive financial records
// during business hours from the corporate network

function canAccessSensitiveFinancialRecord(user, record, environment) {
  const isFinanceStaff = user.department === "Finance";
  const isHighSensitivity = record.sensitivity === "High";
  
  // If this is a high-sensitivity record, apply time and location controls
  if (isHighSensitivity) {
    const currentHour = new Date(environment.timestamp).getHours();
    const isBusinessHours = currentHour >= 9 && currentHour < 17;
    const isCorporateNetwork = environment.ipRange === "corporate";

    return isFinanceStaff && isBusinessHours && isCorporateNetwork;
  }

  // Lower sensitivity records only require finance department membership
  return isFinanceStaff;
}

What this does: Applies stricter controls to higher-sensitivity resources. The same user gets access to low-sensitivity records at any time, but high-sensitivity records require them to be on the corporate network during business hours. The policy logic mirrors the actual business rule: sensitive data needs more protection.

Ownership-Based Policy

ABAC can also implement discretionary ownership rules:

// Policy: A user can edit a document
// if they own it, or if they have editor permissions
// and the document isn't locked

function canEditDocument(user, document, action) {
  const isOwner = document.ownerId === user.id;
  const hasEditorPermission = user.permissions.includes("document.edit");
  const isUnlocked = document.status !== "locked";

  return (isOwner || hasEditorPermission) && isUnlocked;
}

What this does: Combines ownership (an attribute of the relationship between user and document) with explicit permissions and resource state. An editor can't edit a locked document even if they have the edit permission. An owner can edit their own documents but not locked ones.

How to Implement ABAC in Code

Let's build a simple ABAC evaluation engine that puts these pieces together.

Step 1: Define the Attribute Structure

First, define clear data structures for your attributes:

// A user (subject) requesting access
const user = {
  id: "user-123",
  name: "Sarah Chen",
  department: "Cardiology",
  jobTitle: "Nurse Practitioner",
  clearanceLevel: 2,
  assignedFloor: "Floor 3",
  shiftActive: true,
  employmentStatus: "Active"
};

// A resource (object) being accessed
const patientRecord = {
  id: "record-456",
  type: "PatientMedical",
  floor: "Floor 3",
  sensitivity: 2,
  ownerId: "doctor-789",
  department: "Cardiology"
};

// Environment conditions
const environment = {
  timestamp: new Date().toISOString(),
  ipAddress: "10.0.1.25",
  ipRange: "corporate",
  deviceCompliant: true
};

Step 2: Write Policy Functions

Write individual policies as pure functions that take attributes and return boolean values:

// policies/patientRecord.js

// Policy 1: User must be active and clinical staff
function isClinicalStaff(user) {
  const clinicalTitles = [
    "Nurse Practitioner",
    "Physician",
    "Resident",
    "Medical Assistant"
  ];
  return (
    user.employmentStatus === "Active" &&
    clinicalTitles.includes(user.jobTitle)
  );
}

// Policy 2: Record must be within the user's assigned area
function isAssignedToRecord(user, record) {
  return (
    user.department === record.department &&
    user.assignedFloor === record.floor
  );
}

// Policy 3: User must be on active shift
function isOnActiveShift(user) {
  return user.shiftActive === true;
}

// Policy 4: High-sensitivity records require compliant devices
function meetsDeviceRequirements(record, environment) {
  if (record.sensitivity >= 3) {
    return environment.deviceCompliant === true;
  }
  return true; // No device requirement for lower sensitivity
}

What this does: Each policy is a small, focused function. This makes policies easy to test individually, easy to read, and easy to reuse across different access decisions. A policy for "is this user clinical staff" can be applied to many different resource types.

Step 3: Build an Evaluation Engine

Combine your policies into a decision engine:

// abac/engine.js

function evaluateAccess(user, resource, action, environment, policies) {
  // Collect all policy results
  const results = policies.map(policy => {
    try {
      return policy(user, resource, action, environment);
    } catch (error) {
      console.error(`Policy evaluation error: ${error.message}`);
      return false; // Fail closed: deny on error
    }
  });

  // Deny-overrides: if any policy denies, access is denied
  return results.every(result => result === true);
}

// Assemble policies for reading patient records
const readPatientRecordPolicies = [
  (user) => isClinicalStaff(user),
  (user, record) => isAssignedToRecord(user, record),
  (user) => isOnActiveShift(user),
  (user, record, action, environment) => meetsDeviceRequirements(record, environment)
];

// Make an access decision
const canRead = evaluateAccess(
  user,
  patientRecord,
  "read",
  environment,
  readPatientRecordPolicies
);

console.log(`Access ${canRead ? "granted" : "denied"}`);
// → Access granted (all conditions met)

What this does: The engine loops through each policy function, passing in the relevant attributes. If all policies return true, access is granted. If any returns false, access is denied. This is called "deny-overrides combining". The try-catch ensures that if a policy throws an error, access is denied rather than granted, following the security principle of fail-closed.

Step 4: Add Attribute Collection

In a real application, attributes come from multiple sources:

// attributes/collector.js

async function collectAttributes(userId, resourceId) {
  // Collect in parallel for performance
  const [user, resource, environment] = await Promise.all([
    fetchUserAttributes(userId),      // From identity provider or HR system
    fetchResourceAttributes(resourceId), // From resource metadata store
    collectEnvironmentConditions()    // Time, IP, device status
  ]);

  return { user, resource, environment };
}

async function fetchUserAttributes(userId) {
  // This would query your user directory, LDAP, or identity provider
  const user = await userDirectory.findById(userId);
  const shift = await shiftService.getActiveShift(userId);
  
  return {
    ...user,
    shiftActive: shift !== null,
    assignedFloor: shift?.floor || null
  };
}

async function collectEnvironmentConditions() {
  return {
    timestamp: new Date().toISOString(),
    ipAddress: request.ip,
    ipRange: await networkService.classifyIP(request.ip),
    deviceCompliant: await deviceService.checkCompliance(request.deviceId)
  };
}

What this does: Attribute collection is separated from policy evaluation. This is an important design decision: it means you can test policies with any attribute values without needing real users or resources. It also means you can swap out the source of attributes (say, moving from an on-premise directory to a cloud identity provider) without changing your policies.

Step 5: Integrate with Your API

Use the evaluation engine in your API handlers:

// middleware/abac.js

function requireAccess(action, resourceType) {
  return async (req, res, next) => {
    try {
      const { user, resource, environment } = await collectAttributes(
        req.user.id,
        req.params.id
      );

      const policies = getPoliciesFor(resourceType, action);
      const allowed = evaluateAccess(user, resource, action, environment, policies);

      if (!allowed) {
        // Log the denial for audit purposes
        auditLog.record({
          userId: req.user.id,
          resourceId: req.params.id,
          action,
          decision: "denied",
          timestamp: new Date()
        });

        return res.status(403).json({ error: "Access denied" });
      }

      next();
    } catch (error) {
      // Fail closed: deny access on unexpected errors
      return res.status(403).json({ error: "Access denied" });
    }
  };
}

// Use in route definitions
app.get(
  "/patient-records/:id",
  authenticate(),                               // First verify identity
  requireAccess("read", "patientRecord"),       // Then evaluate ABAC
  patientRecordController.getById               // Then handle the request
);

What this does: The ABAC check lives in middleware that runs between authentication and the route handler. Authentication establishes who the user is. ABAC decides whether that user can do what they're trying to do. This separation keeps authorization logic out of your business logic.

ABAC vs RBAC: When to Use Which

RBAC isn't obsolete. It's genuinely the right choice for many applications. The question is which model fits your specific access requirements.

RBAC Strengths

RBAC is simple to understand, simple to implement, and simple to audit. If you can describe your access requirements as a list of roles with fixed permissions, RBAC works well. Most SaaS applications start with RBAC and it serves them fine for years.

A typical RBAC check looks like:

// Simple RBAC: does the user have the required role?
function canAccess(user, requiredRole) {
  return user.roles.includes(requiredRole);
}

It's fast, clear, and easy to debug. When something goes wrong, you check which roles the user has and which roles the resource requires.

Where RBAC Breaks Down

RBAC struggles when permissions need to depend on factors that aren't captured by a role. If you need to express "finance managers can view financial records, but only for their own region, and only during business hours," you're outside what a role alone can express cleanly.

You either need an extremely specific role (finance_manager_us_east_business_hours) that creates the role explosion problem, or you add conditional logic to your application code that effectively recreates ABAC, just in a less organized way.

RBAC vs ABAC Comparison

Combining Both Models

RBAC and ABAC work well together. A common pattern is to use RBAC for coarse-grained access control (which sections of your application can this user see?) and ABAC for fine-grained control within those sections (which specific records can they access?).

For example, a role might grant access to the patient records section of a hospital system. Within that section, ABAC policies determine which specific records a user can view or edit based on their department, assigned floor, and active shift.

Real-World Use Cases

Healthcare Records Management

Healthcare is one of the clearest examples of why ABAC matters. Patient privacy regulations require precise access control, and patient care requires that the right staff can access records quickly when they need them.

An ABAC policy in a hospital might allow a nurse to view a patient's record only when:

1. the patient is currently admitted to the nurse's assigned floor,

2. the nurse is on an active shift,

3. the access occurs from within the hospital network,

4. and the record type is within the nurse's care scope.

According to WorkOS's ABAC analysis, in emergency situations ABAC systems can automatically expand access rights. For example, an ER doctor automatically gains broader access to patient records to provide immediate care, with this access being time-bound and closely monitored.

All of these rules would require dozens of roles in an RBAC system, and those roles would still struggle to handle the emergency access scenario dynamically.

Corporate Data Access

Large enterprises typically have employees across departments, roles, locations, and clearance levels who need different views of the same underlying data. A document might be accessible to finance managers in the US region during business hours, accessible to executives globally at any time, but inaccessible to contractors entirely.

ABAC expresses all of these rules in policies. As employees change departments, go on leave, or change roles, their attributes update in the identity system and their access changes automatically, with no manual ACL updates required.

Government and Classified Information

The US federal government's adoption of ABAC is described in NIST SP 800-162, which was developed to address the Federal Identity, Credential, and Access Management (FICAM) requirements. Federal agencies deal with information shared across organizational boundaries, with varying classification levels and need-to-know requirements.

ABAC allows an analyst in one agency to access information from another agency without requiring the second agency to pre-provision an account for them. The analyst's clearance attributes, organizational affiliation, and project assignments are evaluated against the resource's classification and access rules at the time of the request.

Multi-Tenant SaaS Applications

SaaS applications that serve multiple organizations need to ensure strict data isolation between tenants while supporting complex permission structures within each tenant.

ABAC handles this naturally. A resource attribute like record.tenantId is evaluated against the user attribute user.tenantId, and no cross-tenant access is possible through policy. Within a tenant, ABAC supports as much complexity as the tenant's policies require.

Enterprise ABAC Considerations

Deploying ABAC at enterprise scale introduces several challenges that don't exist in smaller implementations.

Policy Administration

Policies need to be authored, reviewed, tested, and deployed. According to NIST SP 800-162, this requires a Policy Administration Point (PAP), an interface for creating and managing policies. Without proper tooling, policies become difficult to audit and maintain.

In practice, this means treating policies like code: version control, code review, and automated testing.

Attribute Quality and Freshness

ABAC is only as good as the attributes it evaluates. If user attributes are stale, for example, for a user who changed departments but whose directory entry hasn't been updated, the access decisions will be wrong.

NIST warns that "attributes that are not refreshed as often will ultimately be less secure than attributes that are refreshed in real time." Building reliable attribute pipelines from authoritative sources is often the hardest part of ABAC deployment.

Performance

Evaluating policies on every request has a performance cost. Each evaluation may require fetching attributes from multiple sources. To manage this, many implementations use attribute caching, but caching introduces the staleness problem described above.

The solution is to cache with appropriate TTLs (time-to-live values) based on how quickly each attribute type can change. A user's department changes rarely and can be cached for hours. A user's active shift status might change every 8 hours and needs a shorter cache. Real-time location might not be cacheable at all.

Audit Logging

Because ABAC makes decisions dynamically, auditing requires logging the attributes used in each decision, not just the decision itself. A log entry that says "access denied" is only useful if it also captures why access was denied and which attributes failed to satisfy which policies.

NIST notes that without tracking attribute values at decision time, accountability requirements can't be met.

Limitations and Challenges

ABAC is powerful, but it's not the right solution for every access control problem. It's worth being honest about its limitations before committing to an implementation.

Complexity: According to NIST SP 800-162, "an ABAC system is more complicated, and therefore more costly to implement and maintain, than simpler access control systems." The flexibility that makes ABAC powerful also makes it harder to reason about. A user asking "why can't I access this?" requires examining all the attributes that were evaluated and which conditions weren't met.

Policy Conflicts: In complex systems with many policies, conflicts between policies can occur. Two policies might individually seem correct but together produce unexpected results. Resolving these conflicts requires clear precedence rules and careful policy design.

Attribute Management Overhead: Maintaining accurate attributes across large user populations requires investment in identity infrastructure. Attributes from different systems need to be normalized, validated, and kept synchronized. As NIST describes it, organizations need an entire attribute management infrastructure, not just a policy engine.

Testing is Hard: Because access depends on the combination of potentially dozens of attributes, testing edge cases comprehensively requires thought. A policy that works correctly for typical cases might behave unexpectedly for unusual attribute combinations.

Not Always Worth the Investment: For applications with straightforward access requirements, ABAC introduces unnecessary complexity. If your needs can be expressed cleanly as a set of roles with fixed permissions, RBAC is the better choice.

Conclusion

Attribute-Based Access Control represents a genuine evolution in how applications manage authorization. Rather than maintaining ever-growing lists of roles and permissions, ABAC evaluates the actual characteristics of users, resources, and context at the moment of every request.

It solves the role explosion problem that plagues complex RBAC implementations. It enables access rules that reflect real business policies rather than technical approximations of them. It handles dynamic scenarios, emergencies, time-based restrictions, and cross-organizational access that are difficult or impossible to express with static roles.

But ABAC isn't universally better. It's more complex to build, harder to debug, and requires investment in attribute management infrastructure that simpler models don't need. Many applications are well-served by RBAC, and some use RBAC and ABAC together.

The right question isn't "should I use ABAC?" It's "are my access requirements complex enough that the investment in ABAC pays off?" If your access rules change frequently, depend on resource or environment context, or need to scale across organizational boundaries, ABAC is worth serious consideration.

Start by identifying where your current access control model is breaking down. If you're creating roles to represent every edge case, if you're writing conditional logic inside route handlers that checks specific attribute values, or if users are accumulating permissions they should no longer have, those are signals that a more expressive model would help.

ABAC is the tool for when roles aren't enough.

Glossary

ABAC (Attribute-Based Access Control): An access control method where authorization decisions are made by evaluating policies against the attributes of subjects, objects, actions, and environment conditions. Defined by NIST as the approach where "subject requests to perform operations on objects are granted or denied based on assigned attributes."

Subject: The entity requesting access to a resource. Usually a human user, but can also be a service, automated process, or device. Also called the "requestor."

Object: The resource being protected, such as a file, database record, API endpoint, service, or any system resource whose access is managed by the ABAC system.

Attribute: A characteristic of a subject, object, action, or environment expressed as a name-value pair. For example, user.department = "Finance" or record.sensitivity = "High".

Subject Attributes: Properties describing the user or service making the request, such as job title, department, clearance level, or current location.

Object Attributes: Properties describing the resource being accessed, such as its type, owner, sensitivity level, or department.

Environment Conditions: Contextual factors independent of both subject and object that influence access decisions. Examples include time of day, day of week, IP address, device compliance status, or current threat level.

Policy: A rule or set of rules that evaluates attribute values to determine whether a specific access request should be permitted or denied. ABAC policies are typically written as logical conditions.

Policy Decision Point (PDP): The component of an ABAC system that evaluates policies and attributes to compute an access decision.

Policy Enforcement Point (PEP): The component that intercepts access requests and enforces the decisions made by the PDP.

Policy Information Point (PIP): The component that retrieves attribute values needed by the PDP to make decisions.

Policy Administration Point (PAP): The component that provides an interface for creating, testing, and managing policies.

RBAC (Role-Based Access Control): An access control model that assigns permissions to roles and users to roles. Simpler than ABAC but less expressive for complex, dynamic access requirements.

Role Explosion: The proliferation of increasingly specific roles in an RBAC system as access requirements become more granular, eventually making the roles as difficult to manage as individual permissions.

DAC (Discretionary Access Control): An access control model where resource owners control who can access their resources. Common in file systems.

MAC (Mandatory Access Control): An access control model where access is governed by a central authority using classification labels, independent of resource owner preferences.

ACL (Access Control List): A list associated with a resource that specifies which users or groups have which permissions. Common in identity-based access control systems.

Non-Person Entity (NPE): A subject that is not a human user, such as an automated service, application, or network device, that can request access to resources.

Attribute Caching: Storing previously retrieved attribute values to improve performance, at the cost of potentially using stale data for access decisions.

Deny-Overrides Combining: A policy combining rule where if any applicable policy returns deny, the overall decision is deny, regardless of other policies that may return permit.

Fail-Closed: A security design principle where unexpected errors or missing information result in access being denied rather than granted, reducing the risk of unauthorized access.

Source: Definitions adapted from NIST Special Publication 800-162, Guide to Attribute Based Access Control (ABAC) Definition and Considerations, January 2014 (with updates through August 2019).

Google Maps provides a $200 monthly credit, but beyond that, usage is billed per request. For applications like logistics, ride-hailing, or fleet tracking – where thousands of requests are made daily – costs can grow quickly depending on which APIs you use.

OpenStreetMap (OSM) offers a different approach. Instead of charging for access to map APIs, it provides free, open geographic data that you can build on.

In this guide, you'll learn what OpenStreetMap is, how it differs from Google Maps, and how to integrate it into a React application using Leaflet.

What We'll Cover:

1. What is OpenStreetMap?

2. Why Choose OpenStreetMap Over Google Maps?

3. Understanding the OpenStreetMap Ecosystem

   • Data Layer (OpenStreetMap)

   • Rendering Layer (Leaflet, MapLibre)

   • Services Layer

   • How Everything Works Together

4. How to Integrate OpenStreetMap in React with Leaflet

5. How to Add Geocoding with Nominatim

6. Advanced Features

7. When to Choose OpenStreetMap vs Google Maps

8. Wrapping Up

What is OpenStreetMap?

OpenStreetMap is a free, open, and community-driven map of the world. Anyone can contribute to it, and anyone can use it.

Unlike Google Maps, which gives access through controlled APIs, OpenStreetMap gives you access to the underlying geographic data itself.

This data is structured in three main ways:

1. Nodes: single points (for example, a bus stop or a tree)

2. Ways: lines or shapes made up of nodes (like roads or buildings)

3. Relations: groups of nodes and ways that define more complex things (like routes or boundaries)

Each of these elements includes tags (key-value pairs), such as:

highway=residential
name=Allen Avenue

So instead of just displaying a map, OpenStreetMap lets you work with structured geographic data.

The Open Database License (ODbL)

OpenStreetMap data is licensed under the ODbL. This means:

• You can use it for commercial or personal projects

• You must give proper attribution

This makes it especially useful for developers who want clarity around data ownership.

Why Choose OpenStreetMap Over Google Maps?

Cost

OpenStreetMap data is free to use. But it's important to be precise here: OpenStreetMap removes licensing costs, but not infrastructure costs.

You may still need to pay for:

• Tile hosting

• Geocoding services

• Routing engines

Control

With Google Maps, you can't modify the data, and you rely entirely on Google's APIs

But with OpenStreetMap, you can download and store the data, modify it, and build custom solutions on top of it.

Customization

OpenStreetMap gives you more flexibility:

• You control how maps are rendered

• You can choose or build your own map styles

• You can create domain-specific maps

Adoption

OpenStreetMap is widely used. Companies like Meta and Microsoft contribute to it, and many platforms rely on it directly or indirectly.

This shows that the ecosystem is mature and reliable.

Understanding the OpenStreetMap Ecosystem

A common mistake is to think that OpenStreetMap works like a single API. It doesn't.

Instead, it works as a set of layers, where each layer handles a different responsibility.

Data Layer (OpenStreetMap)

This is the foundation. It contains all the raw geographic data:

• Roads

• Buildings

• Landmarks

• Boundaries

This is what you are ultimately working with.

Rendering Layer (Leaflet, MapLibre)

Raw data isn't visual. It needs to be turned into something users can see.

There are two main approaches:

1. Raster tiles (used by Leaflet): pre-rendered images

2. Vector tiles (used by MapLibre): raw geometry styled in the browser

Leaflet uses raster tiles by default, which makes it simple and fast to start with.

Services Layer

This is what makes your map interactive. Geocoding converts addresses into coordinates, while reverse geocoding converts coordinates into addresses.

Routing calculates directions between points, and tile servers provide the actual map visuals.

How Everything Works Together

When a user searches for a place:

1. The user enters a location

2. A geocoding service converts it into coordinates

3. The map updates its position

4. A tile server provides the visual map

Each part is separate, but they work together to create the full experience.

How to Integrate OpenStreetMap in React with Leaflet

Let's build a simple map.

Step 1: Create a React App

npm create vite@latest osm-app -- --template react
cd osm-app
npm install

Step 2: Install Dependencies

npm install leaflet react-leaflet
npm install --save-dev @types/leaflet

Step 3: Import Leaflet CSS

import 'leaflet/dist/leaflet.css';

This is required for the map to display correctly.

Step 4: Create a Map Component

import { MapContainer, TileLayer, Marker, Popup } from 'react-leaflet';

function Map() {
  const position = [51.505, -0.09]; // latitude, longitude

  return (
    <MapContainer
      center={position}
      zoom={13}
      style={{ height: '100vh' }}
    >
      <TileLayer
        attribution='&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
        url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"
      />
      <Marker position={position}>
        <Popup>Hello from OpenStreetMap</Popup>
      </Marker>
    </MapContainer>
  );
}

export default Map;

Let's break down the important parts here:

MapContainer initializes the map.

• center is where the map starts

• zoom is how close the view is

• style must include height, or the map won't show

TileLayer defines where the map visuals come from.

• {z} is the zoom level

• {x}, {y} are the tile coordinates

• {s} is the subdomain

Each tile is a small image (usually 256×256 pixels), and Leaflet combines them to form the full map.

Marker adds a point on the map at a specific coordinate.

Popup displays information when the marker is clicked.

Important note:

The default OpenStreetMap tile server:

https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png

is meant for learning, demos, and low-traffic apps. For production, you should use a dedicated provider or your own tile server.

How to Add Geocoding with Nominatim

Nominatim is OpenStreetMap's geocoding service. It allows you to convert addresses into coordinates and coordinates into readable locations.

Custom Hook for Geocoding

import { useState } from 'react';

export function useGeocoding() {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  const searchAddress = async (query) => {
    setLoading(true);
    setError(null);

    try {
      const response = await fetch(
        `https://nominatim.openstreetmap.org/search?q=${encodeURIComponent(query)}&format=json&limit=5`,
        {
          headers: {
            'User-Agent': 'YourAppName/1.0'
          }
        }
      );

      if (!response.ok) {
        throw new Error('Request failed');
      }

      const data = await response.json();
      setLoading(false);
      return data;
    } catch (err) {
      setError(err.message);
      setLoading(false);
      return [];
    }
  };

  return { searchAddress, loading, error };
}

In this code:

• useState manages loading and error states

• encodeURIComponent ensures safe URLs

• User-Agent is required by Nominatim

• response.json() converts response into usable data

Nominatim returns coordinates as strings, so you have to convert them before using them.

Important Usage Rules

The public Nominatim service:

• Allows about 1 request per second

• Requires proper identification

• May block excessive usage

You should debounce user input, cache results, and avoid repeated requests.

Creating a Search Component

The search component lets users type an address or place name and get matching locations via Nominatim. It includes a text input and a submit button.

When the form is submitted, it calls our searchAddress function (from the useGeocoding hook), which fetches up to 5 address results. These results are displayed below the input as clickable items.

When the user clicks a result, the component parses the returned latitude and longitude into numbers and passes them (along with a display name) up to the parent component via the onLocationSelect callback. This will allow the parent (for example, the map) to update its center based on the chosen location.

function SearchBox({ onLocationSelect }) {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState([]);
  const { searchAddress, loading } = useGeocoding();

  const handleSearch = async (e) => {
    e.preventDefault();
    if (!query.trim()) return;

    const data = await searchAddress(query);
    setResults(data);
  };

  const selectLocation = (result) => {
    onLocationSelect({
      lat: parseFloat(result.lat),
      lon: parseFloat(result.lon),
      name: result.display_name
    });
  };

  return (
    <div>
      <form onSubmit={handleSearch}>
        <input
          value={query}
          onChange={(e) => setQuery(e.target.value)}
          placeholder="Search location"
        />
        <button type="submit">
          {loading ? 'Searching...' : 'Search'}
        </button>
      </form>

      <div>
        {results.map((result) => (
          <div key={result.place_id} onClick={() => selectLocation(result)}>
            {result.display_name}
          </div>
        ))}
      </div>
    </div>
  );
}

Key concepts here:

• useState stores the current input (query) and the array of search results.

• e.preventDefault() stops the form submission from reloading the page.

• Calling searchAddress(query) fetches geocoding results from Nominatim.

• parseFloat() converts the returned lat/lon strings into JavaScript numbers before using them.

• onLocationSelect is a callback prop that sends the selected coordinates and name back to the parent component (for example to update the map).

Advanced Features

We can further extend the map app by adding more advanced functionality. For example:

Routing (OSRM, GraphHopper)

You can integrate turn-by-turn routing on your map. A common solution is to use a library like Leaflet Routing Machine, which supports OSRM out of the box and has plugins for GraphHopper. This adds a route UI control where users enter start and end points, and the library fetches a route from one of these engines to draw on the map.

Custom Tile Providers (Carto, MapTiler, and so on)

Instead of the standard tile.openstreetmap.org, you can use hosted tile services that offer OSM-based maps. For example, Carto and MapTiler both provide tile APIs (often with custom style options and higher usage limits).

Carto, MapTiler, and similar services are listed among the providers that allow free usage of OSM tiles. By using a custom tile provider, you gain flexibility in map design and avoid hitting the public server’s limits.

Vector Maps (MapLibre GL JS)

You can switch from raster tiles to vector tiles for even richer interactivity. Vector tiles send raw map data (geometries and attributes) to the client, which are then rendered in the browser. This allows dynamic styling and advanced features: for instance, you can change the map’s theme on the fly (for example, switch to a “dark mode” style at night) or highlight certain features like bike lanes more prominently.

Libraries like MapLibre GL JS (the open-source successor to Mapbox GL) can display OSM vector tiles with highly customizable styles and smooth zooming/rotation. This makes your map more responsive and adaptable to different use cases.

When to Choose OpenStreetMap vs Google Maps

Choose OpenStreetMap when:

• You need flexibility

• You want to reduce costs at scale

• You want control over data

Choose Google Maps when:

• You want an all-in-one solution

• You need features like Street View

• You want minimal setup

Wrapping Up

OpenStreetMap offers a powerful alternative to Google Maps for developers who need cost control, data ownership, and customization. While it requires understanding different components, the flexibility it provides is worth the learning curve.

In this tutorial, you’ll learn how to set up Vitest in a React project, write effective tests for your components and hooks, and understand the testing patterns that will help you build more reliable applications.

Table of Contents

• What is Vitest and Why Should You Use It?

• Prerequisites

• How to Set Up Vitest in Your React Project

• How to Write Your First Test

• How to Test React Components

• How to Test User Interactions

• How to Test Custom Hooks

• How to Mock API Calls

• Best Practices for Testing React Components

What is Vitest and Why Should You Use It?

Vitest is a testing framework built on top of Vite. It uses Vite’s development server and plugin pipeline to transform and load files during testing. This means your tests use the same configuration and plugins as your app (for example, the React plugin, TypeScript support,and so on), so you don’t need a separate build or compile step.

Vitest runs tests in parallel across worker threads for maximum speed, and it automatically enables an instant “watch” mode (similar to Vite’s HMR) that reruns only the tests related to changed files. Vitest also has first-class support for modern JavaScript out of the box: it handles ESM, TypeScript, and JSX natively via Vite’s transformer (powered by Oxc).

Because Vitest provides a Jest-compatible API, you can continue to use familiar testing libraries (for example, React Testing Library, jest-dom matchers, user-event, and so on) without extra setup.

In short, Vitest tightly integrates with your Vite-powered stack (or can even run standalone) and lets you plug in existing testing tools seamlessly.

Here is why Vitest has become popular in the React ecosystem:

• Speed: Vitest can run tests more than four times faster than Jest in many scenarios. This speed comes from Vite's fast Hot Module Replacement and efficient caching capabilities.

• Zero configuration: Unlike Jest, which required Babel integration, TSJest setup, and multiple dependencies, Vitest works out of the box. It reuses your existing Vite configuration, eliminating the need to configure a separate test pipeline.

• Native TypeScript support: Vitest handles TypeScript and JSX natively through ESBuild, with no additional configuration needed.

• Modern JavaScript: Vitest offers native support for ES modules out of the box, making it ideal for modern JavaScript stacks.

• Familiar API: If you know Jest, you already know most of Vitest. The API is intentionally compatible, making migration straightforward.

Prerequisites

To follow along with this tutorial, you should have:

• Basic knowledge of React and JavaScript

• Understanding of React Hooks

• Node.js installed (version 14 or higher)

• A React project created with Vite (or you can create one as we go)

How to Set Up Vitest in Your React Project

Let's start by creating a new React project with Vite and setting up Vitest.

Step 1: Create a React Project with Vite

If you don't have an existing project, create one with the following command:

npm create vite@latest my-react-app -- --template react
cd my-react-app
npm install

This creates a React project with Vite as the build tool.

Step 2: Install Vitest and Testing Dependencies

Install Vitest along with the React Testing Library and other necessary dependencies:

npm install --save-dev vitest @testing-library/react @testing-library/jest-dom @testing-library/user-event jsdom

Here's what each package does:

• vitest: The testing framework itself

• @testing-library/react: Provides utilities for testing React components

• @testing-library/jest-dom: Adds custom matchers for DOM assertions

• @testing-library/user-event: Simulates user interactions

• jsdom: Provides a DOM environment for testing

Step 3: Configure Vitest

Create a vitest.config.js file in your project root:

import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  test: {
    globals: true,
    environment: 'jsdom',
    setupFiles: './src/test/setup.js',
  },
});

Setting globals: true exposes the describe and it functions on the global object, so you don't need to import them in every test file. The environment: 'jsdom' setting tells Vitest to use jsdom for simulating a browser environment.

Step 4: Create the Test Setup File

Create a file at src/test/setup.js:

import { expect, afterEach } from 'vitest';
import { cleanup } from '@testing-library/react';
import '@testing-library/jest-dom';

afterEach(() => {
  cleanup();
});

The cleanup() function runs after each test to clean up the DOM, ensuring tests don't interfere with each other.

Step 5: Add Test Scripts

Add the following script to your package.json:

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "test": "vitest",
    "test:ui": "vitest --ui",
    "coverage": "vitest --coverage"
  }
}

Now you can run tests with npm test.

How to Write Your First Test

Let's write a simple test to make sure everything is working. Create a file called sum.test.js in your src directory:

import { expect, test } from 'vitest';

function sum(a, b) {
  return a + b;
}

test('adds 1 + 2 to equal 3', () => {
  expect(sum(1, 2)).toBe(3);
});

Run npm test and you should see your test pass. A test in Vitest passes if it doesn't throw an error.

How to Test React Components

Now let's test an actual React component. We'll start with a simple component and gradually build up to more complex scenarios.

Testing a Simple Component

Create a component called Greeting.jsx:

export function Greeting({ name }) {
  return (
    <div>
      <h1>Hello, {name}!</h1>
      <p>Welcome to our application</p>
    </div>
  );
}

Now create a test file Greeting.test.jsx:

import { render, screen } from '@testing-library/react';
import { Greeting } from './Greeting';

describe('Greeting Component', () => {
  it('should render the greeting with the provided name', () => {
    render(<Greeting name="Alice" />);

    const heading = screen.getByRole('heading', { level: 1 });
    expect(heading).toHaveTextContent('Hello, Alice!');
  });

  it('should render the welcome message', () => {
    render(<Greeting name="Bob" />);

    const paragraph = screen.getByText('Welcome to our application');
    expect(paragraph).toBeInTheDocument();
  });
});

The describe function groups related tests into a single describe block. Each it function contains one test case.

The render function from React Testing Library renders your component in a test environment. The screen object provides query methods to find elements in the rendered output.

Understanding Query Functions

React Testing Library provides three types of query functions: get, query, and find.

getBy queries: Throw an error if the element isn't found. Use these when you expect the element to be present.

const button = screen.getByRole('button', { name: /click me/i });

queryBy queries: Return null if the element isn't found. Use these when you want to assert that an element doesn't exist.

const errorMessage = screen.queryByText('Error');
expect(errorMessage).not.toBeInTheDocument();

findBy queries: Return a promise and wait for the element to appear. Use these for asynchronous operations.

const loadedData = await screen.findByText('Data loaded');

Testing a Counter Component

Let's test a more interactive component. Create Counter.jsx:

import { useState } from 'react';

export function Counter({ initialCount = 0 }) {
  const [count, setCount] = useState(initialCount);

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount(count + 1)}>Increment</button>
      <button onClick={() => setCount(count - 1)}>Decrement</button>
      <button onClick={() => setCount(0)}>Reset</button>
    </div>
  );
}

Create the test file Counter.test.jsx:

import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { Counter } from './Counter';

describe('Counter Component', () => {
  it('should render with initial count of 0', () => {
    render(<Counter />);

    expect(screen.getByText('Count: 0')).toBeInTheDocument();
  });

  it('should render with custom initial count', () => {
    render(<Counter initialCount={5} />);

    expect(screen.getByText('Count: 5')).toBeInTheDocument();
  });

  it('should increment count when increment button is clicked', async () => {
    const user = userEvent.setup();
    render(<Counter />);

    const incrementButton = screen.getByRole('button', { name: /increment/i });
    await user.click(incrementButton);

    expect(screen.getByText('Count: 1')).toBeInTheDocument();
  });

  it('should decrement count when decrement button is clicked', async () => {
    const user = userEvent.setup();
    render(<Counter initialCount={5} />);

    const decrementButton = screen.getByRole('button', { name: /decrement/i });
    await user.click(decrementButton);

    expect(screen.getByText('Count: 4')).toBeInTheDocument();
  });

  it('should reset count to 0 when reset button is clicked', async () => {
    const user = userEvent.setup();
    render(<Counter initialCount={10} />);

    const resetButton = screen.getByRole('button', { name: /reset/i });
    await user.click(resetButton);

    expect(screen.getByText('Count: 0')).toBeInTheDocument();
  });
});

In these Counter tests, we first use render(<Counter />) to mount the component in a virtual DOM. We then query the output using Testing Library’s screen object. For example, screen.getByText('Count: 0') finds the element displaying the initial count of 0, and expect(...).toBeInTheDocument() asserts that it is present. The getByText query will throw an error if the text isn’t found, immediately failing the test.

For interactive tests, we create a user with const user = userEvent.setup() and then call await user.click(...) on the increment/decrement/reset buttons. The userEvent.click method simulates a real user click (dispatching the sequence of events a browser would fire). We locate buttons by their accessible role and name (for example, getByRole('button', { name: /increment/i })), following best practices for accessible queries.

After each click, we assert that the DOM updates accordingly (for example, the count text changes to “Count: 1”). Using async/await with user.click ensures the test waits for any state changes. In this way, each test checks the user-visible behavior: that clicking the Increment button increases the count, the Decrement button decreases it, and the Reset button sets it back to zero, without depending on the component’s internal implementation.

How to Test User Interactions

User interactions are a critical part of testing React applications. The @testing-library/user-event library provides a more realistic simulation of user behaviour than simple event dispatching.

Testing Form Inputs

Create a LoginForm.jsx component:

import { useState } from 'react';

export function LoginForm({ onSubmit }) {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [error, setError] = useState('');

  const handleSubmit = (e) => {
    e.preventDefault();

    if (!email || !password) {
      setError('Both fields are required');
      return;
    }

    setError('');
    onSubmit({ email, password });
  };

  return (
    <form onSubmit={handleSubmit}>
      <div>
        <label htmlFor="email">Email</label>
        <input
          id="email"
          type="email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
        />
      </div>
      <div>
        <label htmlFor="password">Password</label>
        <input
          id="password"
          type="password"
          value={password}
          onChange={(e) => setPassword(e.target.value)}
        />
      </div>
      {error && <p role="alert">{error}</p>}
      <button type="submit">Log In</button>
    </form>
  );
}

Create the test file LoginForm.test.jsx:

import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { LoginForm } from './LoginForm';

describe('LoginForm Component', () => {
  it('should render email and password inputs', () => {
    render(<LoginForm onSubmit={() => {}} />);

    expect(screen.getByLabelText(/email/i)).toBeInTheDocument();
    expect(screen.getByLabelText(/password/i)).toBeInTheDocument();
  });

  it('should update input values when user types', async () => {
    const user = userEvent.setup();
    render(<LoginForm onSubmit={() => {}} />);

    const emailInput = screen.getByLabelText(/email/i);
    const passwordInput = screen.getByLabelText(/password/i);

    await user.type(emailInput, 'test@example.com');
    await user.type(passwordInput, 'password123');

    expect(emailInput).toHaveValue('test@example.com');
    expect(passwordInput).toHaveValue('password123');
  });

  it('should show error when form is submitted empty', async () => {
    const user = userEvent.setup();
    const mockSubmit = vi.fn();
    render(<LoginForm onSubmit={mockSubmit} />);

    const submitButton = screen.getByRole('button', { name: /log in/i });
    await user.click(submitButton);

    expect(screen.getByRole('alert')).toHaveTextContent('Both fields are required');
    expect(mockSubmit).not.toHaveBeenCalled();
  });

  it('should call onSubmit with form data when valid', async () => {
    const user = userEvent.setup();
    const mockSubmit = vi.fn();
    render(<LoginForm onSubmit={mockSubmit} />);

    await user.type(screen.getByLabelText(/email/i), 'test@example.com');
    await user.type(screen.getByLabelText(/password/i), 'password123');
    await user.click(screen.getByRole('button', { name: /log in/i }));

    expect(mockSubmit).toHaveBeenCalledWith({
      email: 'test@example.com',
      password: 'password123',
    });
  });
});

The LoginForm tests similarly use render and screen to interact with the component. We use screen.getByLabelText(/email/i) and screen.getByLabelText(/password/i) to find the input fields by their associated labels, mimicking how users identify form fields.

To simulate typing, we use await user.type(input, text), which sends real keyboard events to the input (via user-event). After typing, we assert the input’s value with expect(input).toHaveValue(...) (a custom matcher from jest-dom).

When submitting the form empty, clicking the Log In button triggers the form’s validation and displays an error message. We find this error by querying getByRole('alert') and check its text content. We also assert that the mock onSubmit handler was not called.

In the valid submission test, we fill both fields and click Log In; then expect(mockSubmit).toHaveBeenCalledWith({...}) verifies the submit handler received the correct { email, password } object.

These tests focus on user actions and outcomes: typing and clicking drive the form logic, and our assertions confirm the expected outputs (visible error text or the callback arguments).

How to Test Custom Hooks

Custom hooks encapsulate reusable logic, and they need testing just like components. React Testing Library provides a renderHook function specifically for this purpose.

Creating and Testing a Custom Hook

Create a custom hook useFetch.js:

import { useState, useEffect } from 'react';

export function useFetch(url) {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    const fetchData = async () => {
      try {
        setLoading(true);
        const response = await fetch(url);

        if (!response.ok) {
          throw new Error('Network response was not ok');
        }

        const json = await response.json();
        setData(json);
        setError(null);
      } catch (err) {
        setError(err.message);
        setData(null);
      } finally {
        setLoading(false);
      }
    };

    fetchData();
  }, [url]);

  return { data, loading, error };
}

Create the test file useFetch.test.js:

import { renderHook, waitFor } from '@testing-library/react';
import { useFetch } from './useFetch';

describe('useFetch Hook', () => {
  beforeEach(() => {
    global.fetch = vi.fn();
  });

  afterEach(() => {
    vi.restoreAllMocks();
  });

  it('should return loading state initially', () => {
    global.fetch.mockImplementation(() => 
      Promise.resolve({
        ok: true,
        json: async () => ({ data: 'test' }),
      })
    );

    const { result } = renderHook(() => useFetch('https://api.example.com/data'));

    expect(result.current.loading).toBe(true);
    expect(result.current.data).toBe(null);
    expect(result.current.error).toBe(null);
  });

  it('should return data when fetch succeeds', async () => {
    const mockData = { id: 1, title: 'Test Post' };

    global.fetch.mockImplementation(() =>
      Promise.resolve({
        ok: true,
        json: async () => mockData,
      })
    );

    const { result } = renderHook(() => useFetch('https://api.example.com/posts/1'));

    await waitFor(() => expect(result.current.loading).toBe(false));

    expect(result.current.data).toEqual(mockData);
    expect(result.current.error).toBe(null);
  });

  it('should return error when fetch fails', async () => {
    global.fetch.mockImplementation(() =>
      Promise.resolve({
        ok: false,
      })
    );

    const { result } = renderHook(() => useFetch('https://api.example.com/posts/1'));

    await waitFor(() => expect(result.current.loading).toBe(false));

    expect(result.current.data).toBe(null);
    expect(result.current.error).toBe('Network response was not ok');
  });
});

The renderHook function from React Testing Library renders custom hooks, and waitFor is used to wait for asynchronous state updates in the hook.

How to Mock API Calls

When testing components that make API calls, you don't want to hit real endpoints. Mocking ensures your tests are fast, reliable, and don't depend on network conditions.

Mocking with Vitest

Vitest doesn’t auto-mock modules like Jest does, so you need to manually mock them. Let's see how to mock an Axios call.

Create a PostsList.jsx component:

import { useState, useEffect } from 'react';
import axios from 'axios';

export function PostsList() {
  const [posts, setPosts] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    const fetchPosts = async () => {
      try {
        const response = await axios.get('https://api.example.com/posts');
        setPosts(response.data);
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    };

    fetchPosts();
  }, []);

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error: {error}</p>;

  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}

Create the test file PostsList.test.jsx:

import { render, screen, waitFor } from '@testing-library/react';
import axios from 'axios';
import { PostsList } from './PostsList';

vi.mock('axios');

describe('PostsList Component', () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });

  it('should display loading state initially', () => {
    axios.get.mockImplementation(() => new Promise(() => {}));
    render(<PostsList />);

    expect(screen.getByText('Loading...')).toBeInTheDocument();
  });

  it('should display posts when API call succeeds', async () => {
    const mockPosts = [
      { id: 1, title: 'First Post' },
      { id: 2, title: 'Second Post' },
    ];

    axios.get.mockResolvedValue({ data: mockPosts });
    render(<PostsList />);

    await waitFor(() => {
      expect(screen.queryByText('Loading...')).not.toBeInTheDocument();
    });

    expect(screen.getByText('First Post')).toBeInTheDocument();
    expect(screen.getByText('Second Post')).toBeInTheDocument();
  });

  it('should display error when API call fails', async () => {
    axios.get.mockRejectedValue(new Error('Network error'));
    render(<PostsList />);

    await waitFor(() => {
      expect(screen.queryByText('Loading...')).not.toBeInTheDocument();
    });

    expect(screen.getByText(/error/i)).toBeInTheDocument();
  });
});

In these tests, we verify specific UI states: the “loading” test checks that a loading indicator shows while data is being fetched, the “success” test confirms that post items render when the API returns data, and the “error” test makes sure an error message appears if the call fails.

We mock Axios by calling vi.mock('axios') and then using methods like mockResolvedValue(...) on axios.get to simulate a successful response (and mockRejectedValue(...) to simulate a failure). This kind of mocking isolates our tests from real network calls (making them fast and reliable) and lets us control exactly what data or error the hook receives.

We use await waitFor(...) to pause the test until those asynchronous updates complete before making assertions. Finally, we use screen.getByText(...) to find elements that should be present (it will throw an error if they’re missing) and screen.queryByText(...) to check that elements aren’t present (it returns null if the element is not in the DOM).

Mocking Specific Module Functions

Sometimes you only want to mock specific functions while keeping the rest of a module's behaviour intact. Here's how to do that:

vi.mock('date-fns', async () => {
  const original = await vi.importActual('date-fns');
  return {
    ...original,
    format: vi.fn(() => '2025-01-01'),
  };
});

In Vitest, you use vi.importActual to retain all original methods while mocking only the format method.

Best Practices for Testing React Components

Now that you know how to write tests, let's talk about how to write good tests.

Test User Behaviour, Not Implementation

Focus on testing what users see and do, not internal component details. If you refactor your component's implementation without changing its behaviour, your tests shouldn't break.

Bad test (testing implementation):

it('should set isOpen state to true', () => {
  const { result } = renderHook(() => useState(false));
  // Testing internal state directly
});

Good test (testing behaviour):

it('should show menu when button is clicked', async () => {
  const user = userEvent.setup();
  render(<Menu />);

  await user.click(screen.getByRole('button', { name: /menu/i }));
  expect(screen.getByRole('navigation')).toBeVisible();
});

Use Accessible Queries

React Testing Library encourages you to query elements the way users do. Prefer queries that mirror user interaction:

1. getByRole (best for interactive elements)

2. getByLabelText (for form fields)

3. getByPlaceholderText

4. getByText

5. getByTestId (last resort)

Keep Tests Simple and Focused

Each test should verify one thing. If your test needs a lot of setup or has many assertions, consider splitting it into multiple tests.

Clean Up Between Tests

Use afterEach to clean up the DOM after each test run, ensuring tests don't interfere with each other. This is already handled if you followed the setup steps earlier.

Use Descriptive Test Names

Test names should clearly describe what they're testing and what the expected outcome is.

Good test names:

it('should display error message when form is submitted empty');
it('should call onSubmit with email and password when form is valid');
it('should disable submit button while request is pending');

Mock External Dependencies

Always mock API calls, timers, and other external dependencies. Your tests should be isolated and not depend on network conditions or external services.

Conclusion

Now, you have learned how to set up Vitest in a React project and write effective tests for components, user interactions, custom hooks, and API calls. Vitest provides a powerful and efficient way to test React applications, especially when combined with modern tools like Vite.

Testing is about building confidence in your code, documenting expected behaviour, and enabling safe refactoring. Vitest's speed makes testing feel less like a chore and more like a natural part of development.

Start small. Add tests for critical user flows. Test the components that change frequently. As you build the habit, you will find that tests actually make development faster, not slower. The code will still be there tomorrow. But the bugs you catch today won't be.