Scan PDF files

Your application has various controls, which are elements that Tosca interacts with when you run your tests. To make this possible, you must first scan your application. This gets the necessary technical data into Tosca.

This topic explains how to scan PDF documents which you need for the following use cases:

You want to test text, image, or tables in a PDF file.
You want to exclude areas from a PDF comparison.

In all other cases, such as checking for broken links, you'll work with the Standard subset instead. For more information, check out PDF Modules.

Start the scan

To start the scan, follow these steps:

Right-click a Module folder and select Scan from the context menu, or use the dynamic menu Modules and select Scan->PDF. Alternatively, you can use the keyboard shortcut Ctrl + Shift + P.
Select the PDF file that you want to scan and select Open.

Add a content preview

You can make sure your scanned controls are accurate by checking the Content Preview of the PDF Scan. The Content Preview shows exactly what you've selected for your control. You may need to add it manually.

By default, the PDF Scan window shows the following:

The PDF file.
The names and types of the PDF controls you choose during the scan.

To display the content of a chosen control, select Show Content Preview in the ribbon menu.

This helps make sure your selection has the right content. It also gives you access to the Force optical recognition option, in case Tosca doesn't properly recognize a control's content.

Additional options in the scan interface

The PDF Scan menu also offers the following options:

Option	Description
Zoom	Change the zoom level of the PDF View.
Zoom Fit	Enlarge the scanned PDF to fit the PDF View.
Show scanned areas	Show or hide the scanned areas in the PDF View.
Select Document Language	Select the language of the scanned PDF. The PDF Scan uses this language for optical character recognition (OCR).

Choose your controls

There are different ways to define the PDF controls you want to add to your Module:

Define a control by its absolute position.
Define a control by its relative position to another element. This is useful if a PDF element doesn't have an absolute position, but always appears in a specific position to another PDF element.

Let's say you're testing invoices and want to verify that Net price shows the right price. Depending on the length of the itemized list, Net price might appear further up or down on the page. It doesn't have an absolute position. However, it always appears right above Gross price. So it always appears in a specific position relative to another element.
Define repetitive areas. This is useful if an element appears in the same area on multiple pages of the document.

Let's say you want to verify that the copyright notice appears at the bottom of all pages. Instead of defining the control separately for every single page, you can create a repetitive area for the entire document.

Choose your use case:

I want to define a control by absolute position.

If you choose this option, Tosca identifies a control by its location in your PDF file.

To scan, follow these steps:

In the ribbon menu of the PDF Scan, select the type of control you want to add to your Module: Text, Image, or Table.
In the PDF view of the scan, highlight the respective area with your mouse. This adds the control to your Module.
For Table controls, perform the following additional actions:
- Add the Content Preview.
- Specify the number of row or column headers, if applicable.
- If the gridlines don't match the table, select Edit Table to move the column lines and rescale rows. You can hold C and click to create a new column, or hold R and click to create a new row. If you need to move rows precisely, select Edit rows.
If you haven't yet, add the Content Preview. Then, ensure that your Text and Table controls have the right content:
- The control isn't missing important characters, such as spaces.
- The preview of the control's content matches the original in the PDF. If it doesn't, you can choose to Force optical recognition as an alternative recognition method.
Once you've defined all controls you want to add to the Module, save. Then either Scan New Document or Close.

I want to define a control by relative position.

If you choose this option, Tosca identifies a control (target control) by its location in relation to another element (anchor control).

The anchor control must meet the following requirements:

It's a text or an image.
It's uniquely identifiable. As a result, you can't use repetitive areas as anchor controls.
It's on the same page as the target control.

To scan, follow these steps:

In the PDF Scan, define two controls by their absolute position: anchor control and target control.
In the list of controls, right-click the anchor control. Then perform these actions:
- Depending on the type of control the anchor is, select Use as Text Anchor for ... or Use as Image Anchor for ... from the context menu.
- Select the target control from the list.
  
  Note that you can't change anchor controls back into regular controls.
Once you've defined all controls you want to add to the Module, save. Then, either Scan New Document or Close.

At runtime, Tosca searches the PDF file for the anchor control, and then calculates the location of the target control.

By default, Tosca looks for an anchor control that's an exact match for the text or image you defined. If this causes issues in your tests, you can configure a lower level of accuracy. For more information, check out Configure anchor controls. This topic also describes how to edit anchor controls or make them unique.

I want to define a repetitive area.

If you choose this option, you define a control that appears in the same area on multiple pages of your document.

To scan, follow these steps:

In the ribbon menu of the PDF Scan, select the type of control you want to add as a repetitive area: Text, Image, or Table.
In the PDF view of the scan, highlight the respective area with your mouse. Then, right-click the area and select Repetitive Area from the context menu.
Once you've defined all controls you want to add to the Module, save. Then, either Scan New Document or Close.

By default, Tosca looks for the repetitive area on all pages of your PDF. For information on how to exclude certain pages, check out Repetitive area controls.

When you create a Module with one or more repetitive areas, an additional ModuleAttribute Repetitive Area Exclusions is also generated. This allows you to prevent these areas from being executed on certain pages. In test steps that use the Module, you can do the following:

Select Odd numbered pages from the ModuleAttribute's ValueRange to exclude all odd numbered pages.
Select Even numbered pages from the ModuleAttribute's ValueRange to exclude all even numbered pages.
Specify as a Value on the ModuleAttribute the pages to exclude. To do so, use the following syntax: <n>;<n-n>; ....

Example: The value 1; 3-6; 9 excludes pages 1, 3, 4, 5, 6 and 9.

Edit controls during the scan

You can edit your controls during the scan:

To select an area, select it in the PDF View or on the list of controls.
To jump to a control in the PDF View, double-click the control on the list, or use the Jump icon.
To change the name of a control, double-click its name.
To change the size of an area or move it, manipulate the rectangle in the PDF View.
To redraw a control, select the Redraw icon in the list of controls.
To delete a control, select the Delete icon in the list of controls, or right-click the area in the PDF View and select Remove this control from the context menu.

Rescan

If you want to add or change controls in your Module, rescan your PDF file. Please note the following limitations:

You can't delete controls during the rescan.
You can't change the control type during the rescan.

To rescan, right-click the Module that you want to change and select Rescan from the context menu, or press Ctrl + Shift + R..

What's next

Now that you have your PDF Modules, you can start creating PDF TestSteps.