Implement v3.0 roadmap features

In this release, Schema.org validation and Google Structured Data validation have been split so markup can validated independently for technical correctness and for vendor compatibility.

There are easy to accommodate but breaking API changes in this release, which should provide a stable API foundation for future updates.

* Automatically detects Schema.org markup and tests it separately from vendor specific validation.
* You can now use `--schemas` to specify schemas to check for as well as to list them.
* You can optionally prefix schema names with 'jsonld:', 'microdata:', 'rdfa:' to check for a schema specified in a particular way (e.g. `--schemas  Article` or `--schemas jsonld:Article` or `--schemas Microdata:Article`).
* You can specify one or more schemas to check for, the same way the `--presets` option works (e.g. `--schemas "jsonld:Article,BreadcrumbList,microdata:WPFooter"`)
* Presets can now contain other presets (to any level), to allow for easier organisation of tests. e.g. use `--presets SocialMedia` to test social media markup, or `--presets Google` to apply rules based on those for the Google Structured Data Testing Tool.
* Presets can now have conditional tests to determine if a preset is invoked, which is useful when grouping presets inside other presets, so that groups of tests are only applied when appropriate.
* Individual tests within presets can now have conditional tests to determine if they should run.
* Added new preset called 'Google' which checks commonly used schemas for structured data properties that Google expects to see.
* Added a new preset called 'SocialMedia', containing both Twitter and Facebook presets.
* Removed `--disable-presets` option as is now redundant.
* All options available via both API and Command Line Tool.
* Updated README and inline documentation.

* This update does not validate if individual Schema.org schema properties exist or check if the contents of those properties are valid (this is possible with the API using a custom preset).
* The Google preset is contains subset of tests based on responses from the Google Structured Data Testing Tool and tests for all known Article schema types, but does not validate all supported Schemas or test the contents of properties using the same rules (this is possible with the API using a custom preset).

Author: Iain Collins

README.md

@@ -2,52 +2,52 @@
 
 Helps inspect and test web pages for Structured Data.
 
-Designed to allow automation and quick ad-hoc testing of structured data - especially in bulk or as part of a CD/CI pipeline.
+The structured data testing tool is designed to allow automation and quick ad-hoc testing of structured data - especially in bulk or as part of a CD/CI pipeline.
+
+This utility uses [web-auto-extractor](https://www.npmjs.com/package/web-auto-extractor) and [jmespath](https://www.npmjs.com/package/jmespath).
 
 ## Features
 
-* A Command Line Interface (`sdtt`) and an API for CD/CI integration.
+* Command Line Interface (`sdtt`) and an API for CD/CI integration.
 * Accepts any URL or a file to test (via string, buffer, stream…).
-* Tests pages for Schema.org markup in HTML (with microdata), JSON-LD and RDFa.
-* Tests `<meta>` tags for specific tags and values (e.g. for Twitter and Facebook sharing data, OpenGraph tags, App Store tags).
-* Tests if properties exist, should not exist and/or if they match a Regular Expression check.
-* Built-in 'presets' for testing common schema types (including all types of Article schemas).
+* Detects Schema.org markup in HTML (`microdata`), `JSON-LD` and `RDFa`.
+* Tests `<meta>` tags for specific tags and values (e.g. for social media / sharing).
+* Built-in presets for Twitter and Facebook tags.
+* Built-in presets for for testing and validating common structured data expected by Google.
 * API: Define your own re-useable, custom presets to write specific tests for your own site.
 * API: Use with a headless browser to test Structured Data injected by client side JavaScript (e.g. via Google Tag Manager).
 * CLI: Recognizes and displays info for all 1000+ schemas on Schema.org.
 
-This tool uses [web-auto-extractor](https://www.npmjs.com/package/web-auto-extractor) and [jmespath](https://www.npmjs.com/package/jmespath).
-
-Note: Schema.org does not define 'optional' and 'required' fields for schemas, it describes valid properties and what they may contain. Recommendations and tests in the built-in presets are based on practical errors and warnings returned by search engine providers.
-
 ## Install
 
     npm i structured-data-testing-tool -g
 
-## Features
-
 ## Usage
 
 ### Command Line Interface
 
-_Note: The API supports additional options not currently exposed in the CLI tool._
-
 ```
-Usage: sdtt --url <url> [--presets <presets>]
+Usage: sdtt --url <url> [--presets <presets>] [--schemas <schemas>]
 
 Options:
-  -u, --url              Inspect a URL
-  -f, --file             Inspect a file
-  -p, --presets          Test a URL for specific markup from a list of presets
-  -d, --disable-presets  Disable auto-detection of presets - will only evaluate explicitly specified presets
-  -s, --schemas          List valid schemas
-  -h, --help             Show help
-  -v, --version          Show version number
+  -u, --url      Inspect a URL
+  -f, --file     Inspect a file
+  -p, --presets  Test for specific markup from a list of presets
+  -s, --schemas  Test for a specific schema from a list of schemas
+  -h, --help     Show help
+  -v, --version  Show version number
 
 Examples:
-  sdtt --url "https://example.com/article"               Inspect a URL
-  sdtt --url <url> --presets "Article,Twitter,Facebook"  Test a URL for Article schema and social metatags
-  sdtt --presets                                         List supported presets
+  sdtt --url "https://example.com/article"       Inspect a URL
+  sdtt --url <url> --presets "Twitter,Facebook"  Test a URL for specific metatags
+  sdtt --url <url> --presets "SocialMedia"       Test a URL for social media metatags
+  sdtt --url <url> --presets "Google"            Test a URL for markup inspected by Google
+  sdtt --url <url> --schemas "Article"           Test a URL for the Article schema
+  sdtt --url <url> --schemas "jsonld:Article"    Test a URL for the Article schema in JSON-LD
+  sdtt --url <url> --schemas "microdata:Article" Test a URL for the Article schema in microdata/HTML
+  sdtt --url <url> --schemas "rdfa:Article"      Test a URL for the Article schema in RDFa
+  sdtt --presets                                 List all built-in presets
+  sdtt --schemas                                 List all supported schemas
 ```
 
 Inspect a URL to see what markup is found:
@@ -60,47 +60,76 @@ Inspect a file to see what markup is found:
 
 Test a URL contains specific markup:
 
-    sdtt --url <url> --presets "Article,Twitter,Facebook"
+    sdtt --url <url> --presets "Twitter,Facebook"
+
+Test a URL contains specific schema:
+
+    sdtt --url <url> --schemas "Article"
+
+Test a URL contains specific schema in both JSON-LD and in microdata/HTML:
+
+    sdtt --url <url> --schemas "jsonld:Article,microdata:Article"
 
 #### Example output from CLI
 
 ```
-$ sdtt -u https://www.bbc.co.uk/news/world-us-canada-49060410
+$ sdtt --url https://www.bbc.co.uk/news/world-us-canada-49060410 --presets Google,SocialMedia
 Tests
 
-  ReportageNewsArticle Passed 14 of 14 (100%)
+  Schema.org > ReportageNewsArticle - 100% (1 passed, 1 total)
+    ✓  schema in jsonld
+
+  Google > ReportageNewsArticle - 100% (12 passed, 12 total)
     ✓  ReportageNewsArticle
     ✓  ReportageNewsArticle[*]."@type"
-    ✓  ReportageNewsArticle[*].url
-    ✓  ReportageNewsArticle[*].mainEntityOfPage
-    ✓  ReportageNewsArticle[*].datePublished
-    ✓  ReportageNewsArticle[*].dateModified
     ✓  ReportageNewsArticle[*].author
-    ✓  ReportageNewsArticle[*].author.name
-    ✓  ReportageNewsArticle[*].image
+    ✓  ReportageNewsArticle[*].datePublished
     ✓  ReportageNewsArticle[*].headline
-    ✓  ReportageNewsArticle[*].publisher
+    ✓  ReportageNewsArticle[*].image
     ✓  ReportageNewsArticle[*].publisher."@type"
     ✓  ReportageNewsArticle[*].publisher.name
     ✓  ReportageNewsArticle[*].publisher.logo
+    ✓  ReportageNewsArticle[*].publisher.logo.url
+    ✓  ReportageNewsArticle[*].dateModified
+    ✓  ReportageNewsArticle[*].mainEntityOfPage
+
+  SocialMedia > Facebook - 100% (8 passed, 8 total)
+    ✓  must have page title
+    ✓  must have page type
+    ✓  must have url
+    ✓  must have image url
+    ✓  must have image alt text
+    ✓  should have page description
+    ✓  should have account username
+    ✓  should have locale
+
+  SocialMedia > Twitter - 100% (7 passed, 7 total)
+    ✓  must have card type
+    ✓  must have title
+    ✓  must have description
+    ✓  must have image url
+    ✓  must have image alt text
+    ✓  should have account username
+    ✓  should have username of content creator
 
 Statistics
 
   Number of Metatags: 38
   Schemas in JSON-LD: 1
      Schemas in HTML: 0
       Schema in RDFa: 0
-       Schemas found: ReportageNewsArticle
-     Test suites run: ReportageNewsArticle
-     Total tests run: 14
+  Schema.org schemas: ReportageNewsArticle
+       Other schemas: 0
+    Test groups run : 4
+     Total tests run: 28
 
 Results
 
-    Passed: 14 (100%)
+    Passed: 28 (100%)
   Warnings: 0 (0%)
     Failed: 0 (0%)
 
-  ✓ 14 tests passed.
+  ✓ 28 tests passed with 0 warnings.
 ```
 
 ### API
@@ -116,22 +145,22 @@ const { ReportageNewsArticle, Twitter, Facebook } = require('./presets')
 const url = 'https://www.bbc.co.uk/news/world-us-canada-49060410'
 
 structuredDataTest(url, { presets: [ ReportageNewsArticle, Twitter, Facebook ] })
-.then(response => {
+.then(res => {
   // If you end up here, then there were no errors
   console.log("All tests passed.")
-  console.log('Passed:',response.passed.length)
-  console.log('Failed:',response.failed.length)
-  console.log('Warnings:',response.warnings.length)
+  console.log('Passed:',res.passed.length)
+  console.log('Failed:',res.failed.length)
+  console.log('Warnings:',res.warnings.length)
 })
 .catch(err => {
   // If any test fails, the promise is rejected
   if (err.type === 'VALIDATION_FAILED') {
     console.log("Some tests failed.")
-    console.log('Passed:',err.passed.length)
-    console.log('Failed:',err.failed.length)
-    console.log('Warnings:',err.warnings.length)  
+    console.log('Passed:',err.res.passed.length)
+    console.log('Failed:',err.res.failed.length)
+    console.log('Warnings:',err.res.warnings.length)  
     // Loop over validation errors
-    err.failed.forEach(test => {
+    err.res.failed.forEach(test => {
       console.error(test)
     })
   } else {
@@ -193,13 +222,16 @@ const url = 'https://www.bbc.co.uk/news/world-us-canada-49060410'
 const MyCustomPreset = {
   name: 'My Custom Preset', // Required
   description: 'Test NewsArticle JSON-LD data is defined and twitter metadata was found', // Required
-  tests: [ // Required
+  tests: [ // Required (unless 'presets' specified)
     { test: 'NewsArticle', type: 'jsonld', schema: 'NewsArticle' },
     { test: '"twitter:card"', type: 'metatag' },
     { test: '"twitter:domain"', expect: 'www.bbc.co.uk', type: 'metatag', }
   ],
-  group: 'A Group Name', // Optional: A group name can be used to group tests in a preset (defaults to preset name)
-  // schema: 'NewsArticle', // Optional: A default schema for tests (useful if tests in a preset are all for the same schema)
+  // Options:
+  // group: 'My Group Name', // A group name can be used to group tests in a preset (defaults to preset name)
+  // schema: 'NewsArticle', // A default schema for tests (useful if tests in a preset are all for the same schema)
+  // presets: [] // Any preset can also contain other presets
+  // conditional: {} // Both Presets and Tests can define a conditional `test`, which is evaluated to determine if they should run
 }
 
 const options = {

__tests__/index.js

@@ -26,7 +26,7 @@ describe('Structured Data parsing', () => {
     // Ideally there would be multiple different fixtures that more robustly
     // test different scenarios, but this is is a practical approach that
     // improves coverage easily for now with minimal effort
-    await structuredDataTest(html)
+    await structuredDataTest(html, { presets: [ presets.Google ]})
     .then(response => {
       structuredDataTestResult = response
     })
@@ -50,15 +50,15 @@ describe('Structured Data parsing', () => {
   })
 
   test('should auto-detect when input is a string', async () => {
-    const result = await structuredDataTest(html.toString())
+    const result = await structuredDataTest(html.toString(), { presets: [ presets.Google ]})
     expect(result.passed.length).toBeGreaterThan(10)
     expect(result.failed.length).toEqual(0)
   })
 
   test('should auto-detect when input is a buffer', async () => {
     const result = await new Promise((resolve) => {
       fs.readFile(testFile, async (err, buffer) => {
-        return resolve(await structuredDataTest(buffer))
+        return resolve(await structuredDataTest(buffer, { presets: [ presets.Google ]}))
       })
     })
     expect(result.passed.length).toBeGreaterThan(10)
@@ -67,50 +67,51 @@ describe('Structured Data parsing', () => {
 
   test('should auto-detect when input is a readable stream', async () => {
     const buffer = fs.createReadStream(testFile)
-    const result = await structuredDataTest(buffer)
+    const result = await structuredDataTest(buffer, { presets: [ presets.Google ]})
     expect(result.passed.length).toBeGreaterThan(10)
     expect(result.failed.length).toEqual(0)
   })
 
   test('should auto-detect when input is an HTTP URL', async () => {
-    const result = await structuredDataTest('http://example.com')
+    const result = await structuredDataTest('http://example.com', { presets: [ presets.Google ]})
     expect(result.passed.length).toBeGreaterThan(10)
     expect(result.failed.length).toEqual(0)
   })
 
   test('should auto-detect when input is an HTTPS URL', async () => {
-    const result = await structuredDataTest('https://example.com')
+    const result = await structuredDataTest('https://example.com', { presets: [ presets.Google ]})
     expect(result.passed.length).toBeGreaterThan(10)
     expect(result.failed.length).toEqual(0)
   })  
 
   test('should work when explicitly invoked with HTML', async () => {
-    const result = await structuredDataTestHtml(html)
+    const result = await structuredDataTestHtml(html, { presets: [ presets.Google ]})
     expect(result.passed.length).toBeGreaterThan(10)
     expect(result.failed.length).toEqual(0)
   })
 
   test('should work when explicitly invoked with a URL', async () => {
-    const result = await structuredDataTestUrl('https://example.com')
+    const result = await structuredDataTestUrl('https://example.com', { presets: [ presets.Google ]})
     expect(result.passed.length).toBeGreaterThan(10)
     expect(result.failed.length).toEqual(0)
   })
 
-  test('should validate all structured data schemas found as well as any presets specified', async () => {
+  // @FIXME This test covers too much at once, should split out error handling checks
+  test('should validate all structured data schemas found as well as any presets specified and handle errors correctly', async () => {
     // Should validate schemas found, but also find errors as Facebook schema should not
     // be present in the example, but is passed as a preset so the test should fail.
     let result = ''
-    await structuredDataTest(html, { presets: [ presets.Facebook ] })
+    await structuredDataTest(html, { presets: [ presets.Facebook, presets.Google ] })
     .then(response => {
       result = response
     })
     .catch(err => {
       result = err
     })
-    expect(result.schemas.length).toEqual(4)
-    expect(result.schemas.includes('Facebook')).toBeFalsy()
-    expect(result.passed.length).toBeGreaterThan(10)
-    expect(result.failed.length).toBeGreaterThan(0)
+    expect(result.res.schemas.length).toEqual(4)
+    expect(result.res.schemas.includes('Facebook')).toBeFalsy()
+    expect(result.res.passed.length).toBeGreaterThan(10)
+    expect(result.res.failed.length).toBeGreaterThan(0)
   })
 
   test('should run all tests passed as options and for any schemas found', async () => {