/source-map-tests

Primary LanguageHTML

WIP repo for source map test proof of concept

Running the tests

How to run in Firefox:

  • Check out mozilla-unified (see Firefox dev setup under "Setting up your machine" for details, note that you can use git via git-cinnabar)
  • cd to the checked out directory.
  • Run git am <this-repo>/firefox/0001-WIP-Firefox-source-map-spec-tests.patch
  • Run mach build (this builds the test too, you'll need to run it if you modify tests/harness)
  • Run mach test devtools/client/shared/source-map-loader/

How to run in WebKit:

  • Check out WebKit
  • cd to the checked out WebKit directory.
  • Run git am <this-repo>/webkit/0001-Add-harness-for-source-maps-spec-tests.patch
  • Run Tools/Scripts/build-webkit (depending on the platform you may need to pass --gtk or other flags)
  • Run Tools/Scripts/run-webkit-tests LayoutTests/inspector/model/source-map-spec.html (again, you may need --gtk on Linux)

Mozilla source-map library:

  • There is a branch for adding the spec tests to the package.

Goals of tests

  • Thoroughly test all aspects of the source maps spec that can be tested.
  • Strictly follow the spec when determining test behavior.

Test coverage

Core spec

  • Encoding
    • Source map must be a valid JSON document.
    • Base64 VLQ
      • VLQs should decode correctly
        • A VLQ with a non-base64 character will fail to decode.
        • A VLQ with one digit and no continuation digits should decode.
        • A negative VLQ with the sign bit set to 1 should decode.
        • A VLQ with non-zero continuation bits (and more than one digit) should decode.
        • A VLQ with a non-zero continuation bit with no further digits should fail to decode.
        • A VLQ should decode with the correct order of digits (least to most significant).
        • A long VLQ with many trailing zero digits will decode.
      • A VLQ exceeding the 32-bit size limit is invalid (note: the spec is unclear on the details of this limit)
      • A VLQ at exactly the 32-bit size limit should be decoded (positive and negative).
  • Basic format
    • version field
      • Must be present
      • Must be a number
      • Must be 3
    • file field
      • Optional, allow missing
      • Must be a string? (spec is not clear)
    • sourceRoot field
      • Optional, allow missing
      • Must be a string? (spec is not clear)
    • sources field
      • Must be present
      • Must be an array
      • Array elements must be null or a string
    • sourcesContent field
      • Must be present
      • Must be an array
      • Array elements must be null or a string
    • names field
      • Must be present (note: the spec implies this but implementations may not agree)
      • Must be an array
      • Array elements must be strings
    • mappings field
      • Must be present
      • Must be a string
      • Empty string is valid
    • ignoreList field
      • Optional, allow missing
      • Must be an array
      • Array elements must be numbers
      • Elements must not be out of bounds for the sources list
    • Extra unrecognized fields are allowed
  • Index maps
    • ? Must be mutually exclusive with non-index map?
    • file field
      • Optional, allow missing
      • Must be a string? (spec is not clear)
    • sections field
      • Must be present
      • Must be an array
      • An empty sections array is valid
      • Array elements are valid section objects
        • offset field
          • Must be present
          • line field
            • Must be present
            • Must be a number
          • column field
            • Must be present
            • Must be a number
        • map field
          • Must be present
          • Must be an object
          • Must be a valid source map
      • Sections are in order (the spec is not 100% clear, but assumption is increasing numeric order, may need subtests)
      • Sections are non-overlapping (the definition of overlap is not clear, may need subtests)
  • Mappings format
    • Each line is separated by ";"
    • A line may consist of zero segments (e.g., ";;")
    • Each line consists only of segments separated by ","
    • Must have greater than zero fields (note: many implementations don't check)
    • Must have 1, 4, or 5 fields
    • The source index must not be out of bounds of the sources array
    • The name index must not be out of bounds of the names array
    • Absolute VLQ values must be non-negative
      • The column must be non-negative
      • The source index must be non-negative
      • The original line must be non-negative
      • The original column must be non-negative
      • The name index must be non-negative
    • Relative VLQ values must be non-negative after adding to previous value
      • The column must be non-negative
      • The source index must be non-negative
      • The original line must be non-negative
      • The original column must be non-negative
      • The name index must be non-negative
  • Ignore list
    • An ignore list is optional, may be missing
    • An ignore list can't be a non-array value
      • An ignore list can be empty
      • An ignore list entry must be a number
      • An ignore list entry cannot be out-of-bounds of the sources array
    • Ignore list entries are detected and are present
    • Items not specified in the ignore list don't show up as ignored
  • Mappings semantics
    • A source map with no mappings does not map any position.
    • A single field segment gets mapped to the correct line and column.
    • A four field segment gets mapped to the correct line and column.
    • A five field segment gets mapped to the correct line and column.
    • When a name is present in a segment, it is correctly mapped.
    • When a source is present in a segment, it is correctly mapped.
    • The second occurence of a field segment in a line is mapped relative to the previous one.
    • When a new line starts, the generated column field resets to zero rather than being relative to the previous line.
    • For fields other than the generated column, a segment field that has occured once in a previous line is mapped relatively when it occurs in the next line.
    • Ensure that a transitive source map mapping works as expected
    • Index maps are correctly used in mappings
      • An index map with one sub-map will map correctly.
      • An index map with multiple sub-maps will map correctly, with appropriate offsets for the second and later sub-maps.
  • Resolution of sources
    • When sourceRoot is provided, it is prepended to any sources entries and will be mapped with the full URL.
    • If the source URL is an absolute URL, it is resolved as an absolute URL.
    • If the source URL is a relative URL, it is resolved relative to the source map path.
  • Wasm support
    • Create versions of the tests that use a Wasm source.

Scopes Proposal

TODO