31:T54e,md`You can of course use one of the [provided tests functions](#ttoc), but it should be quite simple to create your own. In fact a test is just a function which returns a new tests.Test object : \`\`\`js my_test = function(data, config = {}) { // Do what you want here let status = bad_values.length == 0; let msg = status ? "Everything's good" : "Oops, bad values !"; return new tests.Test({ msg: msg, status: status, level: 'warn', id: 'test_my_test', show_details: bad_values.length > 0, details: table(bad_values), details_summary: 'Show bad values' }); }; \`\`\` When creating the new tests.Test object, you can include the following properties : - \`msg\` : the message to be displayed as test result (for example "Test is ok", "There are X bad values", etc.) - \`status\` : a boolean which indicates if the test passes (\`true\`) or fails (\`false\`) - \`level\` : the test level, one of \`info\`, \`warn\` or \`error\` - \`id\` : a string identifying the test. Must be a valid HTML \`id\` attribute - \`show_details\` : a boolean which indicates if the test provides more detailed results - \`details\` : (optional) the more detailed results to be displayed - \`details_summary\` : (optional) a string giving the text used for the "Show details" element`32:[{"id":"71ab36fa8ac0c46fe4f2b96557c115b333722025bd0e199c3eafcf38e617dc3873d82df0233f0a40b3b9853be3615e5c40b4e12f87ba5d8dbce8c7aeb62eacb1","href":"https://static.observableusercontent.com/files/71ab36fa8ac0c46fe4f2b96557c115b333722025bd0e199c3eafcf38e617dc3873d82df0233f0a40b3b9853be3615e5c40b4e12f87ba5d8dbce8c7aeb62eacb1","name":"data_tests.csv","type":"text/csv","lastModified":1590504045003.324,"size":341}] 2f:{"title":"Data tests documentation","cells":[{"id":0,"value":"md`# Data tests documentation`","pinned":false,"hidden":false,"mode":"ojs"},{"id":376,"value":"tests_tests_badge","pinned":false,"hidden":false,"mode":"ojs"},{"id":11,"value":"md`[Data tests](https://observablehq.com/@juba/data-tests) provide a set of functions to ease creating and running tests on a dataset to ensure its quality and consistency. It is better aimed at datasets which are regularly updated : after a set of tests has been defined it can easily be run against any new data version.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":15,"value":"md`## Usage`","pinned":false,"hidden":false,"mode":"ojs"},{"id":17,"value":"md`### Import the tests notebook and your data`","pinned":false,"hidden":false,"mode":"ojs"},{"id":19,"value":"md`First, import the tests object from the following notebook :\n\n\\`\\`\\`js\nimport { tests } from '@juba/data-tests'\n\\`\\`\\`\n\nSome tests are applied on the raw content of a textual data file (CSV, XML, JSON...), but most of them are run against an already parsed d3 data array.\n\nHere we will load and parse a sample attached CSV file :\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":25,"value":"data = d3.csvParse(await FileAttachment(\"data_tests.csv\").text(), d3.autoType)","pinned":true,"hidden":false,"mode":"ojs"},{"id":31,"value":"md`### Define a test`","pinned":false,"hidden":false,"mode":"ojs"},{"id":33,"value":"md`To define and run a test, you have to create a cell which calls one of the tests functions. For example, we can run the \\`data_dimensions\\` function which returns the number of rows and columns of our dataset :`","pinned":false,"hidden":false,"mode":"ojs"},{"id":35,"value":"tests.data_dimensions(data)","pinned":true,"hidden":false,"mode":"ojs"},{"id":297,"value":"md`By default a test function only returns an object. We can display a formatted result of the test by using its \\`result\\` method :`","pinned":false,"hidden":false,"mode":"ojs"},{"id":282,"value":"tests.data_dimensions(data).result()","pinned":true,"hidden":false,"mode":"ojs"},{"id":37,"value":"md`Note that to avoid manually importing every function used in this notebook, we just imported the \\`tests\\` object which includes every function as a method. So each function will be called as \\`tests.function\\`.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":39,"value":"md`By default \\`data_dimensions\\` only returns an informative message. We can convert it to a test by giving the expected values as an array argument in a config object :`","pinned":false,"hidden":false,"mode":"ojs"},{"id":47,"value":"tests.data_dimensions(data, { expected: [5, 9] }).result()","pinned":true,"hidden":false,"mode":"ojs"},{"id":49,"value":"md`Each function has a different set of arguments to specify his behavior and expected values. Please refer to the [tests functions section](#tests_functions) for a list of functions and there documentation.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":54,"value":"md`You can change the test level to one of the three possible values : \\`info\\`, \\`warn\\` and \\`error\\`. Each level gives different message styles if the test fails :`","pinned":false,"hidden":false,"mode":"ojs"},{"id":58,"value":"tests.data_dimensions(data, { level: 'info', expected: [100, 100] }).result()","pinned":false,"hidden":false,"mode":"ojs"},{"id":60,"value":"tests\n .data_dimensions(data, {\n level: 'warn',\n expected: [100, 100],\n id: 'test_dims_warn'\n })\n .result()","pinned":false,"hidden":false,"mode":"ojs"},{"id":62,"value":"tests\n .data_dimensions(data, {\n level: 'error',\n expected: [100, 100],\n id: 'test_dims_error'\n })\n .result()","pinned":false,"hidden":false,"mode":"ojs"},{"id":325,"value":"md`### Define a series of tests`","pinned":false,"hidden":false,"mode":"ojs"},{"id":329,"value":"md`In general a notebook will define several tests. The best practice then is to group them into one or several arrays :`","pinned":false,"hidden":false,"mode":"ojs"},{"id":332,"value":"tests_format = [\n tests.data_dimensions(data),\n tests.date_format(data, 'date_ok', { format: '%Y-%m-%d' })\n]","pinned":true,"hidden":false,"mode":"ojs"},{"id":339,"value":"tests_values = [\n tests.not_trimmed(data),\n tests.numeric_range(data, \"age_ok\", { range: [18, 100] })\n]","pinned":true,"hidden":false,"mode":"ojs"},{"id":67,"value":"md`### View results`","pinned":false,"hidden":false,"mode":"ojs"},{"id":345,"value":"md`Once our tests arrays are defined, we can display the results by using \\`tests.results\\` :`","pinned":false,"hidden":false,"mode":"ojs"},{"id":347,"value":"tests.results(tests_format)","pinned":true,"hidden":false,"mode":"ojs"},{"id":354,"value":"md`You can pass several tests arrays to \\`tests.results\\` if you want to display all the results at once :`","pinned":false,"hidden":false,"mode":"ojs"},{"id":359,"value":"tests.results(tests_format, tests_values)","pinned":true,"hidden":false,"mode":"ojs"},{"id":362,"value":"md`### View results summary`","pinned":false,"hidden":false,"mode":"ojs"},{"id":82,"value":"md`Finally, you can automatically generate a table which summarises all the tests results in one or several tests arrays by using \\`tests.tables\\` :`","pinned":false,"hidden":false,"mode":"ojs"},{"id":84,"value":"tests.table(tests_format, tests_values)","pinned":true,"hidden":false,"mode":"ojs"},{"id":275,"value":"md`You can also display a summary badge to briefly display your global tests status with tests_badge. Note that tests with an info level are ignored :`","pinned":false,"hidden":false,"mode":"ojs"},{"id":278,"value":"tests.badge(tests_format, tests_values)","pinned":true,"hidden":false,"mode":"ojs"},{"id":233,"value":"md`### Create your own tests`","pinned":false,"hidden":false,"mode":"ojs"},{"id":236,"value":"$31","pinned":false,"hidden":false,"mode":"ojs"},{"id":99,"value":"html`

`","pinned":false,"hidden":false,"mode":"ojs"},{"id":87,"value":"tests_functions = md`# Tests functions`","pinned":false,"hidden":false,"mode":"ojs"},{"id":102,"value":"md`## Common arguments`","pinned":false,"hidden":false,"mode":"ojs"},{"id":105,"value":"md`Each test function accept a different set of arguments, but they all have some in common :\nthe first argument is the data object (parsed or textual) on which the test must be run, and\neach function also accepts a \\`config\\` object with at least two optional elements :\n- \\`level\\` indicates the test level : \\`info\\`, \\`warn\\` or \\`error\\`. It will override the default level used by each function.\n- \\`id\\` is used to identify the test and create the *show* link in the results table. A default value is generated and should be suitable, but you can manually specify one if needed.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":219,"value":"ttoc = tests_toc(\".tests-doc h2, .tests-doc h3\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":186,"value":"gen_doc()","pinned":false,"hidden":false,"mode":"ojs"},{"id":90,"value":"md`# Misc`","pinned":false,"hidden":false,"mode":"ojs"},{"id":108,"value":"md`### Documentation functions`","pinned":false,"hidden":false,"mode":"ojs"},{"id":208,"value":"// Source : https://observablehq.com/@mbostock/toc\nfunction tests_toc(selector = \"\") {\n return Generators.observe(notify => {\n let headings = [];\n\n function observed() {\n const h = Array.from(document.querySelectorAll(selector));\n if (h.length !== headings.length || h.some((h, i) => headings[i] !== h)) {\n notify(\n html`Tests list by category

' : '
'}${DOM.text(h.textContent)}`,\n { onclick: e => (e.preventDefault(), h.scrollIntoView()) }\n );\n }\n )}`\n );\n }\n }\n\n const observer = new MutationObserver(observed);\n observer.observe(document.body, { childList: true, subtree: true });\n observed();\n return () => observer.disconnect();\n });\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":115,"value":"gen_doc = () => {\n let docs = Object.values(tests)\n .filter(d => d.doc !== undefined)\n .map(d => d.doc);\n\n let doc_sections = d3.group(docs, d => d.category);\n\n let out = '';\n\n doc_sections.forEach((v, k) => {\n out += `\\n\\n## ${k}\\n\\n`;\n v.forEach(d => {\n out += gen_function_doc(d);\n });\n });\n\n out = md`${out}`;\n\n return md`
${out}
`;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":94,"value":"gen_function_doc = doc =>\n `\n\n### ${doc.title}\n\n${doc.description}\n\n\n\n\n${doc.args\n .map(\n arg =>\n ``\n )\n .join('')}\n\n
Argument Description Default
\\`${arg.name}\\` ${arg.desc} ${\n arg.default === undefined ? '' : arg.default\n }
\n\n
\n\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":188,"value":"styles = html``","pinned":false,"hidden":false,"mode":"ojs"},{"id":8,"value":"md`### Imports`","pinned":false,"hidden":false,"mode":"ojs"},{"id":373,"value":"import { badge as tests_tests_badge } from \"@juba/data-tests-tests\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":5,"value":"import { tests } from '@juba/data-tests'","pinned":false,"hidden":false,"mode":"ojs"},{"id":27,"value":"d3 = require(\"d3@5\", \"d3-array@2\")","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W32","stdlib":"1","titling":"auto"}