Aiyedogbon Abraham - freeCodeCamp.org

How to Build More Accessible Websites with WCAG 2.2

Aiyedogbon Abraham — Tue, 18 Aug 2026 16:33:33 +0000

A website can look polished, work perfectly with a mouse, and still be difficult for some people to use.

A form might use colour as the only indication that something went wrong. A sticky header might completely cover the element that currently has keyboard focus. A login form might prevent users from pasting a password from their password manager. Or a custom button might work when clicked with a mouse but do nothing when someone uses a keyboard.

These are development decisions, not problems that only appear during an accessibility audit.

The Web Content Accessibility Guidelines (WCAG) provide a common standard for identifying and reducing many of these barriers. WCAG 2.2 is the latest WCAG 2 Recommendation, and the World Wide Web Consortium (W3C) advises developers and organisations to use WCAG 2.2 whenever possible.

This article focuses on the WCAG 2.2 Level A and AA requirements that frequently affect frontend development. The aim is to show how accessibility requirements connect to frontend development decisions.

What Is WCAG 2.2?
How WCAG Conformance Works
How the Four WCAG Principles Work
How to Start with Semantic HTML
How to Write Useful Text Alternatives for Images
How to Handle Colour, Contrast, Text Resizing, and Reflow
How to Make an Interface Work with a Keyboard
How to Keep Keyboard Focus Visible
How to Design Pointer Targets and Dragging Interactions
How to Build More Accessible Forms
How to Avoid Redundant Entry
How to Keep Help Consistent
How WCAG 2.2 Affects Authentication
How to Use ARIA Without Replacing HTML
How to Make Dynamic Status Messages Accessible
How to Test Your Website for Accessibility
Conclusion

What Is WCAG 2.2?

WCAG stands for Web Content Accessibility Guidelines. W3C develops the standard to describe how web content can be made more accessible to people with disabilities.

WCAG 2.2 organises its requirements into principles, guidelines, and testable success criteria. The success criteria are technology-independent, which is important because WCAG doesn't exist specifically for HTML, React, WordPress, or any other implementation technology.

Consider this hierarchy:

Principle: Operable

    Guideline 2.1: Keyboard Accessible

        Success Criterion 2.1.1: Keyboard

The principle gives you the broad accessibility objective. The guideline narrows that objective, while the success criterion provides the testable requirement.

W3C also publishes resources such as Understanding WCAG 2.2, How to Meet WCAG 2.2, and Techniques for WCAG 2.2. These resources explain the success criteria and provide implementation approaches, examples, and known failures. They're informative rather than part of the normative WCAG requirements.

A W3C technique can show one recognised way to satisfy a criterion, but WCAG generally doesn't require you to use that exact technique. Another implementation can also be valid if it meets the actual success criterion.

How WCAG Conformance Works

WCAG defines three conformance levels: A, AA, and AAA.

The levels build on one another. A page can't claim Level AA conformance by satisfying only the criteria labelled AA. It must satisfy all applicable Level A and Level AA success criteria. Level AAA similarly includes A, AA, and AAA requirements.

This distinction is important because accessibility discussions sometimes reduce WCAG to individual checks.

You might fix the keyboard interaction on a menu, add alternatives to your images, and correct several contrast problems. Those are useful accessibility improvements, but they don't automatically make the entire website "WCAG AA compliant".

WCAG conformance applies to complete web pages. When a process requires several pages to complete, such as a checkout process, all pages in that process must conform at the claimed level.

The examples in this article therefore demonstrate ways to address particular accessibility requirements. They don't constitute a conformance claim for an entire application.

How the Four WCAG Principles Work

WCAG groups its guidelines under four principles commonly remembered with the acronym POUR: Perceivable, Operable, Understandable, and Robust.

Perceivable means users need to be able to perceive the information you provide. Text alternatives, captions, contrast, and adaptable layouts fall under this principle.

Operable concerns how people interact with the interface. Keyboard operation, focus behaviour, navigation, pointer interactions, and timing are examples.

Understandable deals with whether users can understand the information and the way the interface behaves. Form instructions, useful error messages, predictable interfaces, and accessible authentication are relevant here.

Robust concerns whether browsers and assistive technologies can correctly interpret the content. Semantic HTML, accessible names, roles, values, and states are central to this principle.

These categories are useful, but accessibility problems rarely respect the boundary between HTML, CSS, and JavaScript.

A custom dropdown, for example, might need semantic information in the markup, visible focus styling in CSS, and correct keyboard behaviour in JavaScript.

Accessibility therefore works best when it forms part of the implementation itself rather than becoming a separate task at the end of development.

How to Start with Semantic HTML

One of the most useful accessibility decisions happens before you write any ARIA: choosing the correct HTML element.

Consider this:

Submit

A mouse user may be able to click the element, but a div doesn't automatically behave like a button.

Compare it with this:

The native button already communicates its role to the browser and provides the expected keyboard behaviour.

This relates to Success Criterion 4.1.2 Name, Role, Value, which requires user interface components to expose information such as their name and role programmatically. W3C notes that standard controls already provide much of this information when developers use them according to their specification.

The practical implication is simple: don't recreate browser behaviour unless you need to.

How Semantic HTML Communicates Page Structure

Semantic HTML also helps expose relationships between parts of a page.

You could build a page like this:


  ...



  ...



  Account Settings
  ...

The classes may create the visual layout you want, but they don't necessarily communicate the same structure programmatically.

A more meaningful structure could be:


  ...



  ...



  Account Settings
  ...

Success Criterion 1.3.1 Info and Relationships requires structure and relationships communicated visually to also be programmatically determinable or available in text. Semantic markup can provide this information without requiring developers to recreate it with additional accessibility attributes.

This doesn't mean that using

, and

automatically makes a page accessible. It means you're giving the browser more accurate information about what the content represents.

Repeated page navigation creates another issue.

If a page has a large navigation menu, a keyboard user may otherwise need to move through those links every time before reaching the main content.

A skip link provides another path:


  Skip to main content



  ...



  ...



  ...

You can position the link outside the normal view until it receives keyboard focus:

.skip-link {
  position: absolute;
  top: -4rem;
  left: 1rem;
}

.skip-link:focus {
  top: 1rem;
}

This is one recognised way to support Success Criterion 2.4.1 Bypass Blocks, which requires a mechanism for bypassing blocks of repeated content. WCAG requires the outcome rather than this exact CSS implementation.

The broader principle is worth keeping: use HTML's existing semantics before adding custom semantics yourself.

How to Write Useful Text Alternatives for Images

Adding alt text is one of the best-known accessibility practices, but the rule is often oversimplified.

Success Criterion 1.1.1 Non-text Content requires non-text content to have a text alternative that serves an equivalent purpose, subject to several exceptions. Decorative content, for example, should be implemented so assistive technologies can ignore it.

The important word is purpose.

Consider this image:

The alternative tells the user that the page contains a chart. It doesn't communicate anything the chart actually tells a sighted user.

If the main message is the change in revenue, an alternative could be:

That doesn't mean every chart can be reduced to one sentence.

If the chart contains several data series or detailed values that readers need, you may also need a nearby explanation, accessible table, or another way of communicating the underlying information.

The alternative should reflect what the image contributes in its context.

How to Handle Decorative Images

A decorative image serves a different purpose.

Consider a visual divider:

The empty alt value indicates that the image doesn't contribute information that needs to be announced.

A missing alt attribute and alt="" are therefore not interchangeable. The empty alternative is an intentional decision.

How to Handle Icons Inside Controls

Now consider a search button containing a magnifying-glass SVG.

The relevant information isn't that the user is looking at a magnifying glass. The important information is that the control starts a search.

The button receives the accessible name Search, while the SVG itself doesn't add duplicate information.

When deciding what alternative to provide, ask a more useful question than "What does this image look like?"

Ask: What information or function would the user lose if they couldn't perceive this image visually? That distinction matters when implementing accessibility.

How to Handle Colour, Contrast, Text Resizing, and Reflow

Accessibility also affects ordinary CSS decisions.

A layout may look correct at your preferred viewport size and still become difficult to use when somebody changes the way content is displayed.

How to Avoid Relying Only on Colour

Imagine a form that changes an input border from grey to red when validation fails:

.input {
  border: 1px solid #777;
}

.input.error {
  border-color: red;
}

The colour communicates that something changed, but a user needs to perceive that colour difference to understand the state.

Success Criterion 1.4.1 Use of Color requires colour not to be the only visual means used to convey information, indicate an action, prompt a response, or distinguish a visual element.

An improved implementation can combine styling with actual text:

Email address




  Enter an email address in the format name@example.com.

You can still use a red border. It just shouldn't carry the message alone.

How to Check Text Contrast

Success Criterion 1.4.3 Contrast (Minimum) requires regular text to have a contrast ratio of at least 4.5:1. Qualifying large-scale text has a minimum ratio of 3:1, subject to the criterion's exceptions.

Don't judge contrast only by looking at the colours. Two colours can look sufficiently different on your display while still falling below the required ratio. Use a contrast-testing tool as part of your design and development process.

How Non-Text Contrast Differs from Text Contrast

Success Criterion 1.4.11 Non-text Contrast deals with visual information needed to identify interface components, states, and meaningful graphical objects. The required ratio is generally 3:1 against adjacent colours, subject to the criterion's scope and exceptions.

This can affect things such as custom form controls, meaningful icons, component boundaries, selected states, and graphical information.

Passing the text contrast requirement therefore doesn't automatically mean the rest of the interface has sufficient contrast.

How to Support Text resizing

Success Criterion 1.4.4 Resize Text requires text, with specified exceptions, to be resizable up to 200% without loss of content or functionality.

Fixed dimensions often expose problems here.

Consider:

.card {
  height: 180px;
  overflow: hidden;
}

If text grows beyond the space the developer assumed it would need, some content can disappear.

Where the design doesn't genuinely require a fixed height, allowing the component to grow is safer:

.card {
  min-height: 180px;
}

This doesn't prove that the component passes the criterion. You still need to resize the text and inspect the result.

The CSS simply removes one common source of failure.

How to Design for Reflow

Success Criterion 1.4.10 Reflow addresses the ability to use content at narrow equivalent dimensions without losing information or functionality or requiring prohibited two-dimensional scrolling.

For vertically scrolling content, the criterion uses a width equivalent to 320 CSS pixels. Certain content, such as some maps and data tables, may genuinely require two-dimensional layout and falls under the criterion's exceptions.

A flexible layout can help ordinary content adapt:

.settings-grid {
  display: grid;
  grid-template-columns:
    repeat(auto-fit, minmax(min(100%, 18rem), 1fr));
  gap: 1rem;
}

As space decreases, the cards move onto new rows rather than forcing the entire page to remain wide.

Responsive design helps here, but "responsive" and "accessible" aren't synonyms.

A responsive page can still hide controls, clip text, overlap content, or remove functionality at high zoom. Test the behaviour rather than assuming a media query solves the accessibility requirement.

How to Make an Interface Work with a Keyboard

One of the simplest manual accessibility tests is to put the mouse aside and use the application with a keyboard.

Success Criterion 2.1.1 Keyboard requires functionality to be operable through a keyboard interface except where the underlying function genuinely depends on the path of the user's movement. WCAG doesn't prevent the interface from also supporting mouse, touch, voice, or other forms of input.

Let's return to our custom control:

Save

Making the div look like a button doesn't give it button behaviour.

You could begin rebuilding that behaviour yourself:


  Save

But now your JavaScript must also provide the appropriate keyboard interaction.

In most cases, this is unnecessary:

Native controls reduce the amount of interaction behaviour you need to reproduce.

W3C's ARIA Authoring Practices Guide makes this distinction explicit: ARIA roles don't cause browsers to add the keyboard behaviour that comes with native HTML controls. If you create a custom ARIA widget, you're responsible for implementing those interactions.

How to Check for Keyboard Traps

Success Criterion 2.1.2 No Keyboard Trap addresses situations where keyboard focus enters a component but can't leave through a keyboard interface.

This is particularly relevant to custom editors, dialogs, embedded widgets, and other complex controls.

Keyboard testing should go beyond asking whether you can press Tab until an element receives focus.

Try to complete the actual task. If you open a dialog, can you use its controls and close it? If you enter a custom widget, can you leave it? If a menu opens, can you operate it using its expected keyboard pattern?

Keyboard accessibility concerns the whole interaction, not simply whether an element appears in the tab order.

How to Keep Keyboard Focus Visible

Keyboard navigation becomes difficult when users can't tell which element currently has focus.

This CSS is therefore risky:

*:focus {
  outline: none;
}

It removes the browser's default focus indication without providing an alternative.

Success Criterion 2.4.3 Focus Order requires a keyboard-operable interface to provide a mode in which the keyboard focus indicator is visible.

If the default outline doesn't fit your design, replace it with another visible focus treatment rather than simply removing it:

button:focus-visible,
a:focus-visible,
input:focus-visible,
select:focus-visible,
textarea:focus-visible {
  outline: 3px solid currentColor;
  outline-offset: 3px;
}

This is an example, not a guarantee of conformance. Your chosen indicator still needs to remain visible against the colours surrounding the component.

How WCAG 2.2 Deals with Obscured Focus

WCAG 2.2 added Success Criterion 2.4.11 Focus Not Obscured (Minimum) at Level AA.

When a user interface component receives keyboard focus, author-created content must not completely hide it. The Level AA criterion requires at least part of the focused component to remain visible.

A sticky header illustrates the problem:

.site-header {
  position: sticky;
  top: 0;
  height: 5rem;
}

There's nothing inherently inaccessible about a sticky header. The problem occurs if the page scrolls a focused link or control entirely behind that header.

CSS such as this can help when scroll positioning is involved:

html {
  scroll-padding-top: 6rem;
}

But don't treat it as a complete fix.

Test the real keyboard interaction because cookie notices, fixed bottom navigation, chat windows, sticky toolbars, and other overlays can create similar problems.

The important requirement is the outcome: when focus moves, the user should still be able to see the focused component.

How to Design Pointer Targets and Dragging Interactions

Keyboard support doesn't cover every interaction barrier.

WCAG 2.2 introduced additional requirements that are particularly relevant to touchscreens, drag-and-drop interfaces, and compact controls.

How to Provide an Alternative to Dragging

Imagine a task board where users reorder cards only by dragging them.

Dragging may work well for many users, but it depends on pressing a pointer, moving it while maintaining that interaction, and releasing it in the correct place.

Success Criterion 2.5.7 Dragging Movements requires functionality that uses a dragging movement to also be achievable without dragging through a single-pointer operation, unless dragging is essential to the function.

You can keep drag-and-drop while providing another control:


  Prepare monthly report

The exact reorder logic depends on your application.

The important part is that the user has another pointer-based way to perform the same function without having to drag the card.

WCAG isn't saying "don't use drag-and-drop". It's saying that dragging shouldn't unnecessarily become the only route to the functionality.

How to Think About Target Size

Success Criterion 2.5.8 Target Size (Minimum) is another WCAG 2.2 Level AA addition.

The criterion uses a minimum target size of 24 by 24 CSS pixels or a defined spacing alternative and contains several exceptions. It therefore should not be simplified to "every clickable element must always be at least 24 pixels wide and high".

For an isolated icon button, you can choose to provide an even larger target:

.icon-button {
  min-width: 2.75rem;
  min-height: 2.75rem;

  display: inline-grid;
  place-items: center;
}

At a typical root font size, this deliberately creates a target larger than the WCAG minimum.

The visible icon can remain smaller:

The size of the icon and the size of the interactive target are not the same thing.

That distinction is useful when designing dense interfaces.

How to Keep the Accessible Name Aligned with the Visible Label

Success Criterion 2.5.3 Label in Name concerns controls that have a visible text label.

The accessible name should contain the visible label text. This is particularly important for users who operate interfaces using speech and refer to controls by the words they can see.

Avoid this:

The visible label is Search, but the accessible name is Find products.

In this case, the simplest version is better:

If additional accessible context is genuinely necessary, retain the visible wording:

Before adding an aria-label, check whether the visible text already gives the control an adequate accessible name.

How to Build More Accessible Forms

Forms combine several areas of accessibility: structure, instructions, errors, input purpose, and status changes.

Start with the field itself.

How to Label Form Controls

This pattern is common:

The placeholder provides a visual hint, but it's not a good replacement for a proper label.

Use:


  Email address

Success Criterion 3.3.2 Labels or Instructions requires labels or instructions when content requires user input.

The for and id values also create a programmatic relationship between the label and the field.

How to Identify Common Input Purposes

Success Criterion 1.3.5 Identify Input Purpose applies to fields collecting certain types of information about the user. Their purpose needs to be programmatically determinable when the technology supports it.

HTML's autocomplete tokens help communicate common purposes:


  Full name





  Email address

This also allows browsers and other tools to provide useful input assistance.

How to Write Useful Validation Errors

Now consider an error message:

Invalid input.

The message tells the user almost nothing: Which input is invalid? What's wrong with it? What needs to change?

Success Criterion 3.3.1 Error Identification requires an automatically detected input error to identify the item in error and describe the error in text.

An implementation might look like this:


  Email address





  Enter an email address in the format name@example.com.

aria-invalid="true" exposes the invalid state. aria-describedby associates the explanation with the field.

More importantly, the message tells the user what needs correcting.

Success Criterion 3.3.3 Error Suggestion goes further at Level AA. When the system detects an input error and knows how it can be corrected, it should provide an appropriate suggestion unless doing so would compromise the security or purpose of the content.

The aim isn't to make every error message long. The aim is to make it actionable.

How to Avoid Redundant Entry

Consider a checkout process.

The user enters a delivery address on one step. The next step asks them to type exactly the same address again for billing.

WCAG 2.2 introduced Success Criterion 3.3.7 Redundant Entry at Level A.

When information previously entered by or provided to the user is required again during the same process, the information must generally be auto-populated or available for the user to select. The criterion includes exceptions where re-entry is essential, necessary for security, or where the previous information is no longer valid.

A checkout might offer:


  
  Use my delivery address as my billing address

Notice that the requirement concerns information within the same process. It doesn't mean every website has to remember every value a user entered during earlier visits.

This criterion also shows why accessibility extends beyond screen-reader support.

Reducing unnecessary repetition can lower the cognitive and interaction effort required to complete a task.

How to Keep Help Consistent

WCAG 2.2 also added Success Criterion 3.2.6 Consistent Help at Level A.

If certain help mechanisms appear repeatedly across a set of pages, they need to appear in the same relative order unless the user initiates a change. These mechanisms can include human contact details, contact mechanisms, self-help options, and automated contact mechanisms.

Suppose your account pages all provide a support link in the header:


  Acme

  
    
  

  Support

Do not move that support mechanism unpredictably between otherwise related pages.

A key nuance is that WCAG 2.2 does not require every website to introduce one of these help mechanisms.

The criterion applies when qualifying help is already available and repeated across multiple pages in the same set.

The development implication is therefore mostly about consistency.

If users learn where help appears on one page, avoid making them search for it again on the next.

How WCAG 2.2 Affects Authentication

Authentication is another area that changed in WCAG 2.2.

Consider a login form that deliberately blocks paste:

passwordInput.addEventListener("paste", (event) => {
  event.preventDefault();
});

That may appear to encourage users to type a password manually, but it can also interfere with mechanisms that reduce the need to remember or transcribe credentials.

Success Criterion 3.3.8 Accessible Authentication (Minimum) addresses authentication steps that require cognitive function tests.

The Level AA requirement allows such tests when an accepted alternative or assistance mechanism is available. W3C specifically identifies password-manager support and copy-and-paste as mechanisms that can reduce the cognitive burden involved in authentication.

A conventional login form can allow these tools to work:


  Email address





  Password

It would be inaccurate to simplify this criterion to "WCAG 2.2 prohibits passwords". It does not.

A password is a cognitive function test, but the criterion permits it when the user has a mechanism that assists with completing that test, such as a password manager that can fill the field.

The same reasoning becomes relevant to multi-factor authentication.

If a process requires a user to read a code on one device and manually transcribe it to another, consider whether the authentication flow offers a path that avoids that cognitive burden. W3C's guidance explicitly discusses authentication processes with several steps and the need for an accessible path through them.

This is a good example of why the exact criterion matters more than a simplified accessibility checklist.

How to Use ARIA Without Replacing HTML

ARIA stands for Accessible Rich Internet Applications.

It provides roles, states, and properties that help web applications communicate information that may not otherwise be available to assistive technologies.

ARIA is useful. It's also easy to misuse.

Consider this example:


  Place order

The role tells accessibility APIs that the element represents a button. It doesn't make the element behave like a button.

W3C ARIA Authoring Practices Guide describes an ARIA role as a promise. When you use role="button", you take responsibility for providing the expected keyboard and interaction behaviour yourself. ARIA doesn't cause the browser to add that behaviour automatically.

Where a native HTML element already exists, prefer it:

How ARIA Can Communicate State

ARIA becomes useful when HTML alone doesn't communicate enough about a component's current state.

Consider a disclosure control:




  Profile
  Security

You can keep aria-expanded in sync with the visible state:

const trigger = document.querySelector(
  "#account-options-trigger"
);

const panel = document.querySelector(
  "#account-options"
);

trigger.addEventListener("click", () => {
  const isExpanded =
    trigger.getAttribute("aria-expanded") === "true";

  trigger.setAttribute(
    "aria-expanded",
    String(!isExpanded)
  );

  panel.hidden = isExpanded;
});

The JavaScript does two related things.

It changes whether the panel is hidden, and it updates the accessibility state exposed by the trigger.

If the panel opens visually but aria-expanded remains false, the interface now communicates two conflicting states.

This illustrates a useful ARIA rule: ARIA state must describe the interface that actually exists.

For more complex patterns such as dialogs, comboboxes, tabs, menus, and grids, the W3C ARIA Authoring Practices Guide provides documented interaction patterns and examples. W3C also makes clear that APG is implementation guidance rather than a normative accessibility standard.

How to Make Dynamic Status Messages Accessible

Modern interfaces frequently update without loading a new page.

A user might save a profile and see:

Your settings were saved.

Or run a search and see:

18 results found.

A sighted user can often notice these updates without moving away from the current control.

Assistive technology also needs a programmatic way to identify relevant status messages.

Success Criterion 4.1.3 Status Messages requires qualifying status messages to be programmatically determinable so assistive technologies can present them without requiring the message itself to receive focus.

For a routine save confirmation, you can use role="status":

Then update its content:

const saveButton = document.querySelector(
  "#save-settings"
);

const saveStatus = document.querySelector(
  "#save-status"
);

saveButton.addEventListener("click", () => {
  saveStatus.textContent =
    "Your settings were saved.";
});

The browser can expose that status change to supporting assistive technologies without moving keyboard focus away from the Save button.

Not every dynamic DOM change is a status message.

WCAG defines the term more narrowly. It includes information about the result or success of an action, an application's waiting state, the progress of a process, or the existence of errors when that update doesn't itself constitute a change of context.

Don't make every changing piece of content a live announcement. An excessively chatty interface can create a different usability problem.

Use status semantics for information users need to receive while continuing their current task.

How to Test Your Website for Accessibility

Accessibility testing works best as a combination of methods.

WCAG itself is designed to support testing through both automated tools and human evaluation. An automated scanner can identify many technical problems, but it can't reliably judge every accessibility requirement or determine whether an entire user journey makes sense.

How to Start with Automated Testing

Automated tools are useful for repeatable technical checks.

They can identify many problems involving accessible names, some contrast failures, invalid ARIA usage, form relationships, and other machine-detectable conditions.

The limitation appears when correctness depends on meaning.

A tool can tell you that an image has an alt attribute. It can't always determine whether the text accurately communicates the purpose of the image.

Automation should therefore start the evaluation, not end it.

How to Perform Keyboard Testing

Open the page, put the mouse aside, and try to complete an actual task using only your keyboard.

Start with Tab to move forwards through interactive elements and Shift + Tab to move backwards.

Use Enter and Space to activate controls where appropriate. Custom widgets may also use arrow keys or Escape depending on their interaction pattern. The ARIA Authoring Practices keyboard guidance documents expected behaviour for common widget patterns.

Don't simply press Tab a few times and stop.

For example, if you're testing a checkout flow:

Navigate to the basket.
Change a quantity.
Continue to checkout.
Move through the form.
Submit it.
Correct an error.
Complete the process.

As you do this, check whether you can reach and operate every required control, move away from every component, follow a sensible focus sequence, see where focus currently is, and avoid having focused content hidden by an overlay.

If something goes wrong, the relevant requirements include Success Criterion 2.1.1 Keyboard, Success Criterion 2.1.2 No Keyboard Trap, Success Criterion 2.4.3 Focus Order, Success Criterion 2.4.7 Focus Visible, and Success Criterion 2.4.11 Focus Not Obscured (Minimum).

How to Test Zoom, Resizing, and Reflow

You can perform a basic zoom test directly in your browser.

In most browsers:

use Ctrl + + on Windows or Linux
use Cmd + + on macOS
use Ctrl/Cmd + 0 to return to the default zoom

W3C's Zoom Easy Check suggests testing at 200%.

As you increase zoom, work through the page and look for:

clipped text
overlapping elements
controls that disappear
navigation that stops working
content hidden behind other content
horizontal scrolling across ordinary page content

Also use a narrow browser window or responsive browser tools to inspect how the content reflows.

This is to verify the behaviour discussed under Success Criterion 1.4.4 Resize Text and Success Criterion 1.4.10 Reflow.

How to Test Colour and Contrast

Use a contrast checker or the colour information available in your browser developer tools to measure foreground and background combinations.

Do this for ordinary text as well as important non-text elements such as custom control borders, icons, and state indicators.

Then test colour-dependent information separately.

For example, if an error field turns red, temporarily ignore the colour change and ask whether another visible indication still communicates the error.

These checks correspond to Success Criterion 1.4.1 Use of Color, Success Criterion 1.4.3 Contrast (Minimum), and Success Criterion 1.4.11 Non-text Contrast.

How to Test Forms Manually

Don't test a form only with valid information. You should deliberately make mistakes to test as many cases as possible.

Leave a required field empty. Enter an incorrectly formatted email address. Submit a value the form should reject.

Then check whether you can:

identify the field that has a problem
understand the error message
determine how to correct it
reach the error using the keyboard
correct the information and continue

Also inspect form controls in your browser developer tools to confirm that visible labels and descriptions are associated with the correct fields.

These tests help you verify Success Criterion 3.3.1 Error Identification, Success Criterion 3.3.2 Labels or Instructions, and Success Criterion 3.3.3 Error Suggestion.

How to Test Pointer and Dragging Interactions

If your interface contains drag-and-drop, complete the action normally first. Then try to perform the same function without dragging.

For example, if you can drag a task into a new position, check whether another pointer-operated control lets you move it as well.

That gives you a practical test for Success Criterion 2.5.7 Dragging Movements.

For small controls, use browser developer tools to inspect the rendered interactive area rather than judging only the visible icon.

Pay particular attention to close buttons, carousel controls, pagination items, icon buttons, and densely packed toolbars when checking Success Criterion 2.5.8 Target Size (Minimum).

How to Inspect the Accessibility Tree

Modern browser developer tools expose accessibility information associated with elements.

Inspect important controls and compare what the accessibility tree reports with what the interface shows.

A button might visually say Search while its accessible name says something completely different. A disclosure may look open while its aria-expanded state remains false.

Inspecting the accessibility tree helps expose these mismatches.

How to Test with Assistive Technology

When testing with a screen reader, focus on complete tasks.

For a form, navigate to the fields, identify their labels, enter incorrect information, submit it, locate and understand the errors, correct them, and confirm the successful state.

The question isn't simply:

Can the screen reader read this page?

The more useful question is:

Can the user complete the task and understand what happened?

Testing with disabled users can reveal additional usability barriers that automated and standards-based evaluation may not expose.

Conclusion

WCAG becomes easier to understand when you connect its requirements to normal development decisions. The important shift is to stop treating accessibility as a final audit. Build it into the interface while you build everything else.

How Attribute-Based Access Control Helps You Write Better Authorization Rules

Aiyedogbon Abraham — Thu, 04 Jun 2026 17:22:22 +0000

Every application that handles user data eventually hits the same problem: not all users should see the same things.

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.

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

Factor	RBAC	ABAC
Logic	Permissions assigned to roles, roles assigned to users	Policies evaluate attributes at decision time
Granularity	Coarse-grained	Fine-grained and context-aware
Flexibility	Low, new rules require new roles	High, update policies without changing roles
Scalability	Role explosion under complexity	Scales with policy complexity, not role count
Auditability	Simple, check role assignments	Requires logging attributes at decision time
Complexity	Low	Higher, more moving parts
Best for	Simple, stable permission structures	Complex, dynamic, or context-dependent permissions

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:

the patient is currently admitted to the nurse's assigned floor,
the nurse is on an active shift,
the access occurs from within the hospital network,
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).

How to Use OpenStreetMap as a Free Alternative to Google Maps

Aiyedogbon Abraham — Wed, 25 Mar 2026 17:35:27 +0000

Google Maps has been the default choice for developers building location-based applications for years. But for many teams, especially those operating at scale, pricing has become a real concern.

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:

What is OpenStreetMap?
Why Choose OpenStreetMap Over Google Maps?
Understanding the OpenStreetMap Ecosystem
How to Integrate OpenStreetMap in React with Leaflet
How to Add Geocoding with Nominatim
Advanced Features
When to Choose OpenStreetMap vs Google Maps
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:

Nodes: single points (for example, a bus stop or a tree)
Ways: lines or shapes made up of nodes (like roads or buildings)
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:

Raster tiles (used by Leaflet): pre-rendered images
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:

The user enters a location
A geocoding service converts it into coordinates
The map updates its position
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 (
    
      
      
        Hello from OpenStreetMap
      
    
  );
}

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 (
    
      
         setQuery(e.target.value)}
          placeholder="Search location"
        />
        
      

      
        {results.map((result) => (
           selectLocation(result)}>
            {result.display_name}
          
        ))}
      
    
  );
}

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.

How to Test React Applications with Vitest

Aiyedogbon Abraham — Tue, 10 Feb 2026 22:43:37 +0000

Testing is one of those things that every developer knows they should do, but many put off until problems start appearing in production. If you’re building React applications with Vite, there's a testing framework that fits so naturally into your workflow that you might actually enjoy writing tests. That framework is Vitest.

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.

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 applicationp>
    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)}>Incrementbutton>
      <button onClick={() => setCount(count - 1)}>Decrementbutton>
      <button onClick={() => setCount(0)}>Resetbutton>
    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() 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">Emaillabel>
        <input
          id="email"
          type="email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
        />
      div>
      <div>
        <label htmlFor="password">Passwordlabel>
        <input
          id="password"
          type="password"
          value={password}
          onChange={(e) => setPassword(e.target.value)}
        />
      div>
      {error && <p role="alert">{error}p>}
      <button type="submit">Log Inbutton>
    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:

getByRole (best for interactive elements)
getByLabelText (for form fields)
getByPlaceholderText
getByText
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.

Aiyedogbon Abraham - freeCodeCamp.org

How to Build More Accessible Websites with WCAG 2.2

Table of Contents

What Is WCAG 2.2?

How WCAG Conformance Works

How the Four WCAG Principles Work

How to Start with Semantic HTML

How Semantic HTML Communicates Page Structure

Account Settings

How Attribute-Based Access Control Helps You Write Better Authorization Rules

Table of Contents

Prerequisites

How Access Control Has Evolved

Discretionary and Mandatory Access Control

Identity-Based Access Control and Access Control Lists

Role-Based Access Control

Attribute-Based Access Control

What is Attribute-Based Access Control?

The Four Building Blocks of ABAC

1. Subject Attributes

2. Object Attributes (Resource Attributes)

3. Action Attributes

4. Environment Conditions

How an ABAC Decision is Made

Step 1: Collect Attributes

Step 2: Find Applicable Policies

Step 3: Evaluate Each Policy

Step 4: Reconcile Conflicts

Step 5: Enforce the Decision

How to Write ABAC Policies

Simple Boolean Policy

Multi-Attribute Policy

Environment-Aware Policy

Ownership-Based Policy

How to Implement ABAC in Code

Step 1: Define the Attribute Structure

Step 2: Write Policy Functions

Step 3: Build an Evaluation Engine

Step 4: Add Attribute Collection

Step 5: Integrate with Your API

ABAC vs RBAC: When to Use Which

RBAC Strengths

Where RBAC Breaks Down

RBAC vs ABAC Comparison

Combining Both Models

Real-World Use Cases

Healthcare Records Management

Corporate Data Access

Government and Classified Information

Multi-Tenant SaaS Applications

Enterprise ABAC Considerations

Policy Administration

Attribute Quality and Freshness

Performance

Audit Logging

Limitations and Challenges

Conclusion

Glossary

How to Use OpenStreetMap as a Free Alternative to Google Maps

What We'll Cover:

What is OpenStreetMap?

The Open Database License (ODbL)

Why Choose OpenStreetMap Over Google Maps?

Cost

Control

Customization

Adoption

Understanding the OpenStreetMap Ecosystem

Data Layer (OpenStreetMap)

Rendering Layer (Leaflet, MapLibre)

Services Layer

How Everything Works Together

How to Integrate OpenStreetMap in React with Leaflet

Step 1: Create a React App

Step 2: Install Dependencies

Step 3: Import Leaflet CSS

Step 4: Create a Map Component

Important note:

How to Add Geocoding with Nominatim

Custom Hook for Geocoding