Add tests

Add tests#

This guide shows you how to add tests to the collective.html2blocks codebase. The tests use pytest and YAML files for parametrization. Run the whole suite with make test from the repository root.

Introduction: Test parametrization and the traverse fixture#

Tests in collective.html2blocks are parametrized with YAML files that define the input and the expected results. The traverse fixture extracts values from nested dictionaries and lists with a path-like syntax. To apply a function to the traversed value, append a colon and the function name, for example foo/bar:baz:len. Functions such as len, type and keys are supported by the fixture.

Testing the converter#

This section covers how to test the main converter functions, collective.html2blocks.converter.html_to_blocks and collective.html2blocks.converter.volto_blocks. These functions transform HTML input into Volto blocks. Tests verify that the conversion produces the expected block structure for each input scenario.

html_to_blocks function#

To add a test for html_to_blocks, edit tests/_data/test_html_to_blocks.yml and add a new entry under params:

params:
  - name: div with one paragraph
    src: <div><p>Hello World!</p></div>
    tests:
      - path: "len:"
        expected: 1
      - path: "0/@type"
        expected: slate
      - path: "0/plaintext"
        expected: Hello World!
      - path: "len:0/value"
        expected: 1
      - path: "0/value/0/type"
        expected: p
      - path: "0/value/0/children/0/text"
        expected: Hello World!

volto_blocks function#

To add a test for volto_blocks, edit tests/_data/test_volto_blocks.yml and add a new entry:

params:
  - name: Simple Case
    src: |
      <div><p>Hello</p> <p>World!</p></div>
    default_blocks: [{"@type": "title"}, {"@type": "description"}]
    tests:
      - path: "len:blocks"
        expected: 5
      - path: "len:blocks_layout/items"
        expected: 5

Test the web service endpoints#

This section describes how to test the FastAPI endpoints of collective.html2blocks. The endpoints expose the conversion over HTTP.

/html endpoint#

To add a test for the /html endpoint, edit tests/_data/test_services_html.yml and add a new entry:

params:
  - name: Simple Case
    src: |
      <div><p>Hello World!</p></div>
    converter: slate
    tests:
      - path: "len:"
        expected: 1
      - path: "0/@type"
        expected: "slate"
      - path: "0/plaintext"
        expected: "Hello World!"
      - path: "len:0/value"
        expected: 1
      - path: "0/value/0/type"
        expected: "p"
      - path: "0/value/0/children/0/text"
        expected: "Hello World!"

/volto endpoint#

To add a test for the /volto endpoint, edit tests/_data/test_services_volto.yml and add a new entry:

params:
  - name: Simple Case
    src: |
      <div><p>Hello</p> <p>World!</p></div>
    default_blocks: [{"@type": "title"}, {"@type": "description"}]
    additional_blocks: []
    tests:
      - path: "len:blocks"
        expected: 5
      - path: "len:blocks_layout/items"
        expected: 5

Testing blocks converters#

This section explains how to test the block converters for iframe, image, slate and table blocks. Test each converter with representative input and the expected output. Use YAML files for parametrization and the traverse fixture for assertions.

iframe#

To add a test for the iframe block converter, edit tests/_data/test_iframe_block.yml and add a new entry:

params:
  - name: soundcloud
    src: '<iframe width="480" height="270" src="https://w.soundcloud.com/player/?url=https%3A//api.soundcloud.com/tracks/1275507478&amp;color=%23ff5500&amp;auto_play=false&amp;hide_related=false&amp;show_comments=true&amp;show_user=true&amp;show_reposts=false&amp;show_teaser=true&amp;visual=true" allowfullscreen></iframe>'
    tests:
      - path: "0/@type"
        expected: 'soundcloudBlock'
      - path: "0/soundcloudId"
        expected: '1275507478'

image#

To add a test for the image block converter, edit tests/_data/test_image_block.yml and add a new entry:

params:
  - name: Image without scale
    src: '<img src="https://plone.org/news/item/@@images/44ae2493-53fb-4221-98dc-98fa38d6851a.jpeg" title="A Picture" alt="Picture of a person" class="image-right">'
    tests:
      - path: "0/@type"
        expected: 'image'
      - path: "0/url"
        expected: https://plone.org/news/item
      - path: "0/title"
        expected: "A Picture"
      - path: "0/alt"
        expected: "Picture of a person"
      - path: "0/size"
        expected: "m"
      - path: "0/align"
        expected: "right"

slate#

To add a test for the slate block converter, edit tests/_data/test_slate_block.yml and add a new entry:

params:
  - name: Simple paragraph
    src: <p>Hello World!</p>
    tests:
      - path: "0/@type"
        expected: 'slate'
      - path: "0/plaintext"
        expected: 'Hello World!'
      - path: "0/value/0/type"
        expected: 'p'
      - path: "0/value/0/children/0/text"
        expected: 'Hello World!'

table#

To add a test for the table block converter, edit tests/_data/test_table_block.yml and add a new entry:

params:
  - name: Table with br
    src: '<table class="plain"><tbody><tr><td><br/>Text</td></tr></tbody></table>'
    tests:
      - path: "0/@type"
        expected: "slateTable"
      - path: "0/table/basic"
        expected: False
      - path: "0/table/celled"
        expected: True
      - path: "0/table/compact"
        expected: False
      - path: "0/table/fixed"
        expected: True
      - path: "0/table/hideHeaders"
        expected: True
      - path: "0/table/inverted"
        expected: False
      - path: "len:0/table/rows"
        expected: 2
      - path: "0/table/rows/0/cells/0/type"
        expected: "header"
      - path: "0/table/rows/0/cells/0/value"
        expected: ['']
      - path: "0/table/rows/1/cells/0/type"
        expected: "data"
      - path: "0/table/rows/1/cells/0/value"
        expected: [{'text': "\nText"}]
Contents