openwisp / openwisp/netjsongraph.js

[bug] Example mess! Missing browser tests, some examples are confusing

Open
#492 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug
Dominant language
JavaScript
Stars
314
Forks
119
Avg merge
18h 17m
Merged PRs (30d)
15

Description

There are several issues with the examples that are slowing down progress on this project.

Rather than fixing everything in a single pull request, contributors are encouraged to submit focused PRs that address specific examples. Please avoid using closes or fixes keywords in commit messages and pull request descriptions.

1. Missing browser tests

Many examples lack browser based tests that emulate basic user interactions and verify the primary purpose of each example. At a minimum, these tests should:

  • open the example page
  • verify that no JavaScript console errors are present
  • interact with the UI by clicking elements
  • move or manipulate visual elements when applicable
  • send keyboard input when required to validate functionality

Practical example of a browser test:

  • open the switch graph mode example
  • verify that it renders correctly, as done in other examples
  • click the icon that switches the graph mode
  • verify that the graph renders correctly after the mode change

The following examples can be skipped, as they are planned for removal in https://github.com/openwisp/netjsongraph.js/pull/425:

  • GraphGL
  • Animated links

2. Unclear purpose or broken functionality

The following examples are problematic and should be reviewed and fixed or removed.

  • Multiple interfaces
    Links are not visualized and the example appears broken. The intended purpose seems to be demonstrating that links can reference addresses listed in local_addresses, but currently nothing is shown.

  • Search elements
    It is unclear whether the search functionality works at all. Performing a search results in JavaScript console errors, both locally and in the online example. The search input UI is also very narrow, and submitting the search using the Enter key does not work, forcing users to click the search button.

  • Node expand or fold
    This functionality can be removed entirely, including the example and all related logic in the library. It is not used in OpenWISP and no longer provides clear value. The online example also produces a JavaScript error, and the offline version fails to load in the development environment with Uncaught ReferenceError: module is not defined.

  • Multiple links render
    This example should clearly demonstrate that two links exist between the same nodes. Ideally, both links should be rendered visually. Alternatively, if only a single link is shown, clicking it should clearly indicate in the sidebar that multiple links exist by displaying the details of both links.

  • JSONDataUpdate using override option
    The example file name does not match the button label. When opening the example, it is unclear what behavior is being demonstrated. The example should guide the user with a clear UI message explaining its purpose.

  • JSONDataUpdate using append option
    The example does not explain what it is demonstrating. It should guide the user with a UI message describing the expected behavior.

  • Append data using arrays
    As with the other data update examples, this example should guide the user with a UI message explaining what it is intended to demonstrate.

3. Consistent UI guidance for data update examples

All examples that demonstrate data updates should use a consistent approach for guiding users. Whether this is done via alerts, inline text, or another UI element, the mechanism and tone should be consistent across all related examples.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by choosing one unchecked example and compare its behavior with the browser tests for other examples. Review the selected example's page and existing test setup, then address only that focused problem. Done means the example's intended interaction works without console errors and has a browser test covering its primary behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
d3, javascript
Domain
frontend, testing
Issue type
Bug
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.