Files

These BotAction's focus on reading and writing files to local disk, such as taking a saving a PNG screenshot or saving a PDF of the whole page.

These functions, and the Cookies' BotAction's, are all compatible with the higher-order files()() BotAction to inject an enriched (hydrated with safe defaults) BotFileOptions for all assembled actions.

BotAction's that implement the BotFilesAction interface, type their injects a little more specifically to expect BotFileOptions as the first one. This is what files()() does to its assembled BotAction's.

Files

A higher-order BotAction that will take a partial of BotFileOptions, enrich them with safe defaults, then inject it as the first inject for all assembled BotAction's in the second call.

Copy
const files = (fileOptions?: Partial<BotFileOptions>) =>
  (...actions: BotAction[]): BotAction =>
    inject(enrichBotFileOptionsWithDefaults(fileOptions))(
      errors('files()()')(...actions)
    )

Works great for BotAction's implementing the BotFilesAction interface.

For an usage example, see the Instagram example.

Screenshot

Takes a screenshot of the current page, where ever it's scrolled too, and saves it as a PNG file with the given file name.

Copy
const screenshot = (fileName: string, botFileOptions?: Partial<BotFileOptions>): BotFilesAction => 
  async (page, options) => {
    const hydratedOptions = enrichBotFileOptionsWithDefaults({...options, ...botFileOptions})

    const fileUrl = getFileUrl(hydratedOptions.screenshots_directory, hydratedOptions, fileName) + '.png'
    await page.screenshot({path: fileUrl})
  }

By default, saves the file in the local directory. You can change the directory where it's saved by overloading the BotFileOptions.

For an usage example, see the Screenshots Bot.

Screenshot All

Takes one screenshot of each URL provided. Filenames are created from urls by replacing nonsafe characters with underscores.

Copy
const screenshotAll = (urls: string[], botFileOptions?: Partial<BotFileOptions>): BotFilesAction => 
  forAll(urls)(
    url => ([
      goTo(url),
      screenshot(url.replace(/[^a-zA-Z]/g, '_'), botFileOptions) // filenames are created from urls by replacing nonsafe characters with underscores
    ])
  )

By default, saves the file in the local directory. You can change the directory where it's saved by overloading the BotFileOptions.

Example:

Copy
await chain(
  screenshotAll('https://google.com', 'https://twitter.com')
)(page)

Save PDF

Saves a PDF of the entire web page.

Copy
const savePDF = (fileName: string, botFileOptions?: Partial<BotFileOptions>): BotFilesAction => async(page, options) => {
  const hydratedOptions = enrichBotFileOptionsWithDefaults({...options, ...botFileOptions})

  const fileUrl = getFileUrl(hydratedOptions.pdfs_directory, hydratedOptions, fileName) + '.pdf'

  await page.pdf({path: fileUrl, format: 'A4'})
}

By default, saves the file in the local directory. You can change the directory where it's saved by overloading the BotFileOptions.

Example:

Copy
await chain(
  goTo('https://google.com'),
  savePDF('google-homepage') // saves: google-homepage.pdf
)(page)

Helpers

Botmation consolidates all BotAction's that read and write files to disk with the same Helpers to maintain consistency with how these files are managed.

If you're going to make other Local Disk related BotFilesAction's, please use these Helpers.

enrichBotFileOptionsWithDefaults()

This Helper standardizes the directory structure for file management. The word "enrich" in this project is like "hydrating" models, with the focus on safe defaults that don't break program execution.

Copy
enrichBotFileOptionsWithDefaults = (options: Partial<BotFileOptions> = {}): BotFileOptions => ({
  screenshots_directory: '',
  pdfs_directory: '',
  cookies_directory: '',
  ...options
})

The safe defaults is the local directory.

Let's look at the data structure BotFileOptions:

Copy
interface BotFileOptions {
  parent_output_directory?: string
  screenshots_directory: string
  pdfs_directory: string  
  cookies_directory: string
}

parent_output_directory is optional. It designates a directory ie "assets", "files", etc for all Files. If you specify any other directory, they will be put inside that parent_output_directory.

Otherwise, you can put the files in their own directories, locally.

createFolderURL()

Creates a folder url based on the names passed in with a pattern of starting with . (local) followed by each folder name with a preceding /.

Copy
const createFolderURL = (...folderNames: string[]): string => 
  folderNames.reduce((folderUrl, folderName) => folderUrl + '/' + folderName, '.')

Does not append a backslash. Therefore, can be used to create partial URL's or complete directory and filename URL's.

getFileUrl()

Builds a URL for the requested file type (specific directory option in BotFileOptions), and uses provided BotFileOptions to build a URL with the file name to the managed File.

Copy
const getFileUrl = (fileDirectory: string, filesOptions: BotFileOptions, fileName: string = ''): string => {
  const fileNameWithPrefix = fileName === '' ? '' : '/' + fileName 

  if (filesOptions?.parent_output_directory) {
    if (fileDirectory) {
      return createFolderURL(filesOptions.parent_output_directory, fileDirectory) + fileNameWithPrefix
    }

    return createFolderURL(filesOptions.parent_output_directory) + fileNameWithPrefix
  }

  if (fileDirectory) {
    return createFolderURL(fileDirectory) + fileNameWithPrefix
  }
  
  return './' + fileNameWithPrefix
}