Commit bd961ad1 authored by Mayra Cabrera's avatar Mayra Cabrera

Reorders migrations readme file

The document is now split in two sections:
- Testing an ActiveRecord migration
- Testing an non-ActiveRecord migration

Both sections have an example
parent e520a946
...@@ -22,39 +22,33 @@ migrate the database **down** to the previous migration version. ...@@ -22,39 +22,33 @@ migrate the database **down** to the previous migration version.
With this approach you can test a migration against a database schema that this With this approach you can test a migration against a database schema that this
migration has been written for. migration has been written for.
Use `migrate!` helper to run the migration that is under test.
The `after` hook will migrate the database **up** and reinstitutes the latest The `after` hook will migrate the database **up** and reinstitutes the latest
schema version, so that the process does not affect subsequent specs and schema version, so that the process does not affect subsequent specs and
ensures proper isolation. ensures proper isolation.
## Testing a class that is not an ActiveRecord::Migration
In order to test a class that is not a migration itself, you will need to
manually provide a required schema version. Please add a `schema` tag to a
context that you want to switch the database schema within.
Example: `describe SomeClass, :migration, schema: 20170608152748`.
## Available helpers ## Available helpers
Use `table` helper to create a temporary `ActiveRecord::Base` derived model Use `table` helper to create a temporary `ActiveRecord::Base` derived model
for a table. for a table.
See `spec/support/helpers/migrations_helpers.rb` for all the available helpers.
## Testing a class that is an ActiveRecord::Migration
In order to test a class that is an `ActiveRecord::Migration`, you will need to
manually `require` the migration file because it is not autoloaded with Rails.
Use `migrate!` helper to run the migration that is under test. It will not only Use `migrate!` helper to run the migration that is under test. It will not only
run migration, but will also bump the schema version in the `schema_migrations` run migration, but will also bump the schema version in the `schema_migrations`
table. It is necessary because in the `after` hook we trigger the rest of table. It is necessary because in the `after` hook we trigger the rest of
the migrations, and we need to know where to start. the migrations, and we need to know where to start.
See `spec/support/migrations_helpers.rb` for all the available helpers. ### Example
## An example This spec tests the [`db/post_migrate/20170526185842_migrate_pipeline_stages.rb`](https://gitlab.com/gitlab-org/gitlab-ce/blob/v11.6.5/db/post_migrate/20170526185842_migrate_pipeline_stages.rb) migration. You can find the complete spec on [`spec/migrations/migrate_pipeline_stages_spec.rb`](https://gitlab.com/gitlab-org/gitlab-ce/blob/v11.6.5/spec/migrations/migrate_pipeline_stages_spec.rb).
```ruby ```ruby
require 'spec_helper' require 'spec_helper'
# Load a migration class.
require Rails.root.join('db', 'post_migrate', '20170526185842_migrate_pipeline_stages.rb') require Rails.root.join('db', 'post_migrate', '20170526185842_migrate_pipeline_stages.rb')
describe MigratePipelineStages, :migration do describe MigratePipelineStages, :migration do
...@@ -86,6 +80,56 @@ describe MigratePipelineStages, :migration do ...@@ -86,6 +80,56 @@ describe MigratePipelineStages, :migration do
end end
``` ```
## Testing a class that is not an ActiveRecord::Migration
To test a class that is not an `ActiveRecord::Migration` (a background migration),
you will need to manually provide a required schema version. Please add a
schema tag to a context that you want to switch the database schema within.
Example: `describe SomeClass, :migration, schema: 20170608152748`.
### Example
This spec tests the [`lib/gitlab/background_migration/archive_legacy_traces.rb`](https://gitlab.com/gitlab-org/gitlab-ce/blob/v11.6.5/lib/gitlab/background_migration/archive_legacy_traces.rb)
background migration. You can find the complete spec on
[`spec/lib/gitlab/background_migration/archive_legacy_traces_spec.rb`](https://gitlab.com/gitlab-org/gitlab-ce/blob/v11.6.5/spec/lib/gitlab/background_migration/archive_legacy_traces_spec.rb)
```ruby
require 'spec_helper'
describe Gitlab::BackgroundMigration::ArchiveLegacyTraces, :migration, schema: 20180529152628 do
include TraceHelpers
let(:namespaces) { table(:namespaces) }
let(:projects) { table(:projects) }
let(:builds) { table(:ci_builds) }
let(:job_artifacts) { table(:ci_job_artifacts) }
before do
namespaces.create!(id: 123, name: 'gitlab1', path: 'gitlab1')
projects.create!(id: 123, name: 'gitlab1', path: 'gitlab1', namespace_id: 123)
@build = builds.create!(id: 1, project_id: 123, status: 'success', type: 'Ci::Build')
end
context 'when trace file exsits at the right place' do
before do
create_legacy_trace(@build, 'trace in file')
end
it 'correctly archive legacy traces' do
expect(job_artifacts.count).to eq(0)
expect(File.exist?(legacy_trace_path(@build))).to be_truthy
described_class.new.perform(1, 1)
expect(job_artifacts.count).to eq(1)
expect(File.exist?(legacy_trace_path(@build))).to be_falsy
expect(File.read(archived_trace_path(job_artifacts.first))).to eq('trace in file')
end
end
end
```
## Best practices ## Best practices
1. Note that this type of tests do not run within the transaction, we use 1. Note that this type of tests do not run within the transaction, we use
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment