Skip to content
Tales

File

The file provider inspects a file that an earlier step produced — typically one written by an HTTP save block or by an exec tool. It asserts existence, size, hex digests, text and JSON content, and exposes the same data under the file.* namespace for capture.

When to use it

Section titled “When to use it”

Use it for

  • Asserting a downloaded artifact exists and has the expected size / hash.
  • Reading a tool’s JSON or text output file and asserting on its contents.
  • Capturing file metadata or parsed fields to drive later steps.

Don't use it for

  • Writing files — the file provider is read-only. Produce files with HTTP save or exec.
  • Reading arbitrary host paths. Paths resolve under the scenario workspace (or the project dir for ${project.dir}/...).

Inspecting a file

Section titled “Inspecting a file”
step "file" "check_certificate" {
  path = result.download_certificate.path


  expect {
    exists     = true
    size_bytes = gt(0)
    sha512     = result.download_certificate.sha512
  }


  capture {
    path   = file.path
    size   = file.size_bytes
    sha512 = file.sha512
  }
}

path is the only required attribute.

  • A relative path resolves under scenario.workdir.
  • Reference project files with ${project.dir}/fixtures/document.pdf.
  • Paths that escape the workspace (and the project dir) are rejected.

JSON and text assertions

Section titled “JSON and text assertions”
step "file" "read_verify_result" {
  path = "exec/verify_certificate/stdout.json"


  expect {
    json = { valid = true }
  }


  capture {
    root = file.json.merkle.root
  }
}


step "file" "read_log" {
  path = "exec/verify_certificate/stderr.txt"


  expect {
    text = contains("warning")
  }
}

Missing files

Section titled “Missing files”

The provider does not fail just because a file is absent — it reports exists = false. A failure only occurs when an assertion or capture actually needs to read the file:

step "file" "must_be_absent" {
  path = "should-not-exist.tmp"
  expect { exists = false }   // passes when the file is missing
}

If json is asserted/captured and the file is not valid JSON, or text is asked for and the bytes are not valid UTF-8, the step fails with a clear error.

The file.* namespace

Section titled “The file.* namespace”
FieldTypeNotes
file.pathstringAbsolute resolved path.
file.existsboolWhether the file exists (and is not a directory).
file.size_bytesnumberFile size in bytes.
file.sha1 … file.sha512_256stringLowercase hex digests (sha1, sha224, sha256, sha384, sha512, sha512_224, sha512_256).
file.textstringFile contents as UTF-8 text (when requested).
file.jsondynamicParsed JSON (when requested).

Expectations

Section titled “Expectations”

exists, size_bytes, the sha* digests, text and json are all assertable; each accepts a literal or a matcher (gt(0), contains("..."), { valid = true }, …).