{"id":29225643,"url":"https://github.com/nu0ma/spanwright","last_synced_at":"2026-05-09T06:34:28.408Z","repository":{"id":302583052,"uuid":"1012560235","full_name":"nu0ma/spanwright","owner":"nu0ma","description":"CLI tool to generate Cloud Spanner E2E testing framework projects with Go database tools and Playwright browser automation","archived":false,"fork":false,"pushed_at":"2025-10-17T19:14:33.000Z","size":20920,"stargazers_count":2,"open_issues_count":10,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-18T00:09:29.842Z","etag":null,"topics":["go","playwright","spanner","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/spanwright","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nu0ma.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-07-02T14:14:24.000Z","updated_at":"2025-10-02T02:58:16.000Z","dependencies_parsed_at":"2025-07-03T06:35:55.036Z","dependency_job_id":"76edc891-0d2f-4b46-b525-436a5a47edd6","html_url":"https://github.com/nu0ma/spanwright","commit_stats":null,"previous_names":["nu0ma/spanwright"],"tags_count":33,"template":false,"template_full_name":null,"purl":"pkg:github/nu0ma/spanwright","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nu0ma%2Fspanwright","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nu0ma%2Fspanwright/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nu0ma%2Fspanwright/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nu0ma%2Fspanwright/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nu0ma","download_url":"https://codeload.github.com/nu0ma/spanwright/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nu0ma%2Fspanwright/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32809779,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"online","status_checked_at":"2026-05-09T02:00:06.633Z","response_time":123,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","playwright","spanner","typescript"],"created_at":"2025-07-03T07:11:14.752Z","updated_at":"2026-05-09T06:34:28.399Z","avatar_url":"https://github.com/nu0ma.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Spanwright\n\nCLI tool for generating Cloud Spanner E2E testing framework projects with Go database tools and Playwright browser automation.\n\n[![npm version](https://img.shields.io/npm/v/spanwright)](https://www.npmjs.com/package/spanwright)\n[![CI](https://github.com/nu0ma/spanwright/actions/workflows/ci.yml/badge.svg)](https://github.com/nu0ma/spanwright/actions/workflows/ci.yml)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/nu0ma/spanwright)\n\n## Features\n\n- **Scenario-based Testing** - Structured tests with seed data and browser automation\n- **Zero Config Setup** - Docker Spanner emulator management included  \n- **Go + Playwright** - Database tools with browser testing integration\n- **Multi-database Support** - Handle 1 or 2 Spanner databases per project\n\n## Architecture Overview\n\nSpanwright consists of two main components:\n\n- **Generator** (TypeScript CLI) - Interactive project creation tool\n- **Template** (Complete project scaffold) - Go database tools + Playwright tests + Make workflows\n\n### Generated Project Architecture\n```\nyour-project/\n├── cmd/seed-injector/          # Go CLI for database seeding\n├── internal/spanwright/        # Go internal packages (config, db, retry)\n├── scenarios/                  # Test scenarios with fixtures\n├── tests/                      # Test infrastructure\n└── Makefile                   # Workflow automation\n```\n\n## Tech Stack\n\nGenerated projects use:\n- **[Playwright](https://playwright.dev)** - Browser automation\n- **[testfixtures](https://github.com/go-testfixtures/testfixtures)** - YAML-based database seeding\n- **[wrench](https://github.com/cloudspannerecosystem/wrench)** - Spanner schema migrations\n- **[spalidate](https://github.com/nu0ma/spalidate)** - Database state validation\n- **[Cloud Spanner Go Client](https://cloud.google.com/go/spanner)** - Official Google client\n\n## Configuration Options\n\n### Interactive Mode (Default)\n```bash\nnpx spanwright my-project\n# Interactive prompts guide you through setup\n```\n\n### Non-Interactive Mode\n```bash\n# Single database setup\nexport SPANWRIGHT_DB_COUNT=1\nexport SPANWRIGHT_PRIMARY_DB_NAME=primary-db\nexport SPANWRIGHT_PRIMARY_SCHEMA_PATH=./schema\nnpx spanwright my-project --non-interactive\n\n# Two database setup\nexport SPANWRIGHT_DB_COUNT=2\nexport SPANWRIGHT_PRIMARY_DB_NAME=primary-db\nexport SPANWRIGHT_PRIMARY_SCHEMA_PATH=./schema\nexport SPANWRIGHT_SECONDARY_DB_NAME=secondary-db\nexport SPANWRIGHT_SECONDARY_SCHEMA_PATH=./schema2\nnpx spanwright my-project --non-interactive\n```\n\n### Environment Variables Reference\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `SPANWRIGHT_DB_COUNT` | Number of databases (1 or 2) | Interactive prompt |\n| `SPANWRIGHT_PRIMARY_DB_NAME` | Primary database name | Interactive prompt |\n| `SPANWRIGHT_PRIMARY_SCHEMA_PATH` | Path to primary schema | Interactive prompt |\n| `SPANWRIGHT_SECONDARY_DB_NAME` | Secondary database name | Interactive prompt |\n| `SPANWRIGHT_SECONDARY_SCHEMA_PATH` | Path to secondary schema | Interactive prompt |\n| `SPANWRIGHT_NON_INTERACTIVE` | Skip interactive prompts | `false` |\n\n## Usage Examples\n\n### Single Database E2E Testing\nPerfect for microservices or simple applications:\n\n```bash\nnpx spanwright e-commerce-tests\n# Choose: 1 database\n# Database name: main-db\n# Schema path: ./sql/schema\n```\n\n### Multi-Database Testing\nIdeal for complex systems with separate read/write databases:\n\n```bash\nnpx spanwright multi-tenant-tests\n# Choose: 2 databases\n# Primary: main-db (./schema/main)\n# Secondary: analytics-db (./schema/analytics)\n```\n\n\n## Test Scenarios\n\nGenerated projects include three example scenarios.\nThese are example scenarios to demonstrate the framework structure. You should customize or replace them with scenarios specific to your application's business logic and testing requirements.\n\nEach scenario includes:\n- **YAML fixtures** - Minimal seed data for testing\n- **Expected state files** - Database validation definitions\n- **Playwright tests** - Browser automation with inline SQL validation\n\n## Prerequisites\n\n- **Node.js** \u003e= 22.15.1\n- **Docker** - For Spanner emulator\n- **Go** - For database tools\n- **wrench** - [github.com/cloudspannerecosystem/wrench](https://github.com/cloudspannerecosystem/wrench)\n- **spalidate** - Install from [github.com/nu0ma/spalidate](https://github.com/nu0ma/spalidate)\n\n## Project Structure\n\n```\nyour-project-name/\n├── Makefile                    # Workflow automation\n├── schema/                     # Database schemas (.sql files)\n├── cmd/seed-injector/         # Go data seeding tool\n├── scenarios/                  # Test scenarios\n├── tests/                      # Test infrastructure\n└── playwright.config.ts       # Playwright configuration\n```\n\n## Common Commands\n\n```bash\n# Project setup\nmake init                       # Initialize project and install dependencies\nmake start                      # Start Spanner emulator\nmake setup                      # Setup databases and schemas\n\n# Testing\nmake test                       # Run complete E2E test workflow\nmake test-scenario SCENARIO=name  # Run E2E test for a specific scenario\n\n# Utilities\nmake stop                       # Stop Spanner emulator\nmake help                       # Show available commands\n```\n\n## Troubleshooting\n\n### Common Issues\n\n#### Docker/Emulator Problems\n```bash\n# Check if emulator is running\nmake start\n\n# Reset emulator state\nmake stop \u0026\u0026 make start\n```\n\n#### Schema Migration Issues\n```bash\n# Verify wrench installation\nwrench version\n\n# Check schema files\nls -la schema/\n\n# Manually apply migrations\nmake setup\n```\n\n#### Go Build Errors\n```bash\n# Check Go version (requires Go from .tool-versions)\ngo version\n\n# Clean and rebuild\ngo mod tidy\ngo build ./cmd/seed-injector\n```\n\n### Environment Issues\n- **Node.js version**: Requires \u003e= 22.15.1 for CLI\n- **Path issues**: Ensure schema paths exist and are accessible\n- **Permission issues**: Check Docker daemon permissions\n\n## Development\n\n### For Contributors\n\n#### Setup\n```bash\ngit clone https://github.com/nu0ma/spanwright.git\ncd spanwright\npnpm install\n```\n\n#### Development Workflow\n```bash\n# Build and test\npnpm run build\npnpm test  # Runs unit + E2E tests\n\n# Development mode\npnpm run dev  # Watch mode with auto-rebuild\n\n# Code quality\npnpm run lint\npnpm run format\n```\n\n#### Project Structure\n- `src/` - TypeScript CLI generator\n- `template/` - Complete project template\n- `e2e/` - End-to-end integration tests\n- `scripts/` - Build and development utilities\n\n### For Template Development\n1. Edit files in `template/` directory\n2. Test changes: `pnpm run build \u0026\u0026 pnpm test`\n3. Commit only after E2E tests pass\n\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnu0ma%2Fspanwright","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnu0ma%2Fspanwright","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnu0ma%2Fspanwright/lists"}