|
| 1 | +# Testing Guide |
| 2 | + |
| 3 | +This document explains how to run tests for the obsidian-tracker plugin. |
| 4 | + |
| 5 | +## Quick Start |
| 6 | + |
| 7 | +```bash |
| 8 | +npm test |
| 9 | +``` |
| 10 | + |
| 11 | +That's it! The tests will run automatically. |
| 12 | + |
| 13 | +## Test Commands |
| 14 | + |
| 15 | +```bash |
| 16 | +npm test # Run all tests once |
| 17 | +npm run test:watch # Run tests in watch mode (re-runs on file changes) |
| 18 | +npm run test:coverage # Run tests with coverage report |
| 19 | +``` |
| 20 | + |
| 21 | +## What Gets Tested |
| 22 | + |
| 23 | +### Unit Tests |
| 24 | + |
| 25 | +Unit tests validate core logic without requiring Obsidian to be running. They test: |
| 26 | + |
| 27 | +- **Data collection functions** - How data is extracted from frontmatter, tags, etc. |
| 28 | +- **Parsing functions** - YAML configuration parsing and validation |
| 29 | +- **Edge cases** - Empty values, null, undefined, arrays, booleans, etc. |
| 30 | + |
| 31 | +### Current Test Coverage |
| 32 | + |
| 33 | +- `test/frontmatter-exists.test.ts` - Tests for the `frontmatter.exists` searchType |
| 34 | + - 12 test cases covering all edge cases |
| 35 | + - Validates non-empty strings, arrays, booleans, numbers |
| 36 | + - Validates empty strings, arrays, null, undefined are rejected |
| 37 | + |
| 38 | +## Test Structure |
| 39 | + |
| 40 | +``` |
| 41 | +test/ |
| 42 | +├── frontmatter-exists.test.ts # Unit tests for frontmatter.exists |
| 43 | +├── mocks/ |
| 44 | +│ ├── obsidian.ts # Mock Obsidian API |
| 45 | +│ └── d3.ts # Mock d3 library |
| 46 | +└── setup.ts # Jest setup file |
| 47 | +``` |
| 48 | + |
| 49 | +## Prerequisites |
| 50 | + |
| 51 | +1. **Node.js** - Version 18+ recommended |
| 52 | +2. **npm** - Comes with Node.js |
| 53 | +3. **Dependencies** - Run `npm install` first |
| 54 | + |
| 55 | +## First Time Setup |
| 56 | + |
| 57 | +```bash |
| 58 | +# Install dependencies (including Jest) |
| 59 | +npm install |
| 60 | + |
| 61 | +# Verify tests work |
| 62 | +npm test |
| 63 | +``` |
| 64 | + |
| 65 | +If you encounter issues with npm install (e.g., obsidian package integrity errors), see [Troubleshooting](#troubleshooting) below. |
| 66 | + |
| 67 | +## Writing New Tests |
| 68 | + |
| 69 | +### Example Test Structure |
| 70 | + |
| 71 | +```typescript |
| 72 | +import { describe, it, expect, beforeEach } from '@jest/globals'; |
| 73 | +import { SearchType, Query } from '../src/data'; |
| 74 | +import { yourFunction } from '../src/your-module'; |
| 75 | + |
| 76 | +describe('Your Feature', () => { |
| 77 | + let query: Query; |
| 78 | + |
| 79 | + beforeEach(() => { |
| 80 | + // Set up test data |
| 81 | + query = new Query(0, SearchType.YourType, 'target'); |
| 82 | + }); |
| 83 | + |
| 84 | + it('should do something', () => { |
| 85 | + const result = yourFunction(query); |
| 86 | + expect(result).toBe(true); |
| 87 | + }); |
| 88 | +}); |
| 89 | +``` |
| 90 | + |
| 91 | +### Test File Naming |
| 92 | + |
| 93 | +- Test files should be named `*.test.ts` or `*.spec.ts` |
| 94 | +- Place them in the `test/` directory |
| 95 | +- Jest will automatically find and run them |
| 96 | + |
| 97 | +## Mocking Obsidian API |
| 98 | + |
| 99 | +Since tests run outside Obsidian, we mock the Obsidian API. See `test/mocks/obsidian.ts` for examples. |
| 100 | + |
| 101 | +To use mocks: |
| 102 | + |
| 103 | +```typescript |
| 104 | +import type { CachedMetadata } from 'obsidian'; |
| 105 | + |
| 106 | +const fileCache: CachedMetadata = { |
| 107 | + frontmatter: { |
| 108 | + field: 'value' |
| 109 | + } |
| 110 | +}; |
| 111 | +``` |
| 112 | + |
| 113 | +## Troubleshooting |
| 114 | + |
| 115 | +### npm install fails with obsidian package error |
| 116 | + |
| 117 | +If you see integrity check errors for the obsidian package: |
| 118 | + |
| 119 | +```bash |
| 120 | +# Clear npm cache |
| 121 | +npm cache clean --force |
| 122 | + |
| 123 | +# Remove node_modules and reinstall |
| 124 | +rm -rf node_modules package-lock.json |
| 125 | +npm install |
| 126 | +``` |
| 127 | + |
| 128 | +### Tests fail with "Module not found" |
| 129 | + |
| 130 | +Make sure all dependencies are installed: |
| 131 | + |
| 132 | +```bash |
| 133 | +npm install |
| 134 | +``` |
| 135 | + |
| 136 | +### TypeScript errors in tests |
| 137 | + |
| 138 | +Check that `ts-jest` is installed: |
| 139 | + |
| 140 | +```bash |
| 141 | +npm install --save-dev ts-jest@29 @types/jest@29 |
| 142 | +``` |
| 143 | + |
| 144 | +## Continuous Integration |
| 145 | + |
| 146 | +These tests can be run in CI/CD pipelines: |
| 147 | + |
| 148 | +```yaml |
| 149 | +# Example GitHub Actions |
| 150 | +- name: Run tests |
| 151 | + run: npm test |
| 152 | +``` |
| 153 | +
|
| 154 | +## Manual Testing (Obsidian) |
| 155 | +
|
| 156 | +For visual/end-to-end testing, you still need to test in Obsidian: |
| 157 | +
|
| 158 | +1. Build the plugin: `npm run build` |
| 159 | +2. Copy to test vault: See `test-deploy.sh` or `TEST_SETUP.md` |
| 160 | +3. Enable plugin in Obsidian |
| 161 | +4. Test with real notes |
| 162 | + |
| 163 | +See `docs/dev/issue-497/TESTING_GUIDE.md` for detailed manual testing instructions. |
| 164 | + |
| 165 | +## Coverage Reports |
| 166 | + |
| 167 | +Generate coverage reports: |
| 168 | + |
| 169 | +```bash |
| 170 | +npm run test:coverage |
| 171 | +``` |
| 172 | + |
| 173 | +This creates a `coverage/` directory with HTML reports. Open `coverage/lcov-report/index.html` in a browser to view. |
| 174 | + |
| 175 | +## Best Practices |
| 176 | + |
| 177 | +1. **Write tests for new features** - Add tests when implementing new searchTypes or features |
| 178 | +2. **Test edge cases** - Empty values, null, undefined, arrays, etc. |
| 179 | +3. **Keep tests fast** - Unit tests should run in seconds |
| 180 | +4. **Mock external dependencies** - Don't require Obsidian or real files |
| 181 | +5. **Use descriptive test names** - "should count non-empty strings" not "test1" |
| 182 | + |
| 183 | +## Questions? |
| 184 | + |
| 185 | +- See `TEST_SETUP.md` for setup troubleshooting |
| 186 | +- Check existing test files for examples |
| 187 | +- Review Jest documentation: https://jestjs.io/docs/getting-started |
0 commit comments