How we teach ›Releasing courses
Testing your course locally

How we teach

Introduction to GraphAcademy’s Learning Philosophy

Developing a GraphAcademy course

Lesson Types

Releasing courses

Monitoring courses

Testing your course locally

You have reviewed your course content manually and with AI assistance. To ensure your course meets technical quality standards, you need to run automated tests.

In this lesson, you will learn how to run automated tests locally to validate your course structure and content.

Automated testing with Git hooks

GraphAcademy uses Git hooks to run tests automatically when you commit changes.

When you commit changes to course content, the pre-commit hook:

  1. Detects modified courses - Identifies which courses you’ve changed

  2. Runs QA tests - Tests only the courses you modified

  3. Blocks the commit - Prevents committing if tests fail

  4. Provides feedback - Shows exactly what needs to be fixed

This immediate feedback helps you learn and fix issues as you go, rather than discovering problems later during review.

bash
git commit -m "Update lesson content"

# Output:
# Running pre-commit QA tests...
# Running QA tests for courses: how-we-teach
# ✅ QA tests passed. Proceeding with commit...

Quality assurance tests

GraphAcademy uses automated tests to ensure all courses meet quality standards and structural requirements.

The QA tests verify:

  • Course metadata (caption, duration, key-points)

  • Module and lesson structure

  • Required attributes (:type:, :order:)

  • Content completeness (summaries, questions, hints, solutions)

  • Link validity

  • Cypher syntax validation

  • Admonition formatting

Running QA tests

To run the full QA test suite:

bash
npm run test:qa

This command runs jest qa.test.js which validates all active courses in the repository.

Testing specific courses

You can filter tests to specific courses using the COURSES environment variable:

bash
COURSES=how-we-teach npm run test:qa

To test multiple courses, use a comma-separated list:

bash
COURSES="neo4j-fundamentals,cypher-fundamentals" npm run test:qa

Skipping checks

During development, you may want to skip certain checks:

bash
# Skip link validation (useful when offline)
SKIP_LINK_CHECKS=true npm run test:qa

# Skip Cypher validation (requires database connection)
SKIP_CYPHER_CHECKS=true npm run test:qa

HTML generation tests

After building HTML files, you can validate they were generated correctly:

bash
npm run build:html
npm run test html

These tests check for:

  • Unresolved AsciiDoc directives

  • Broken header formatting

  • Missing or malformed HTML

Pull request templates

When you push your changes, the pre-push hook detects the type of change and suggests the appropriate PR template:

  • Course Release - When :status: active is added to a course

  • Course Draft - When a new course is created

  • Course Fix - When modifying an already active course

The hook provides a direct link to open a PR with the correct template:

bash
git push

# Output:
# ✅ Course(s) updated with :status: active added - this looks like a release
#
# 💡 Open a PR with the Course Release Template:
#
#    https://github.com/neo4j-graphacademy/courses/compare/main...your-branch?template=course_release.md

Best practices

  • Let the pre-commit hook catch issues early - don’t skip it

  • Fix test failures immediately while the context is fresh

  • Run QA tests manually during development: COURSES=your-course npm run test:qa

  • Address all test failures before creating a pull request

  • Test HTML generation before submitting for review

  • Use the suggested PR template when creating your pull request

Summary

In this lesson, you learned how to run automated tests locally to validate your course content.

You can use npm run test:qa to validate course structure, and filter tests using the COURSES environment variable.

In the next lesson, you will learn how to create a pull request and submit your course for review.

Chatbot

How can I help you today?