Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsCapture the current Appium screen as PNG bytes with Selenium’s TakesScreenshot API, then embed those bytes in a .docx file with Apache POI’s XWPF API. This avoids managing an intermediate image file and preserves the screenshot in the Word document. The example below assumes you already have a working Appium session and the desired screen is displayed.
What you need
- A Java project with the Appium Java client and its compatible Selenium dependencies. Appium’s Java client is built on Selenium, whose screenshot interfaces provide the capture API.
- A running Appium session whose driver can take screenshots, with the app already navigated to the screen you want.
- Apache POI’s
poi-ooxmldependency for creating a Word.docxdocument using XWPF.
Use dependency versions that are compatible with your project’s Java version, Appium server, and driver. The APIs shown here are the relevant components; the combined code is an implementation pattern, not a version-specific integration tested against every Appium and POI release.
Capture the screenshot and create the Word document
The code below takes a PNG screenshot in memory, inserts it into a paragraph, and writes appium-screenshot.docx to the current working directory. It assumes driver is an initialized Appium driver and is positioned at the screen to capture.
import java.io.ByteArrayInputStream;
import java.io.FileOutputStream;
import java.io.InputStream;
import org.apache.poi.util.Units;
import org.apache.poi.xwpf.usermodel.Document;
import org.apache.poi.xwpf.usermodel.XWPFDocument;
import org.apache.poi.xwpf.usermodel.XWPFParagraph;
import org.apache.poi.xwpf.usermodel.XWPFRun;
import org.openqa.selenium.OutputType;
import org.openqa.selenium.TakesScreenshot;
// Assumes `driver` is an initialized Appium driver and the desired screen is visible.
byte[] screenshot = ((TakesScreenshot) driver).getScreenshotAs(OutputType.BYTES);
// Choose a display width, then calculate the height from the screenshot's aspect ratio.
// Replace these values with dimensions appropriate for your page layout.
int imageWidthEmu = Units.toEMU(6.0);
int imageHeightEmu = Units.toEMU(10.0);
try (XWPFDocument word = new XWPFDocument();
InputStream imageStream = new ByteArrayInputStream(screenshot);
FileOutputStream output = new FileOutputStream("appium-screenshot.docx")) {
XWPFParagraph paragraph = word.createParagraph();
XWPFRun run = paragraph.createRun();
run.addPicture(
imageStream,
Document.PICTURE_TYPE_PNG,
"appium-screenshot.png",
imageWidthEmu,
imageHeightEmu
);
word.write(output);
}The Apache POI picture-insertion method takes an image stream, picture type, filename, width, and height; the dimensions are in EMUs. The sample’s 6-by-10-inch values are illustrative only. They may distort a screenshot whose aspect ratio differs. Calculate the height from the image’s actual pixel dimensions after choosing a width: heightInches = widthInches × pixelHeight ÷ pixelWidth, then convert both inches to EMUs with Units.toEMU. That keeps the image proportional. Leave enough room for the image within the document’s usable page width and height.
#1 Best Overall
Using the code in a test method
Place the capture and document-writing block after the test has navigated to the relevant screen and before the driver session is closed. If your driver variable is declared as a concrete Android or iOS driver type, the cast to TakesScreenshot makes the screenshot interface explicit. The required imports and output file path can be adapted to your project’s package and test structure.
Save to another location
Change the FileOutputStream path to an absolute path or a path under your test’s artifact directory. Create any parent directories before opening the stream. If the file is collected by a CI system, write it to the workspace or artifact directory that the CI job preserves.
Choose a screenshot output type
Selenium exposes three useful screenshot representations. For embedding in a Word document, bytes are usually the simplest route because POI accepts an input stream and no temporary image file is required.
| Output type | Useful when | What to account for |
|---|---|---|
OutputType.BYTES |
You want to pass screenshot data directly into the document workflow. | The screenshot stays in memory; wrap the byte array in a ByteArrayInputStream for POI. |
OutputType.FILE |
Your pipeline already works with image files or you also want a separate image artifact. | Selenium documents the returned file as temporary and says to copy it if you need it to persist. Copy or consume it promptly; do not treat it as the final saved artifact. |
OutputType.BASE64 |
You need a text representation for a transport or API. | Decode the Base64 data into image bytes before passing it to POI. |
The screenshot output interfaces document these forms. Regardless of the form chosen, the image supplied to the Word picture method must be valid image data matching the picture type you declare. For an Appium PNG screenshot, use Document.PICTURE_TYPE_PNG.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Adjust the document layout
Preserve the screenshot’s proportions
A screenshot is a rectangle with a particular pixel aspect ratio. If you set width and height independently without matching that ratio, the image will stretch or compress. Determine its pixel width and height, choose a target width that fits the document, and calculate the matching height. Convert the resulting inch measurements with Units.toEMU, as in the sample.
Rank #2
Choose where the picture appears
The example creates a new paragraph and adds the image to its run. To add a caption, create another paragraph after the image paragraph and write the caption text in its run. For multiple captures, repeat the paragraph-and-picture operation for each screenshot, using a distinct filename for each embedded picture. The filename is part of the insertion call; it is not the output document’s path.
Control output and resource handling
Try-with-resources closes the image stream, document, and file output stream even if writing fails. If your application writes to a different kind of output stream, close that stream according to its ownership rules. Keep the screenshot bytes only as long as needed if your test captures many screens, since retaining multiple full-size images increases memory use.
Understand what Appium captures
Appium describes screenshot capture as capturing the current viewport, window, or page. The precise surface depends on whether the session is in a native app context or a web context. This workflow embeds the screenshot Appium returns; it does not expand the capture to an entire scrollable page automatically.
Platform security can block screenshots. Appium’s screenshot documentation names Android’s FLAG_SECURE as an example. That documentation page is deprecated, so treat the example as a warning rather than a complete statement of behavior for every current driver version; consult the documentation for your Appium server and platform driver when investigating version-specific capture behavior.
Troubleshoot common failures
The driver cannot be cast to TakesScreenshot
Cause: The object referenced by driver does not expose Selenium’s screenshot interface, or it is not the active driver object you expect.
Rank #3
- Used Book in Good Condition
Fix: Confirm that the initialized Appium driver type and its Selenium dependencies support TakesScreenshot. Check the actual object used by the test, and ensure the screenshot call runs while the session is active.
Screenshot capture throws an error or returns no usable image
Cause: The session may have ended, capture may be blocked by platform security, or the current driver/context may not support the requested operation.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Fix: Verify that the Appium session is still running and the target screen is visible. If the app or device uses screenshot restrictions such as Android FLAG_SECURE, the platform may prevent capture; check current driver documentation and app policy rather than treating a failed call as a POI problem.
Word reports a corrupt image or cannot open the document
Cause: The bytes may not be a valid PNG, the declared picture type may not match the data, or the document write may have been interrupted.
Fix: Confirm that getScreenshotAs(OutputType.BYTES) completed successfully, use Document.PICTURE_TYPE_PNG for PNG bytes, and let POI finish writing before the test exits or the output file is consumed. Avoid sharing the output file with another process while it is being written.
Rank #4
The picture is stretched, clipped, or too large
Cause: The dimensions passed to addPicture do not fit the screenshot’s aspect ratio or the page’s usable area.
Free tools Windows power users keep installed
One-click scans. No signup required.
Fix: Calculate the height from the screenshot’s pixel dimensions and chosen width. Reduce the target width if it exceeds the document’s available text area; inspect page margins and orientation if the capture is unusually wide.
The document is missing from the expected folder
Cause: A relative path is resolved against the process’s current working directory, which may differ between a local IDE, command line, and CI runner.
Fix: Log or inspect the resolved output path, use an explicit artifact directory, and ensure the parent directory exists. Confirm that the CI job is configured to retain that directory.
The screenshot file disappears after the test
Cause: The workflow used OutputType.FILE and relied on Selenium’s temporary file as a persistent artifact.
Fix: Copy the temporary file to a durable location promptly, or use OutputType.BYTES and embed the result directly as shown above.
Or skip the browser setup
If your goal is to capture a website rather than a native mobile app screen, ScreenshotNeo offers a one-request screenshot API. It is not an Appium replacement for capturing an app running on a device; use it for web pages. The request below saves a WebP response:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. Cookie banners, newsletter popups, and chat widgets are removed before capture; bot checks, blank pages, and failed loads are not billed. An MCP server provides screenshot tools for AI agents, and the free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots. Learn about ScreenshotNeo, then sign up for the free plan.
Frequently Asked Questions
Can I add more than one Appium screenshot to the same Word document?
Yes. Create a separate paragraph and picture run for each capture, and use a distinct embedded filename for each image.
Does this method capture a full, scrollable mobile page?
No. It embeds the screenshot returned for the current viewport, window, or page; it does not automatically capture all scrollable content.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
