Skip to content

libraries.md

Latest commit

 

History

History
102 lines (69 loc) · 4.31 KB

libraries.md

File metadata and controls

102 lines (69 loc) · 4.31 KB
Raw

Working on a Library

  • Details coming soon.

  • Tour of a Library

=== Raw Notes Below ===

Library

Javascript library of FarmData2 custom reusable functions.

  • Create a directory for each library
    • .js files for the library
    • .unit.cy.js files for the unit tests

Structure

  • Either
    • a single .js file containing the code for the library
    • or a barrel file that only exports a collection of other.js files in the directory that contain the code for the library.
      • the .js files must begin with a comment block with a single line description of the contents.

farmOS Permissions Checking

A component can check the permissions of the logged in farmOS user with appropriate function in farmosUtil.js.

If a permission needs to be checked that is not yet supported it can be added to the $perms array in the permissions function in modules/farm_fd2/src/module/Controller/FD2_Controller.php file.

Testing

  • test.bash --unit --lib
  • test.bash --unit --lib --glob="**/farmosUtil/*.unit.cy.js"
  • test.bash --unit --lib --glob="**/farmosUtil/farmosUtil.getFarmInstance.unit.cy.js"

Any it with an intercept should include { retries: 4 } to tolerate some of the flake that appears to go with cy.intercept.

Best practice is to reset the database state before tests are run. Doing this before every test or even at the start of every file adds significantly to the runtime of the test suite. FarmData2 compromises by resetting the database to the DB that was most recently installed (i.e. using installDB.bash) before each test run. A test run is one cypress command (e.g. as is done by test.bash --comp). Any test that absolutely requires a clean database (i.e. cannot tolerate changes made by prior tests) can reset it in its before hook using the following code:

  before(() => {
    cy.task('initDB');
  });

You can change the database that will be used for testing by using the installDB.bash script manually prior to running the tests. This is useful when you want to run tests against a pre-release of the sample database. For example:

installDB.bash --release=v3.1.0-development.3 --asset=db.sample.tar.gz

Use: cy.task('log', 'message') to log messages to the console. Use: cy.task('logObject', obj) to log an object to the console.

  • Visible in the console when running headless.
  • Click on the task in the test events output to print to console in Cypress gui.

Documentation

  • Docs are in docs/library

  • Generating the docs

    • npm run doc:gen

  • Viewing the docs

    • npm run doc:view

Documentation Conventions

Minimum expectations:

  • @module - in comment at the top of the file.
    • @module module:<moduleName>
  • @description <description> - to describe the module.
    • Include a short one sentence description here - it is extracted into the documentation index.
  • @param - for every parameter on every function.
    • @param {<type>} name - description of parameter
    • @param {<type>} [name = default] - description of parameter
  • @returns [{type}] [description] - on every function that returns a value.
    • @returns <type> [description]
      • use {Promise<type>} for functions that return a promise.
  • @throws - on any function that throws an exception.
    • @throws <type> description of when it is thrown.

Other tags that are often useful:

  • @category - organizing the functions in a module into categories.
  • @example - as appropriate.
    • example starts on next line and continues until next tag or end of comment.
  • @link - links inline with text.
    • blah blah [<link text>]{@link <link>} blah blah.
      • use #module:<moduleName/functionName for internal links.
  • @see - separate element that refers to another element.
    • @see module:<moduleName>/<functionName>
    • @see <link>

There are additional tags if ever an OO class definition is added.