Test an AI feature that reads images

Some AI features look at a picture and answer about it: they write alt text, describe a photo or decide whether an upload is allowed. In this tutorial you test two of them. First, alt text written by a vision model, scored by judges that look at the same photo. Then an image safety guardrail, scored by a plain text check.

It takes about an hour and makes about 20 model calls, so it costs a few cents on a typical provider. You need the test skills from Your first test and Improve your test.

You will learn to

• set up a chat test whose questions carry photos;
• upload photos in the question editor and avoid the two upload traps;
• read image previews, judge reasons and errors on the result page;
• test a guardrail that answers XTRUE or XFALSE with a rubric check;
• tell what a test of images can and cannot show.

Terms with a dotted underline are defined in the Glossary. Point at one to see a short definition; click or tap it to read the full entry.

How a question with an image runs

flowchart LR
    Q["Question<br/>text and photo"] --> M["Vision model<br/>gets text and photo"]
    M --> A["Answer"]
    A --> J["Judges score the answer<br/>and see the same photo"]
    J --> S["Score and verdict"]

Before you start

You need:

• The Administer AI Eval permission.
• A provider and a vision model for the feature under test. The demo site uses Claude Haiku 5.5 through OpenRouter.
• A model for the judges that can also read images. Each LLM judge uses the model set on its Edit prompt tab, otherwise the site judge.
• Five photos you may use. The demo site uses five photos from its own media library.

The screenshots come from the Northmoor demo site. The feature under test is the AI Automators plugin LLM: Image Alt Text, which writes the alt text of an image field.

Part 1: alt text

1. Find out what the feature sends

Open the code or the settings of the feature and note two things: the prompt, and where the prompt goes.

The Image Alt Text automator sends its prompt as one user message with the photo attached. It sends no system prompt. The form of the automator suggests the prompt Look at the image and make a good alt text out of it. The automator also adds a line that asks for a JSON reply. This test leaves that line out, so the model answers in plain text.

So in the test, the prompt goes in the question's Input (prompt) field and the System prompt stays empty. If your feature puts its prompt in a system message, put it in the System prompt field instead.

AI Eval does not run the automator itself. It sends the same prompt and photo to the same model, so this tests a plain-text version of the automator's request. To test the automator's exact output, keep its JSON line in the prompt and judge the JSON reply.

The field automator target does not fit

AI Eval can also run an automator on a field of a content type. That target skips questions with images, so it cannot test this feature.

2. Start a guided test in chat mode

Open Configuration > AI > AI Eval and click Create a test (guided). On the AI step:

1. Label: Tester: Alt text from photos.
2. Evaluation mode: Chat: prompt an AI provider directly.
3. Provider / Model: OpenRouter - Anthropic: Claude Haiku 5.5. Choose the model your feature uses.
4. System prompt: leave it empty.
5. Graders: turn on Relevance Grader and Completeness Grader.
6. Gate metric: Pass rate, with Gate threshold 0.8.

Under the hood: which models count as vision models

Before it sends a question with images, AI Eval asks the provider for the models that support image input. If the model is not on that list, the question is skipped. AI Eval trusts that list, so the check is only as good as the provider's answer. Before version 1.1.9, the OpenRouter provider listed all of its chat models as able to read images, so the check could not skip a question. From 1.1.9 it lists only the models whose input types on OpenRouter include images. With other providers, check on the provider's own model page that your model reads images.

Click Next.

3. Write five examples

The guided Examples step has no upload field, so write the text now and add the photos in step 5. Choose Create a new dataset for this test, give it a label and add five examples. All five use the same Input (prompt): Look at the image and make a good alt text out of it.

Every example has criteria that describe what the photo shows. Each also ends with the rules for alt text: The alt text is under 125 characters and does not start with "Image of" or "Picture of".

Question ID	What the criteria say the photo shows
dockside-sunrise	A wooden dock with small boats on calm water at sunrise.
plankton-microscope	A tiny see-through sea animal with long antennae, seen through a microscope.
cup-anemometer	A wind-speed instrument with spinning cups on a pole, with sea cliffs behind it.
rehab-pool	A large round blue pool under a clear roof, with a person in waders, a stretcher and a bucket of fish.
aquaculture-tanks	Two students looking into large indoor fish tanks, one holding a notepad.

Write the criteria from the photo itself, not from a guess. Open each photo and check every fact you put in the criteria.

Click Next. On the Review step click Save test, not Save and run: the questions have no photos yet. AI Eval opens the test's workflow page.

4. Prepare the photos

Two traps are easy to hit.

• The file type must match its name. The demo site's library photos are JPEG files named .png. AI Eval checks the real file type, so the first upload failed with the message below. Rename a copy of the file so its extension matches what it is, here .jpg.
• Large photos cost more and may not show. The full-size photos are 2 to 3 MB. Resize copies to about 1024 pixels wide first. The walk below used copies of 56 to 151 KB.

Under the hood: what AI Eval accepts

Images can be png, jpeg, webp or gif, up to 5 MB each and 5 per question. AI Eval checks the extension, the real image type and the size when you save. The results page shows a preview only when the image is 256 KB or smaller. Images in questions lists the rules.

5. Upload one photo per question

Open AI Eval > Manage > Datasets and click the dataset of this test. Click ✎ on dockside-sunrise. Near the bottom of the editor, under Files, find Upload images. Click Choose Files and pick the photo.

Click the Save inside the question editor, not the one for the dataset. The upload happens then. Open the question again and Files now holds a row: the file name and a private:// address. AI Eval keeps the file in private storage when the site has it.

Repeat for the other four questions. To replace a photo, click Remove on its Files row first, then upload the new one. If you only upload, a photo with a different file name is added as a second photo, and one with the same file name is refused.

6. Run the test

Open the test's workflow page and click Run under Run (or schedule). Keep the page open: the run only advances while it is open, as in Your first test. On the demo site it took three to four minutes.

The test makes five answers and, with two judges, ten judge scores: 15 model calls when nothing is retried or skipped.

7. Read the result

Click View results. Expand a question: it shows its photo's file name, your criteria, the model's reply and each judge's reason. The photo itself shows as a small preview when it is 256 KB or smaller and the page has not already shown 2 MB of previews.

On the demo site the run with the 1024 pixel photos gave this:

• 3 of 4 scored examples passed, so the pass rate was 75% and the gate failed against the 80% threshold. A fifth example, aquaculture-tanks, was not scored: the Relevance judge hit a 30 second time-out (cURL error 28). It still shows the Completeness score of 2.
• Every alt text was far longer than 125 characters. The prompt never asks for a length, so the model wrote a paragraph. Both judges said so in their reasons, and both scored 3 or 4 instead of 5. That is a real finding about the feature: its prompt does not ask for short alt text.
• rehab-pool failed with 3.00. The model wrote "a white bucket holding tools". The photo shows a bucket of fish, and the judges noticed.
• The first run, with the full-size 2 to 3 MB photos, showed no previews. The page said "Preview not shown: the image is too large for this page." and gave the file name and size. The model read about 4,700 input tokens per question there, against 950 to 1,400 with the small photos. Two judges timed out that time.

Two judges, one complaint: move countable rules into a check

Both judges marked every answer down for the same rule, the 125-character limit. When every judge repeats one rule, the score mostly measures that rule, and you cannot see how well the alt text describes the photo.

A rule you can count belongs in a check, not in a judge's criteria. Keep the criteria to what the photo shows. For the length, open the test's edit form, set Response char limit to 125 and turn on Format Grader. It reports too long (N chars, max 125) on each long answer. It takes off only one point of five, so a long answer can still pass. A check that fails every answer over the limit needs a pattern check, which the rubric editor does not offer yet (#3594870).

Common mistakes

• A time-out is not a verdict. Both runs had judge time-outs. A question with a judge error is left out of the pass rate. Run again before you decide anything from one error.
• Trusting a judge that cannot see. AI Eval relies on the provider's list to know whether the judge model reads images. A model that cannot read them may still return a score from the text alone. Choose a judge model that reads images, and check it against your own labels.
• Reading too much into one run. With four scored questions the true pass rate could be anywhere from 30% to 95%. The run page says so.

8. A model that cannot read images

If the provider does not list the model under test as able to read images, AI Eval does not send the question. The question is skipped with the reason This model cannot read images. It gets no score and does not count as a zero or a fail. A judge whose model the provider does not list returns no score and says The judge model cannot read images. The other judges still score the question.

This tutorial shows no screenshot of that screen. When it was written, the demo site ran an OpenRouter provider older than 1.1.9, which counted every model as able to read images, so a skipped question could not be produced. The text above comes from the code, not from a run.

Part 2: a guardrail that must not over-block

Some sites check each uploaded image with an AI model and refuse unsafe ones. The demo site has this rule: AI image safety (Media: Image) from the recipe ai_recipe_validations_image_safety. The model must answer exactly XTRUE when the image is safe or XFALSE when the upload must be blocked.

A guardrail can fail in two ways. It can let an unsafe image through. It can also block a good one, and then editors cannot upload photos they are allowed to use. This part tests the second failure.

9. Copy what the guardrail sends

Open Structure > Field validation, edit the rule set AI image safety (Media: Image) and open its rule Block unsafe imagery (/admin/structure/field_validation/manage/media_image). Copy its prompt and its message. The rule's code builds the request like this:

• a system message: the rule's prompt, a line break, then the rule's message text;
• a user message: the file ID as text, with the image attached;
• it counts the image as allowed when the reply contains XTRUE.

The model is the site's default for image chat, here Claude Haiku 5.5.

Make a second guided test, Chat mode, the same model. In System prompt, paste the prompt, add a line break, then paste the message. In each example, put a file ID in Input (prompt), as the guardrail does.

10. Pick safe but tricky photos

Use photos that are safe for a public site but could look odd to a strict classifier. The demo site has no statue or sports photos. These three were the closest: a gloved hand with a yellow ear-tag and pliers, a bare arm holding a wet net on a beach, and the pool from part 1 with its stretcher. All three are safe, so every answer must be XTRUE.

Do not use unsafe images for this. To prove that the guardrail does block unsafe images, you need labeled unsafe test images kept off public pages. This tutorial does not show them.

11. Score with a text check

An LLM judge adds nothing here. The answer is one word. Use a rubric check instead.

Go to AI Eval > Manage > Rubrics and click Add rubric. Fill in:

• Rubric ID: tester_image_guardrail_safe
• Version: 1.0
• Label: Tester: guardrail says XTRUE
• Scoring: combine: all_pass

Click + Add check, keep Must contain any of these, click Add phrase and type XTRUE. Click Save.

The check ignores upper and lower case unless Case sensitive is on. The guardrail looks for the uppercase XTRUE, so turn Case sensitive on if you want the same strictness. The walk left it off. Either way the check passes when XTRUE appears anywhere in the reply, not only when the reply is exactly XTRUE.

Then, in the guided test: turn on only Rubric Checks Grader, set Gate threshold to 1 (every safe photo must pass) and give each example the Rubric reference Tester: guardrail says XTRUE. Click Save test, then upload one photo to each question as in step 5, and click Run.

12. Read the verdicts

On the demo site all three photos got XTRUE, the gate passed and the run took 12 seconds and three model calls. The guardrail did not over-block these three photos. Three photos are a small sample: a pass here is not proof.

What this test cannot show

• One rubric per expected answer. The rubric editor offers only Must contain any of these and Must not contain any of these (#3594870). To expect XFALSE for some photos, make a second rubric that must contain XFALSE and set it as the Rubric reference of those questions. Each question has its own reference, so both kinds can share one test.
• Unsafe images are out of scope. See step 10.
• The model is the guardrail. If the site changes the model or the prompt, run the test again.

Under the hood: why the test mirrors the guardrail

The guardrail and the test call the same provider and model with the same system prompt and the same photo, so the test asks the model what the upload form asks. It is a separate call, so the model can still answer differently from one call to the next. The test also sends the file ID you type, not the ID of the copy AI Eval stores, and that ID is part of the text the model reads.

Check yourself

The provider does not list the model under test as able to read images. What does the result page show for the question?

It shows the question as skipped, with the reason "This model cannot read images." It has no score and does not count as a fail or a zero.

You upload a file named photo.png that is really a JPEG. What happens?

AI Eval refuses it when you save the question: "Upload a png, jpeg, webp or gif image. The filename and contents must match." Rename a copy with the right extension.

A judge returns a score for a photo question, but its model cannot read images. Can you trust the score?

No. It may have scored from the text alone. Use a judge model that reads images and check it against your own labels.

Three safe photos all got XTRUE. Is the guardrail good?

Not yet. Three photos show that it did not over-block those three. It says nothing about unsafe images, and it says little about photos unlike these.

Done when

• A test with five photo questions has run, and you can say how many passed.
• You can name the problem the judges found in the alt text.
• You know which photo rules AI Eval enforces: real type, extension, size, five images per question.
• A guardrail test has run with a text check, and you can say what it does and does not prove.

Next steps

• Take the length rule out of the criteria and check it with the Format Grader, as in the tip after step 7. Then make the alt-text prompt ask for under 125 characters, run the test again and compare the two runs: Improve your test.
• Check your judges before you rely on them: Check a judge against your own labels.
• Read the reference rules: Images in questions and Rubrics and checks.