Platform

Solutions

Resources

Platform

Solutions

Resources

Platform

Solutions

Resources

Blog

Gray Box Testing: Techniques, Examples and When to Use It

Abhilash

Published on

Gray box testing
eBook CTA Background
RECOMMENDED RESOURCES

The Ultimate Enterprise Guide To Agentic Testing

AI agents can write, fix and triage your tests at scale. See how to use them in QA while keeping people in control of everything that ships.

Get the eBook →

Enterprise guide to agentic testing
eBook CTA Background
RECOMMENDED RESOURCES

The Ultimate Enterprise Guide To Agentic Testing

AI agents can write, fix and triage your tests at scale. See how to use them in QA while keeping people in control of everything that ships.

Get the eBook →

Enterprise guide to agentic testing
eBook CTA Background
RECOMMENDED RESOURCES
Enterprise guide to agentic testing

The Ultimate Enterprise Guide To Agentic Testing

AI agents can write, fix and triage your tests at scale. See how to use them in QA while keeping people in control of everything that ships.

Get the eBook →

eBook CTA Background
RECOMMENDED RESOURCES

The Ultimate Enterprise Guide To Agentic Testing

AI agents can write, fix and triage your tests at scale. See how to use them in QA while keeping people in control of everything that ships.

Get the eBook →

Enterprise guide to agentic testing

Table of contents

Lorem ipsum

Lorem ipsum

Lorem ipsum

Lorem ipsum

Lorem ipsum

Gray box testing is a testing approach in which the tester has partial knowledge of the internal structure of the software being tested. The tester combines an external view, meaning what the user experiences and what the system returns, with selective knowledge of the internal architecture, meaning data schemas, API contracts, integration topology, and business rules.

The combination produces tests that are more targeted than pure black box testing and more grounded in real-world use than pure white box testing.

This guide covers the definition and the knowledge-spectrum reframe that explains why the technique matters, the classic techniques, the security and API use cases, a worked enterprise example, the tools, the advantages and honest limits, and why AI-generated code has made structural awareness more valuable rather than less.



What is Gray Box Testing?

Gray box testing combines testing what the system does from the outside with partial knowledge of how it’s built. The tester knows some of the internals, like data structures, API contracts, integration points, business rules and configuration, but doesn’t have the full view a developer has.

That partial knowledge is what defines it:

  • A black box test treats the system as a sealed box. Inputs go in, outputs come out, and you check the outputs are right.

  • A white box test treats the system as a glass box. You can see every line of code, every branch and every variable.

  • A gray box test treats the system as a frosted box. You can see enough of the inside to guide your testing, but you’re still checking behaviour, not the code itself.

In practice, gray box testing is the kind of testing an experienced QA engineer does naturally. They know enough about the system to test it well, without needing to read the code line by line.

Gray box testing



Why the “Three Boxes” Idea is Misleading

Textbooks usually present testing as three separate choices: black box, where you know nothing about the inside, white box, where you know everything, and gray box, where you know something.

It makes for a neat diagram, but it hides something most experienced testers already know: most testing of complex systems is gray box, whether teams call it that or not.

Think about it:

None of them can see all the code, but none of them are testing blind either. They’re all somewhere in the middle.

So gray box isn’t a niche compromise between two “pure” approaches. It’s where most real testing already happens. Having a name for it just helps teams talk about it.



A Quick Comparison - Black Box vs Gray Box vs White Box Testing


Black Box

Gray Box

White Box

Knowledge of the inside

None

Partial, like schemas, API contracts and integrations

Full access to the code

Point of view

The user’s

Someone who knows how the pieces connect

The developer’s

Who usually does it

QA engineers, or end users in acceptance testing

Experienced QA engineers

Developers or specialists who can read code

Best for

Functional and acceptance testing

Integration, API and complex system testing

Unit testing and code-level security reviews

What tests are based on

Requirements and user stories

Requirements plus API, data and integration knowledge

Source code and design documents

Level

Overall behaviour

Systems and integrations

Individual lines and branches

What it covers

Requirements

How components and data work together

Code paths and branches

How it’s automated

UI and acceptance tests

API, integration and end-to-end tests

Unit test frameworks

These three don’t replace each other. Each one finds different kinds of bugs at different levels. A complete testing programme uses all three, and a team that only uses one misses what the others would catch.

For a closer look at the two ends, our guide to white box testing covers code-level techniques like branch and path coverage, with examples.



Think of it as a Scale, Not Three Boxes

A better way to think about it is a scale. At one end, you know nothing about how the system works. At the other, you know everything.

  • Far left (black box): a tester checks acceptance criteria with no idea how the system is built. This is closest to a real user.


  • Far right (white box): a developer runs unit tests with access to every line of code.


  • Everything in between (gray box): this is most of the scale. A tester who knows the API contracts but not the code behind them sits nearer the black box end. A tester who can query the database and read the logs, but not the source code, sits nearer the white box end. Both are doing gray box testing, just with different knowledge.


Thinking of it this way helps in two ways:

  1. It stops pointless either-or debates: Teams sometimes argue about whether to test black box for objectivity or white box for thoroughness. Really, the question is how much of what you know you should use, and where.


  2. It makes the trade-offs clear: More knowledge means more targeted tests, but a greater risk of testing how the code works rather than what it does. Less knowledge means more realistic tests, but a greater risk of missing something the structure would have shown you.


Where you sit on the scale should be a decision you make on purpose, not a default.



How Gray Box Testing Works

Gray box testing starts in the same place as black box testing: the requirements, user stories, acceptance criteria or use cases. Then you add what you know about the inside to decide how to test it well.

There are three main kinds of inside knowledge:

Type of Knowledge

What it Includes

What it Lets You Test

Interfaces

API contracts, request and response formats, methods, parameters and error codes

API-level situations a UI test would never reach

Data

Database schemas, how tables relate, key fields and transaction boundaries

Whether the data is right after a test, even when the screen doesn’t show it

Integrations

How the system connects to others, what data passes between them and how failures spread

Problems between systems, which is where most enterprise journeys go wrong

You don’t need all three for every test. Use the knowledge that helps answer the question you’re asking, and leave the rest. If you try to check everything you can see, you end up writing tests tied to the implementation, which are fragile, slow and hard to maintain.

If you use your knowledge selectively, you get tests at the right level that keep working when the code changes.



The Classic Gray Box Testing Process

Most textbooks describe gray box testing as a set of steps:

  1. Pick inputs, drawing on both black box and white box views

  2. Work out the expected outputs for those inputs

  3. Identify the main paths through the system

  4. Pick sub-functions worth testing in more depth

  5. Work out the inputs and expected outputs for each sub-function

  6. Run the sub-function tests

  7. Check the results, then repeat for the other functions

This is a handy checklist, but it describes the steps, not the judgement. The harder part is deciding which inside knowledge to use and at what level to test. The planning method in the next section helps with that.



How to Plan Gray Box Testing

Step

What to Do

1. List what you know

Write down the inside knowledge available, like API contracts, data schemas, how systems connect, user roles, configuration options and past bug patterns

2. Match knowledge to areas

Decide which kind of knowledge matters for each area. A user-facing feature might need interface knowledge, a reporting feature might need data knowledge, and an integration might need contract knowledge

3. Pick techniques that use it

Use matrix testing for known variables, API testing for documented contracts, database checks for known schemas and pattern testing for past bug history

4. Test at the right level

Use your knowledge to design the test, but don’t make the test depend on how the code is written. Checking an API returns 201 with the new record is a good gray box test. Checking a specific internal function is called twice is a white box test that will break on the first refactor

5. Write down your assumptions

Note which schemas, API versions or integrations each test relies on. Then, when the credit bureau API moves from v2 to v3, you know exactly which tests to update



Gray Box Testing Techniques

The first four techniques below are the classic gray box ones. The last two are the ones most enterprise teams rely on day to day.

Technique

How It Works

Why It’s Gray Box

Example

Matrix testing

Test across combinations of the variables that affect behaviour

You need to know the variables exist, like config settings, feature flags and role permissions

Testing a CRM customisation across roles, currencies and date formats

Regression testing based on what changed

Focus regression on what changed in a release

You need to know enough about the architecture to know what changed

Testing the journeys and integrations whose components changed this release

Pattern testing

Use past bugs to decide where to look

You need to know the history of where things have gone wrong

Extra care on date handling because of three past time-zone incidents

Orthogonal array testing

Test a smaller set of combinations that still covers every pair of values

You need to understand which variables are likely to interact

Testing feature flags or configuration options

API testing

Test requests, responses, methods and error codes

You know the contract, but not how the API is built

Checking a payment API returns the right errors for bad requests

Database and integration testing

Check the right data was saved and the right messages were sent

You know the schemas and payloads, but not the application code

Checking an order screen says “success” and the order is actually saved

Database checks are especially useful, because a transaction can look successful on screen and still leave the data wrong. A black box test would miss that. A gray box test that knows where to look would catch it.

Regression based on what changed works best when your suite runs reliably on every release. To see how Virtuoso QA keeps regression running as your application changes, take a look at regression testing.

Some guides also list boundary value analysis, equivalence partitioning and decision table testing as gray box techniques. They’re really black box techniques, but knowing the internal ranges and rules helps you apply them more precisely.



Gray Box Testing for Security and Penetration Testing

Security is one of the most important uses of gray box testing, and much real-world penetration testing is done this way. The reason is simple: it matches how real attacks usually happen.

Type

What It Simulates

Strengths and Gaps

Black box penetration test

An outside attacker with no inside knowledge

Realistic for outsiders, but misses what an insider or logged-in user could do

White box security review

Someone with full access to the code

Thorough, but doesn’t reflect how most attacks actually unfold

Gray box penetration test

A logged-in user abusing their access, an insider, or an attacker who already knows the API paths

Matches where many real threats come from

A gray box security tester usually has some inside knowledge, like valid login details, the API structure or how authentication works, but not the source code. That’s similar to where a real attacker ends up after some initial digging around.

From there, they can look for:

  • Authorisation flaws, where a user can reach data or actions they shouldn’t

  • Injection problems, in inputs they know users control

  • Weak session handling, like tokens that can be reused

  • Information leaks, in error messages

Knowing where the login boundaries are and which inputs users control lets the tester probe much more effectively than a blind outside scan.



When to Use Gray Box Testing

Gray box testing fits best when a system is too complex for black box testing to catch everything, but you don’t control all the code, so white box testing isn’t realistic.

Situation

Why Gray Box Fits

Complex enterprise platforms, like Dynamics 365, Salesforce, SAP, Workday and Guidewire

They have rich data models and lots of integrations. Black box misses data issues, and white box isn’t practical because most of the code belongs to the vendor

API-first and microservices systems

Testing APIs needs contract knowledge, and testing the journeys built on them needs integration knowledge

Systems with lots of integrations

Payment providers, identity providers, fraud checks and regulatory reporting all need you to know the payloads and failure modes

Data-heavy applications

When the screen is a thin layer over a lot of data, like analytics tools, CRMs and ERPs, you need to check the data is right, not just that the screen looks right

Application security testing

Knowing where the login boundaries are and which inputs users control makes security testing far more effective

Between them, these cover most modern enterprise software. As systems get more complex and more connected, gray box has become the main way teams test, whether they call it that or not.

Related read: Microservices vs Monolithic Architecture Testing Strategies



Gray Box Testing Example: A Building Society’s New Mortgage Platform

A UK building society is launching a new mortgage application platform. It connects to three outside systems:

  • A credit bureau for borrower checks

  • An underwriting engine for risk decisions

  • A document management system for application paperwork

It also writes to the building society’s existing customer records. It’s the biggest release of the year.

The team has to use gray box testing. They don’t have access to all the code, because the underwriting engine is third-party, the credit bureau is external and the document system is a vendor product. But they do know a lot about how everything fits together.

What the Testers Know

What They Don’t Know

The credit bureau’s API: request fields, response fields and error codes

How the credit bureau or underwriting engine works inside

The underwriting engine’s API: the case data sent, the decision returned and the audit fields

The code inside the document management system

Which customer record fields are written, which are read and how they relate

The internal database design of the customer record system

Which user roles can do what


Configuration like interest rate models, eligibility rules and document templates



That knowledge shapes the tests at three levels:


Level

What It Checks

How

Integration

The platform handles each outside system correctly

Send valid and invalid API requests, check responses and make sure errors are handled. It tests how the platform deals with the credit bureau’s behaviour, not how the credit bureau works

Data

Customer records are written and updated correctly

Submit an application, check the screen shows success, then check the customer record directly to confirm the right fields were filled in

Journey

The full mortgage application works from start to finish

Follow a typical application through every system, knowing which integration is involved at each step

Here’s what the integration and data checks might look like in practice. The first checks the platform’s own API accepts an application and records a completed credit check:

given()
    .contentType("application/json")
    .body(mortgageApplication)
.when()
    .post("/api/mortgage-applications")
.then()
    .statusCode(201)
    .body("applicationId", notNullValue())
    .body("creditCheck.status", equalTo("COMPLETED"));
given()
    .contentType("application/json")
    .body(mortgageApplication)
.when()
    .post("/api/mortgage-applications")
.then()
    .statusCode(201)
    .body("applicationId", notNullValue())
    .body("creditCheck.status", equalTo("COMPLETED"));
given()
    .contentType("application/json")
    .body(mortgageApplication)
.when()
    .post("/api/mortgage-applications")
.then()
    .statusCode(201)
    .body("applicationId", notNullValue())
    .body("creditCheck.status", equalTo("COMPLETED"));
given()
    .contentType("application/json")
    .body(mortgageApplication)
.when()
    .post("/api/mortgage-applications")
.then()
    .statusCode(201)
    .body("applicationId", notNullValue())
    .body("creditCheck.status", equalTo("COMPLETED"));

The second checks the customer record was actually updated, even though the screen already said “Application submitted”





If the screen says success but underwriting_decision is empty, you’ve found exactly the kind of bug a screen-only test would miss.

With black box testing alone, the team would catch the obvious journey bugs but miss data and integration problems. With white box testing alone, they’d catch code bugs in the platform but miss problems with the third-party systems. Gray box testing catches both.

Journeys like this cross the platform, three outside systems and the customer records. Virtuoso QA’s end-to-end testing checks the screens, the APIs and the data in one journey test.



Advantages of Gray Box Testing

Advantage

Why It Matters

Better coverage than black box

You can check data, payloads and integrations that black box tests can’t see

More realistic than white box

Tests stay close to what users actually experience, not just how the code works

A better balance of effort and results

You don’t need developer-level code access, and you don’t need endless scenarios to make up for not knowing the structure

Closer to where real bugs are

Most bugs in complex systems happen between components, like a screen sending the wrong data, a database ending up in the wrong state, or an integration timing out without being handled

A natural fit for modern systems

APIs, microservices, integration-heavy platforms and customisable enterprise software all benefit from knowing how things connect



Limitations of Gray Box Testing

Limitation

What It Means

Testers need technical skills

Testers have to read API docs, query databases and understand integrations. Teams without those skills fall back to black box testing. Building these skills takes time

Less repeatable than black box

Two testers with different knowledge will design different tests for the same feature. That can find more bugs, but it also means the programme relies on what individuals know

Can’t replace white box testing

Unit testing, code coverage, mutation testing and code-level security reviews still need white box access. Gray box testing works alongside them, not instead of them

Gray box testing isn’t the answer to everything. The strongest testing programmes use all three approaches, and decide where on the scale each kind of testing should sit.



Gray Box Testing in Enterprise QA Today

Most enterprise QA is gray box testing without the label. Teams testing Dynamics 365, Salesforce, SAP, ServiceNow, Workday, Guidewire and Oracle combine testing what users see with knowledge of each platform’s data model, configuration and integrations.

Calling it gray box testing on purpose helps in three ways:

  • Choices become deliberate: Deciding between black box for realism and gray box for efficiency becomes a planned decision, not a habit.


  • Skills become part of the job: Learning to read API contracts, query databases and understand integrations becomes part of a tester’s career path, not something only the curious pick up.


  • Tests become easier to maintain: A test that’s documented as depending on a specific schema can be updated when that schema changes. A test that relies on knowledge in one tester’s head can’t.



Common Gray Box Testing Mistakes

Mistake

What Goes Wrong

What to Do Instead

Defaulting to black box or white box

Black box misses structural problems, and white box produces fragile tests

Decide on purpose where each kind of testing sits on the scale

Not writing down what knowledge a test uses

When the tester who wrote it leaves, nobody knows what it depends on

Record the schemas, contracts and integrations each test relies on

Relying on a few people’s knowledge

If those people leave, the programme struggles

Keep structural knowledge in shared docs and in the tests themselves

Using the name without the knowledge

Tests are just black box tests with a gray box label

Actually use structural knowledge to design the tests

Thinking gray box means manual

Teams don’t automate gray box tests

Automate them. API tests, data checks and integration tests are all gray box automation



Gray Box Testing and AI-Written Code

AI-assisted development makes gray box testing more useful, not less, for two reasons.

AI Creates Structure Nobody Designed on Purpose

When AI writes a lot of your code, it makes implementation choices your team didn’t consciously make. Some of these affect how data flows, how APIs behave or how integrations are handled.

Black box testing will find these eventually, usually when customers notice. Gray box testing finds them earlier, at the data and API level where they start.

What Customers Rely on is the Contract, Not the Code

AI can rewrite the code underneath overnight, but the API contracts and journeys customers depend on shouldn’t change. Gray box tests at the API and integration level check those contracts, and keep working however often the code is rewritten.


In practice, mature teams split the work in two. Journey-level tests, written in plain English, check what users experience. Gray box tests, like API checks, data checks and integration checks, make sure the contracts underneath still hold.

Between them, they cover most of what modern enterprise software needs testing.



Where Virtuoso QA Fits

Gray box testing works best when you can check the journey and the data underneath it in the same test. That’s how Virtuoso QA is built.

  • One test, three levels: a single test can walk through the mortgage application on screen, call the platform’s API and check the customer record in the database. You don’t need a UI tool, an API tool and a database script stitched together.


  • Written around behaviour: tests describe what the journey should do in plain English, so they’re readable by testers, analysts and developers alike.


  • Fixes you approve: when a screen changes, Virtuoso QA suggests a fix for your team to accept or reject. The API and data checks stay the same, so the structural checks don’t drift.


  • Assumptions you can see: because API and data checks sit in the test itself, anyone can see which endpoints and fields a test depends on, which helps when an API version or schema changes.

That means your testers spend their gray box knowledge deciding what to check, not keeping three separate tools running.



Related Reads

Frequently Asked Questions

When Should Gray Box Testing Be Used?

Is Gray Box Testing Manual or Automated?

How Does Gray Box Testing Apply to API Testing?

See what your next release looks like with Virtuoso

Book a walkthrough on your applications and your workflows. Bring a requirement, a user journey, or a brittle Selenium script, and watch the loop run on something you recognise.

See what your next release looks like with Virtuoso

Book a walkthrough on your applications and your workflows. Bring a requirement, a user journey, or a brittle Selenium script, and watch the loop run on something you recognise.

See what your next release looks like with Virtuoso

Book a walkthrough on your applications and your workflows. Bring a requirement, a user journey, or a brittle Selenium script, and watch the loop run on something you recognise.

Virtuoso QA is establishing the standard of proof for software releases. Its governed QA loop turns business requirements into tests for any browser-based application: AI proposes, a deterministic engine executes, a person approves what matters, and every decision leaves evidence.

Trust Center

AICPA

SOC

WAVE STRONG PERFORMER

@ Copyright 2026 SpotQA, Creators of Virtuoso QA

Virtuoso QA is establishing the standard of proof for software releases. Its governed QA loop turns business requirements into tests for any browser-based application: AI proposes, a deterministic engine executes, a person approves what matters, and every decision leaves evidence.

Trust Center

AICPA

SOC

WAVE STRONG PERFORMER

@ Copyright 2026 SpotQA, Creators of Virtuoso QA

Virtuoso QA is establishing the standard of proof for software releases. Its governed QA loop turns business requirements into tests for any browser-based application: AI proposes, a deterministic engine executes, a person approves what matters, and every decision leaves evidence.

Trust Center

AICPA

SOC

WAVE STRONG PERFORMER

@ Copyright 2026 SpotQA, Creators of Virtuoso QA