CheckPDFText Method

Applies to TestComplete 14.30, last modified on November 21, 2019

Description

The File object for which you call this method corresponds to an item in the Stores > Files collection of your project. You use this method to compare the file with another PDF file or to update the stored file with data of the specified PDF file. The mode, in which the method functions, depends on TestComplete’s settings:

  • Comparison mode (default)

    This mode is used by default. The File object corresponds to a file stored in the Stores > Files collection of your project. The method compares the file with textual data of another PDF file, which you specify in the method parameter.

    To recognize the text, the method first sends the PDF file to the ocr.api.dev.smartbear.com web service running on the SmartBear website. This service forwards the file to Google Vision API and transfers the recognized text back to TestComplete.

    After that, the method compares the two files byte by byte and reports the result. You can use the AllowedDifference parameter to specify acceptable variations between the compared files, if needed. See the parameter description below.

    Note that you can use a third-party Diff utility for comparison. You set it in the Tools > Options > Engines > Stores dialog:

    Setting a Diff utility for comparison

    Click the image to enlarge it.

    In this case, the method will extract text data from the specified PDF file and then pass it for comparison to the specified utility.

  • Update mode

    In this mode, the ConvertToText(…) method replaces the contents of the Stores > Files item with the text of the specified PDF file.

    To enable this mode, do the following:

    1. Open the Tools > Options dialog box and select the Engines > Stores > Update files check box there,

      – and –

    2. Open the Stores > Files collection for editing and select the Update check box for the item that matches the File object.

      TestComplete PDF file comparison - Enable update mode

      Click the image to enlarge it.

Requirements

  • Your TestComplete version must be 14.20 or later.

  • Your computer must have access to the ocr.api.dev.smartbear.com web service.

    If you have firewalls or proxies running in your network, they should allow your computer to access the web service. This web service is used to recognize the text content of PDF files.

  • Your firewall must allow traffic through port 443.

  • You need an active license for the TestComplete Intelligent Quality add-on.

  • The Intelligent Quality add-on must be enabled in TestComplete.

    You can enable the add-on during TestComplete installation. If you did not enable the add-on during the installation, you can do this at any moment later via the File > Install Extensions dialog. Select File > Install Extensions from the TestComplete main menu and enable the Intelligent Quality > Intelligent Quality Core plugin in the resulting dialog.

  • PDF to Text support must be enabled in TestComplete.

    By default, it is enabled automatically if you enable the Intelligent Quality add-on during TestComplete installation.

    If you experience issues with PDF support in your tests, select File > Install Extensions from the TestComplete main menu and make sure the PDF to Text plugin is enabled (you can find it in the Intelligent Quality group). If the plugin is disabled, enable it. In the confirmation message, click the link to read a third-party license agreement. If you agree to the license terms, click Enable OCR.

Declaration

FileObj.CheckPDFText(FileName, AllowedDifference)

FileObj An expression, variable or parameter that specifies a reference to a File object
FileName [in]    Required    String    
AllowedDifference [in]    Optional    Integer Default value: 0   
Result Boolean

Applies To

The method is applied to the following object:

File

Parameters

The method has the following parameters:

FileName

Specifies the fully-qualified name of the PDF file to be used for comparison or for update.

AllowedDifference

Specifies the allowed difference, in bytes, between the text contents of the compared PDF files. You can use this parameter to hide minor differences between the files. If the number of bytes that differ is less than or equal to the parameter value, the method will report the files as equal. 0 means the files must be identical. See also File Checkpoints and How File Verification Works.

Do not obtain the difference value every time you are going to perform file comparison. You should calculate the difference once, and then use this value for future comparison. Otherwise, if you calculate the difference value right before performing comparison and then use it in the CheckPDFText method, the comparison will always be successful even if the compared files are different.

If the method works in the update mode, or if you use a third-party Diff utility for comparison, the parameter is ignored.

Result Value

In the update mode, the method always returns True.

In the comparison mode, if the method determines the files are equal, it returns True and posts a checkpoint message () to the test log.

Otherwise, the method returns False and posts an error message (). It also posts the "checkpoint failed" message and a detailed comparison report. The Details panel of the message shows the comparison summary. You can also click the Details link in the Link column of the message to open the File Comparison Result report that shows the difference between the baseline and the compared text content.

If you use a third-party Diff utility for file comparison, the method will also post a reference to the comparison report generated by the utility.

Remarks

By default, if the CheckPDFText method cannot find or access the PDF file to be compared, or the PDF file does not match its baseline copy, the method will wait for the PDF file to become accessible and for the comparison to complete successfully for the period the Tools > Current Project Properties > Playback > Auto-wait timeout setting specifies. If the method fails to access the PDF file, or if the PDF file does not match its baseline copy within this period, the comparison will fail.

Example

The following example shows how you can compare the text content of an actual PDF file and the contents of the Stores > Files item.

Note: In order for the code to run successfully, your project must have the Stores > Files collection.
JavaScript, JScript
Python
VBScript
DelphiScript
C++Script, C#Script

JavaScript, JScript

function CheckPDFTextContents()
{
  // Create a baseline text file
  var textFilePath = Project.Path + "baseline.txt";
  var expectedContents = "PDF file";
  f = aqFile.OpenTextFile(textFilePath, aqFile.faWrite, aqFile.ctANSI, true);
  f.Write(expectedContents);
  f.Close();

  // Check if the collection already contains an item
  // If it doesn't, add the created file to the collection
  if ((!Files.Contains("baseline")))
  {
    Files.Add(textFilePath, "baseline", false);
  }
  // Get the item containing the baseline text
  var item = Files.Items("baseline");

  // Get the PDF file to compare
  var pdfUrl = "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf";
  var pdfFilePath = Project.Path + "sample.pdf";
  var request = aqHttp.CreateGetRequest(pdfUrl);
  var responsePDF = request.Send();
  if (responsePDF != null && responsePDF.StatusCode == 200)
  {
    responsePDF.SaveToFile(pdfFilePath);

    // Check the PDF text content against the stored text file
    item.CheckPDFText(pdfFilePath);
  }

}

Python

def CheckPDFTextContents():
  # Create a baseline text file
  textFilePath = Project.Path + "baseline.txt"
  expectedContents = "PDF file"
  f = aqFile.OpenTextFile(textFilePath, aqFile.faWrite, aqFile.ctANSI, True)
  f.Write(expectedContents)
  f.Close()

  # Check if the colleciton already contains an item
  # If not, add the created file to the collection
  if not Files.Contains("baseline"):
    Files.Add(textFilePath, "baseline", False)
   
  # Get the item containing the baseline text 
  item = Files.Items("baseline")

  # Get a PDF file to compare 
  pdfUrl = "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"
  pdfFilePath = Project.Path + "sample.pdf"
  request = aqHttp.CreateGetRequest(pdfUrl)
  responsePDF = request.Send()
  if (responsePDF != None and responsePDF.StatusCode == 200):
    responsePDF.SaveToFile(pdfFilePath)

  # Check the PDF text contents against the stored text file
  item.CheckPDFText(pdfFilePath)

VBScript

Sub CheckPDFTextContents()
  ' Create a baseline text file
  textFilePath = Project.Path + "baseline.txt"
  expectedContents = "PDF file"
  Set f = aqFile.OpenTextFile(textFilePath, aqFile.faWrite, aqFile.ctANSI, True)
  f.Write(expectedContents)
  f.Close

  ' Check if the collection already contains an item
  ' If it doesn't, add the created file to the collection
  If Not Files.Contains("baseline") Then
    Call Files.Add(textFilePath, "baseline", False)
  End If
  ' Get the item containing the baseline text
  Set item = Files.Items("baseline")

  ' Get the PDF file to compare
  pdfUrl = "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"
  pdfFilePath = Project.Path + "sample.pdf"
  Set request = aqHttp.CreateGetRequest(pdfUrl)
  Set responsePDF = request.Send
  If Not responsePDF Is Nothing And responsePDF.StatusCode = 200 Then
    Call responsePDF.SaveToFile(pdfFilePath)

    ' Check the PDF text content against the stored text file
    item.CheckPDFText(pdfFilePath)
  End If

End Sub

DelphiScript

procedure CheckPDFTextContents();
var textFilePath, expectedContents, f, item;
var pdfUrl, pdfFilePath, request, responsePDF;
begin
  // Create a baseline text file
  textFilePath := Project.Path + 'baseline.txt';
  expectedContents := 'PDF file';
  f := aqFile.OpenTextFile(textFilePath, aqFile.faWrite, aqFile.ctANSI, true);
  f.Write(expectedContents);
  f.Close;

  // Check if the collection already contains an item
  // If it doesn't, add the created file to the collection
  if not Files.Contains('baseline') then
    Files.Add(textFilePath, 'baseline', false);
  // Get the item containing the baseline text
  item := Files.Items('baseline');

  // Get the PDF file to compare
  pdfUrl := 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf';
  pdfFilePath := Project.Path + 'sample.pdf';
  request := aqHttp.CreateGetRequest(pdfUrl);
  responsePDF := request.Send();
  if ((responsePDF <> nil) and (responsePDF.StatusCode = 200)) then
  begin
    responsePDF.SaveToFile(pdfFilePath);

    // Check the PDF text content against the stored text file
    item.CheckPDFText(pdfFilePath);
  end;

end;

C++Script, C#Script

function CheckPDFTextContents()
{
  // Create a baseline text file
  var textFilePath = Project["Path"] + "baseline.txt";
  var expectedContents = "PDF file";
  f = aqFile["OpenTextFile"](textFilePath, aqFile["faWrite"], aqFile["ctANSI"], true);
  f["Write"](expectedContents);
  f["Close"]();

  // Check if the collection already contains an item
  // If it doesn't, add the created file to the collection
  if ((!Files["Contains"]("baseline")))
  {
    Files["Add"](textFilePath, "baseline", false);
  }
  // Get the item containing the baseline text
  var item = Files["Items"]("baseline");

  // Get the PDF file to compare
  var pdfUrl = "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf";
  var pdfFilePath = Project["Path"] + "sample.pdf";
  var request = aqHttp["CreateGetRequest"](pdfUrl);
  var responsePDF = request["Send"]();
  if (responsePDF != null && responsePDF["StatusCode"] == 200)
  {
    responsePDF["SaveToFile"](pdfFilePath);

    // Check the PDF text content against the stored text file
    item["CheckPDFText"](pdfFilePath);
  }

}

See Also

About File Checkpoints
How File Verification Works
Files.Compare Method

Highlight search results