[internal] We need to talk about JGD

[nopeless]

The way tests are constructed is with JGD or so called (Javascript Graphics Description)

It is derived from the design of XPM

XPM is an image file format that is C code. Individual characters represent C code. More on http://www.xfree86.org/current/xpm.pdf . Example

Now, my initial reaction is that this is not maintainable, as we have far better tools and IDE support for image viewing in IDE. However, I can also see the advantages of using an XPM like representation in tests

So here are a few suggestions

A. Preserve jgd and only improve error checking and performance (no changes required for tests)
B. Use a "baseline" testing approach. Inputs images are on a directory under tests and the plugin is run against the images then outputs the image. Then, the developer checks the image output and determines if it is the desirable effect. If it is deemed correct, they run a cli command which replaces all baseline images with the new image. If any breaking change is made in the future, the cli will aleart.

Advantages of A

• jgd allows users to "write" images very fast compared to opening an image editor.
• Better for git diff*
• Allows text-based editors to see the original image in the test editor

Some git diff programs will improve png/jpeg blob diffs

Disadvantages of A

• You still have to create test result images in an image editor in most cases
• All tests cases have to be hand written
• Not standardized. Arbitrary characteres for colors made by the original developer

B improves

• Developers and users can see the exact output of a plugin
• Test images can be embedded into README with ease (the next branch might do this)
• Test cases are automatically generated as it accepts the input from images. Customization will be possible (testing library will be made)

[nopeless]

    const expectedImg = await Jimp.read(
      getTestDir(__dirname) + "/images/radius-3-circle.png"
    );
    const imgSrc = await jimp.read(
      mkJGD(
        "▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦",
        "▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦",
        "▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦",
        "▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦",
        "▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦",
        "▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦",
        "▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦",
        "▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦",
        "▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦",
        "▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦▦"
      )
    );

    expect(imgSrc.circle({ radius: 3 }).bitmap.data).toEqual(
      expectedImg.bitmap.data
    );

example of a unit test

[hipstersmoothie]

yeah these suck for sure. Never really been able to reliably use and understand them myself.

[hipstersmoothie]

I like the B approach. Using the output images in docs makes a lot of sense too.

To make it simpler we could have very simple to understand bmp images and use those for most tests.

[nopeless]

I like the B approach. Using the output images in docs makes a lot of sense too.

To make it simpler we could have very simple to understand bmp images and use those for most tests.

I'd like to have this discussion open for at least a few weeks and see what others think. If B is ultimately selected, I will write the underlying infrastructure for the test cases

[hipstersmoothie]

Sounds good! The tests we have should be simple and approachable as to encourage more people to write them 😄